Skip to content

Latest commit

 

History

History
342 lines (277 loc) · 15.6 KB

on-new-compose-events-walkthrough.md

File metadata and controls

342 lines (277 loc) · 15.6 KB
Raw
title description ms.date ms.topic ms.localizationpriority
Automatically set the subject of a new message or appointment
Learn how to implement an event-based add-in that automatically sets the subject of a new message or appointment.
04/12/2024
how-to
medium

Automatically set the subject of a new message or appointment

Need to add a required disclaimer to all your messages? With an event-based add-in, content is automatically added to new messages or appointments. Your users can focus on writing, instead of compliance.

The following sections teach you how to develop an add-in that handles the OnNewMessageCompose and OnNewAppointmentOrganizer events. By the end of this walkthrough, you'll have an add-in that automatically sets the subject of new messages and appointments being created.

Note

The OnNewMessageCompose and OnNewAppointmentOrganizer events were introduced in requirement set 1.10. To verify that your Outlook client supports these events, see Requirement sets supported by Exchange servers and Outlook clients.

Set up your environment

Complete the Outlook quick start which creates an add-in project with the Yeoman generator for Office Add-ins.

Configure the manifest

To configure the manifest, select the tab for the type of manifest you're using.

Unified manifest for Microsoft 365

  1. Open the manifest.json file.

  2. Add the following object to the "extensions.runtimes" array. Note the following about this markup:

    • The "minVersion" of the Mailbox requirement set is configured to "1.10" as this is the lowest version of the requirement set that supports the OnNewMessageCompose and OnNewAppointmentOrganizer events.

    • The "id" of the runtime is set to the descriptive name "autorun_runtime".

    • The "code" property has a child "page" property that is set to an HTML file and a child "script" property that is set to a JavaScript file. You'll create or edit these files in later steps. Office uses one of these values depending on the platform.

      • Office on Windows executes the event handlers in a JavaScript-only runtime, which loads a JavaScript file directly.
      • Office on Mac and on the web, and new Outlook on Windows (preview) execute the handlers in a browser runtime, which loads an HTML file. That file, in turn, contains a <script> tag that loads the JavaScript file.

      For more information, see Runtimes in Office Add-ins.

    • The "lifetime" property is set to "short", which means that the runtime starts up when one of the events is triggered and shuts down when the handler completes. (In certain rare cases, the runtime shuts down before the handler completes. See Runtimes in Office Add-ins.)

    • There are two types of "actions" that can run in the runtime. You'll create functions to correspond to these actions in a later step.

     {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.10"
            }
        ]
    },
    "id": "autorun_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html",
        "script": "https://localhost:3000/launchevent.js"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "onNewMessageComposeHandler",
            "type": "executeFunction",
            "displayName": "onNewMessageComposeHandler"
        },
        {
            "id": "onNewAppointmentComposeHandler",
            "type": "executeFunction",
            "displayName": "onNewAppointmentComposeHandler"
        }
    ]
}

  3. Add the following "autoRunEvents" array as a property of the object in the "extensions" array.

    "autoRunEvents": [

]

  4. Add the following object to the "autoRunEvents" array. The "events" property maps handlers to events as described in the table earlier in this article. The handler names must match those used in the "id" properties of the objects in the "actions" array in an earlier step.

      {
      "requirements": {
          "capabilities": [
              {
                  "name": "Mailbox",
                  "minVersion": "1.10"
              }
          ],
          "scopes": [
              "mail"
          ]
      },
      "events": [
          {
              "type": "newMessageComposeCreated",
              "actionId": "onNewMessageComposeHandler"
          },
          {
              "type": "newAppointmentOrganizerCreated",
              "actionId": "onNewAppointmentComposeHandler"
          }
      ]
  }

XML Manifest

To enable event-based activation of your add-in, you must configure the Runtimes element and LaunchEvent extension point in the VersionOverridesV1_1 node of the manifest.

In event-based add-ins, Outlook on Windows uses a JavaScript file, while Outlook on the web and on the new Mac UI, and new Outlook on Windows (preview) use an HTML file that can reference the same JavaScript file. You must provide references to both these files in the Resources node of the manifest as the Outlook platform ultimately determines whether to use HTML or JavaScript based on the Outlook client. As such, to configure event handling, provide the location of the HTML in the <Runtime> element, then in its Override child element provide the location of the JavaScript file inlined or referenced by the HTML.

  1. In your code editor, open the quick start project.

  2. Open the manifest.xml file located at the root of your project.

  3. Select the entire <VersionOverrides> node (including open and close tags) and replace it with the following XML, then save your changes.

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    <Requirements>
      <bt:Sets DefaultMinVersion="1.10">
        <bt:Set Name="Mailbox" />
      </bt:Sets>
    </Requirements>
    <Hosts>
      <Host xsi:type="MailHost">
        <!-- Event-based activation happens in a lightweight runtime.-->
        <Runtimes>
          <!-- HTML file including reference to or inline JavaScript event handlers.
               This is used by Outlook on the web and on the new Mac UI, and new Outlook on Windows (preview). -->
          <Runtime resid="WebViewRuntime.Url">
            <!-- JavaScript file containing event handlers. This is used by Outlook on Windows. -->
            <Override type="javascript" resid="JSRuntime.Url"/>
          </Runtime>
        </Runtimes>
        <DesktopFormFactor>
          <FunctionFile resid="Commands.Url" />
          <ExtensionPoint xsi:type="MessageReadCommandSurface">
            <OfficeTab id="TabDefault">
              <Group id="msgReadGroup">
                <Label resid="GroupLabel" />
                <Control xsi:type="Button" id="msgReadOpenPaneButton">
                  <Label resid="TaskpaneButton.Label" />
                  <Supertip>
                    <Title resid="TaskpaneButton.Label" />
                    <Description resid="TaskpaneButton.Tooltip" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Icon.16x16" />
                    <bt:Image size="32" resid="Icon.32x32" />
                    <bt:Image size="80" resid="Icon.80x80" />
                  </Icon>
                  <Action xsi:type="ShowTaskpane">
                    <SourceLocation resid="Taskpane.Url" />
                  </Action>
                </Control>
                <Control xsi:type="Button" id="ActionButton">
                  <Label resid="ActionButton.Label"/>
                  <Supertip>
                    <Title resid="ActionButton.Label"/>
                    <Description resid="ActionButton.Tooltip"/>
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Icon.16x16"/>
                    <bt:Image size="32" resid="Icon.32x32"/>
                    <bt:Image size="80" resid="Icon.80x80"/>
                  </Icon>
                  <Action xsi:type="ExecuteFunction">
                    <FunctionName>action</FunctionName>
                  </Action>
                </Control>
              </Group>
            </OfficeTab>
          </ExtensionPoint>

          <!-- Can configure other command surface extension points for add-in command support. -->

          <!-- Enable launching the add-in on the included events. -->
          <ExtensionPoint xsi:type="LaunchEvent">
            <LaunchEvents>
              <LaunchEvent Type="OnNewMessageCompose" FunctionName="onNewMessageComposeHandler"/>
              <LaunchEvent Type="OnNewAppointmentOrganizer" FunctionName="onNewAppointmentComposeHandler"/>
            </LaunchEvents>
            <!-- Identifies the runtime to be used (also referenced by the Runtime element). -->
            <SourceLocation resid="WebViewRuntime.Url"/>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Icon.16x16" DefaultValue="https://localhost:3000/assets/icon-16.png"/>
        <bt:Image id="Icon.32x32" DefaultValue="https://localhost:3000/assets/icon-32.png"/>
        <bt:Image id="Icon.80x80" DefaultValue="https://localhost:3000/assets/icon-80.png"/>
      </bt:Images>
      <bt:Urls>
        <bt:Url id="Commands.Url" DefaultValue="https://localhost:3000/commands.html" />
        <bt:Url id="Taskpane.Url" DefaultValue="https://localhost:3000/taskpane.html" />
        <bt:Url id="WebViewRuntime.Url" DefaultValue="https://localhost:3000/commands.html" />
        <!-- Entry needed for Outlook on Windows. -->
        <bt:Url id="JSRuntime.Url" DefaultValue="https://localhost:3000/launchevent.js" />
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="GroupLabel" DefaultValue="Contoso Add-in"/>
        <bt:String id="TaskpaneButton.Label" DefaultValue="Show Taskpane"/>
        <bt:String id="ActionButton.Label" DefaultValue="Perform an action"/>
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="TaskpaneButton.Tooltip" DefaultValue="Opens a pane displaying all available properties."/>
        <bt:String id="ActionButton.Tooltip" DefaultValue="Perform an action when clicked."/>
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</VersionOverrides>

Tip

Implement event handling

  1. From the same quick start project, create a new folder named launchevent under the ./src directory.

  2. In the ./src/launchevent folder, create a new file named launchevent.js.

  3. Open the file ./src/launchevent/launchevent.js in your code editor and add the following JavaScript code.

    /*
* Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
* See LICENSE in the project root for license information.
*/

function onNewMessageComposeHandler(event) {
  setSubject(event);
}
function onNewAppointmentComposeHandler(event) {
  setSubject(event);
}
function setSubject(event) {
  Office.context.mailbox.item.subject.setAsync(
    "Set by an event-based add-in!",
    {
      "asyncContext": event
    },
    function (asyncResult) {
      // Handle success or error.
      if (asyncResult.status !== Office.AsyncResultStatus.Succeeded) {
        console.error("Failed to set subject: " + JSON.stringify(asyncResult.error));
      }

      // Call event.completed() to signal to the Outlook client that the add-in has completed processing the event.
      asyncResult.asyncContext.completed();
    });
}

// IMPORTANT: To ensure your add-in is supported in the Outlook client on Windows, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onNewMessageComposeHandler", onNewMessageComposeHandler);
  Office.actions.associate("onNewAppointmentComposeHandler", onNewAppointmentComposeHandler);
}

  4. Save your changes.

Note

There are some limitations you must be aware of when developing an event-based add-in for Outlook on Windows. To learn more, see Event-based activation behavior and limitations.

Update the commands HTML file

  1. In the ./src/commands folder, open commands.html.

  2. Immediately before the closing head tag (</head>), add a script entry to include the event-handling JavaScript code.

    <script type="text/javascript" src="../launchevent/launchevent.js"></script>

  3. Save your changes.

Update webpack config settings

  1. Open the webpack.config.js file found in the root directory of the project and complete the following steps.

  2. Locate the plugins array within the config object and add this new object at the beginning of the array.

    new CopyWebpackPlugin({
  patterns: [
    {
      from: "./src/launchevent/launchevent.js",
      to: "launchevent.js",
    },
  ],
}),

  3. Save your changes.

Try it out

  1. Run the following commands in the root directory of your project. When you run npm start, the local web server will start (if it's not already running) and your add-in will be sideloaded.

    npm run build

    npm start

    [!INCLUDE outlook-manual-sideloading]

  2. In Outlook on the web or in new Outlook on Windows (preview), create a new message.

    A message window in Outlook on the web with the subject set on compose.

  3. In Outlook on the new Mac UI, create a new message.

    A message window in Outlook on the new Mac UI with the subject set on compose.

  4. In Outlook on Windows, create a new message.

    A message window in Outlook on Windows with the subject set on compose.

Next steps

To learn more about event-based activation and other events that you can implement in your add-in, see Configure your Outlook add-in for event-based activation.

See also