在 Outlook 移动加载项中将约会笔记记录到外部应用程序

项目
02/29/2024

将约会笔记和其他详细信息保存到客户关系管理 (CRM) 或记笔记应用程序有助于跟踪已参加的会议。

本文介绍如何设置 Outlook 移动加载项，使用户能够将有关其约会的笔记和其他详细信息记录到 CRM 或记笔记应用程序中。在本文中，我们将使用名为“Contoso”的虚构 CRM 服务提供商。

支持的客户端

Android 版 Outlook 和 iOS 上的 Microsoft 365 订阅支持从 Outlook 移动加载项将笔记记录到外部应用程序。

设置环境

完成 Outlook 快速入门，使用 Office 外接程序的 Yeoman 生成器创建外接程序项目。

捕获和查看约会笔记

可以选择实现函数命令或任务窗格。若要更新加载项，请选择函数命令或任务窗格的选项卡，然后按照说明进行操作。

函数命令
任务窗格

当用户从功能区选择函数命令时，此选项将允许用户记录和查看其笔记和其他有关其约会的详细信息。

配置清单

若要使用户能够使用外接程序记录约会笔记，必须在父元素 MobileFormFactor下的清单中配置 MobileLogEventAppointmentAttendee 扩展点。不支持其他外形规格。

注意

移动设备目前不支持使用 Microsoft 365 统一清单 (预览版) 的外接程序。

在代码编辑器中，打开快速入门项目。
打开位于项目根目录处的 manifest.xml 文件。

选择整个 <VersionOverrides> 节点 (包括打开和关闭标记) ，并将其替换为以下 XML。请确保将对 Contoso 的所有引用替换为公司的信息。

<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">
    <Description resid="residDescription"></Description>
    <Requirements>
      <bt:Sets>
        <bt:Set Name="Mailbox" MinVersion="1.3"/>
      </bt:Sets>
    </Requirements>
    <Hosts>
      <Host xsi:type="MailHost">
        <DesktopFormFactor>
          <FunctionFile resid="residFunctionFile"/>
          <ExtensionPoint xsi:type="AppointmentAttendeeCommandSurface">
            <OfficeTab id="TabDefault">
              <Group id="apptReadGroup">
                <Label resid="residDescription"/>
                <Control xsi:type="Button" id="apptReadOpenPaneButton">
                  <Label resid="residLabel"/>
                  <Supertip>
                    <Title resid="residLabel"/>
                    <Description resid="residTooltip"/>
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="icon-16"/>
                    <bt:Image size="32" resid="icon-32"/>
                    <bt:Image size="80" resid="icon-80"/>
                  </Icon>
                  <Action xsi:type="ExecuteFunction">
                    <FunctionName>logCRMEvent</FunctionName>
                  </Action>
                </Control>
              </Group>
            </OfficeTab>
          </ExtensionPoint>
        </DesktopFormFactor>
        <MobileFormFactor>
          <FunctionFile resid="residFunctionFile"/>
          <ExtensionPoint xsi:type="MobileLogEventAppointmentAttendee">
            <Control xsi:type="MobileButton" id="appointmentReadFunctionButton">
              <Label resid="residLabel"/>
              <Icon>
                <bt:Image size="25" scale="1" resid="icon-16"/>
                <bt:Image size="25" scale="2" resid="icon-16"/>
                <bt:Image size="25" scale="3" resid="icon-16"/>
                <bt:Image size="32" scale="1" resid="icon-32"/>
                <bt:Image size="32" scale="2" resid="icon-32"/>
                <bt:Image size="32" scale="3" resid="icon-32"/>
                <bt:Image size="48" scale="1" resid="icon-48"/>
                <bt:Image size="48" scale="2" resid="icon-48"/>
                <bt:Image size="48" scale="3" resid="icon-48"/>
              </Icon>
              <Action xsi:type="ExecuteFunction">
                <FunctionName>logCRMEvent</FunctionName>
              </Action>
            </Control>
          </ExtensionPoint>
        </MobileFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="icon-16" DefaultValue="https://contoso.com/assets/icon-16.png"/>
        <bt:Image id="icon-32" DefaultValue="https://contoso.com/assets/icon-32.png"/>
        <bt:Image id="icon-48" DefaultValue="https://contoso.com/assets/icon-48.png"/>
        <bt:Image id="icon-80" DefaultValue="https://contoso.com/assets/icon-80.png"/>
      </bt:Images>
      <bt:Urls>
        <bt:Url id="residFunctionFile" DefaultValue="https://contoso.com/commands.html"/>
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="residDescription" DefaultValue="Log appointment notes and other details to Contoso CRM."/>
        <bt:String id="residLabel" DefaultValue="Log to Contoso CRM"/>
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="residTooltip" DefaultValue="Log notes to Contoso CRM for this appointment."/>
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</VersionOverrides>

提示

若要了解有关 Outlook 外接程序清单的详细信息，请参阅 Office 加载项清单和在移动设备上的 Outlook 中添加对外接程序命令的支持。

捕获约会笔记

在本部分中，了解当用户选择“ 日志 ”按钮时，外接程序如何提取约会详细信息。

在同一快速入门项目中，在代码编辑器中打开文件 ./src/commands/commands.js 。

将 commands.js 文件的全部内容替换为以下 JavaScript。

var event;

Office.initialize = function (reason) {
  // Add any initialization code here.
};

function logCRMEvent(appointmentEvent) {
  event = appointmentEvent;
  console.log(`Subject: ${Office.context.mailbox.item.subject}`);
  Office.context.mailbox.item.body.getAsync(
    "html",
    { asyncContext: "This is passed to the callback" },
    function callback(result) {
      if (result.status === Office.AsyncResultStatus.Succeeded) {
        event.completed({ allowEvent: true });
      } else {
        console.error("Failed to get body.");
        event.completed({ allowEvent: false });
      }
    }
  );
}

// Register the function.
Office.actions.associate("logCRMEvent", logCRMEvent);

接下来，更新 commands.html 文件以引用 commands.js。

在同一快速入门项目中，在代码编辑器中打开 ./src/commands/commands.html 文件。

查找并替换为 <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script> 以下内容：

<script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>
<script type="text/javascript" src="commands.js"></script>

查看约会笔记

可以通过设置为此目的保留的 EventLogged 自定义属性来切换“日志”按钮标签以显示“视图”。当用户选择“ 查看 ”按钮时，他们可以查看此约会的记录笔记。

加载项定义日志查看体验。例如，当用户选择“ 查看 ”按钮时，可以在对话框中显示记录的约会笔记。有关使用对话框的详细信息，请参阅在 Office 外接程序中使用 Office 对话框 API。

将以下函数添加到 ./src/commands/commands.js。此函数设置当前约会项上的 EventLogged 自定义属性。

function updateCustomProperties() {
  Office.context.mailbox.item.loadCustomPropertiesAsync(
    function callback(customPropertiesResult) {
      if (customPropertiesResult.status === Office.AsyncResultStatus.Succeeded) {
        let customProperties = customPropertiesResult.value;
        customProperties.set("EventLogged", true);
        customProperties.saveAsync(
          function callback(setSaveAsyncResult) {
            if (setSaveAsyncResult.status === Office.AsyncResultStatus.Succeeded) {
              console.log("EventLogged custom property saved successfully.");
              event.completed({ allowEvent: true });
              event = undefined;
            }
          }
        );
      }
    }
  );
}

然后，在加载项成功记录约会笔记后调用它。例如，可以从 logCRMEvent 调用它，如以下函数所示。

function logCRMEvent(appointmentEvent) {
  event = appointmentEvent;
  console.log(`Subject: ${Office.context.mailbox.item.subject}`);
  Office.context.mailbox.item.body.getAsync(
    "html",
    { asyncContext: "This is passed to the callback" },
    function callback(result) {
      if (result.status === Office.AsyncResultStatus.Succeeded) {
        // Replace `event.completed({ allowEvent: true });` with the following statement.
        updateCustomProperties();
      } else {
        console.error("Failed to get body.");
        event.completed({ allowEvent: false });
      }
    }
  );
}

删除约会日志

如果你想要让用户撤消日志记录或删除记录的约会笔记，以便可以保存替换日志，你有两个选项。

当用户选择功能区上的相应按钮时，使用 Microsoft Graph 清除自定义属性对象。

将以下函数添加到 ./src/commands/commands.js 以清除当前约会项上的 EventLogged 自定义属性。

function clearCustomProperties() {
  Office.context.mailbox.item.loadCustomPropertiesAsync(
    function callback(customPropertiesResult) {
      if (customPropertiesResult.status === Office.AsyncResultStatus.Succeeded) {
        var customProperties = customPropertiesResult.value;
        customProperties.remove("EventLogged");
        customProperties.saveAsync(
          function callback(removeSaveAsyncResult) {
            if (removeSaveAsyncResult.status === Office.AsyncResultStatus.Succeeded) {
              console.log("Custom properties cleared");
              event.completed({ allowEvent: true });
              event = undefined;
            }
          }
        );
      }
    }
  );
}

然后，在要清除自定义属性时调用它。例如，如果设置日志以某种方式失败，可以从 logCRMEvent 调用它，如以下函数所示。

function logCRMEvent(appointmentEvent) {
  event = appointmentEvent;
  console.log(`Subject: ${Office.context.mailbox.item.subject}`);
  Office.context.mailbox.item.body.getAsync(
    "html",
    { asyncContext: "This is passed to the callback" },
    function callback(result) {
      if (result.status === Office.AsyncResultStatus.Succeeded) {
        updateCustomProperties();
      } else {
        console.error("Failed to get body.");
        // Replace `event.completed({ allowEvent: false });` with the following statement.
        clearCustomProperties();
      }
    }
  );
}

此选项将使用户能够从任务窗格记录和查看其笔记以及有关其约会的其他详细信息。

配置清单

若要使用户能够使用外接程序记录约会笔记，必须在父元素 MobileFormFactor下的清单中配置 MobileLogEventAppointmentAttendee 扩展点。不支持其他外形规格。

注意

移动设备目前不支持使用 Microsoft 365 统一清单 (预览版) 的外接程序。

在代码编辑器中，打开快速入门项目。
打开位于项目根目录处的 manifest.xml 文件。

选择整个 <VersionOverrides> 节点 (包括打开和关闭标记) ，并将其替换为以下 XML。请确保将对 Contoso 的所有引用替换为公司的信息。

<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">
    <Description resid="residDescription"></Description>
      <Requirements>
        <bt:Sets>
          <bt:Set Name="Mailbox" MinVersion="1.3"/>
        </bt:Sets>
      </Requirements>
      <Hosts>
        <Host xsi:type="MailHost">
          <DesktopFormFactor>
            <ExtensionPoint xsi:type="AppointmentAttendeeCommandSurface">
              <OfficeTab id="TabDefault">
                <Group id="apptReadGroup">
                  <Label resid="residDescription"/>
                  <Control xsi:type="Button" id="apptReadOpenPaneButton">
                    <Label resid="residLabel"/>
                    <Supertip>
                      <Title resid="residLabel"/>
                      <Description resid="residTooltip"/>
                    </Supertip>
                    <Icon>
                      <bt:Image size="16" resid="icon-16"/>
                      <bt:Image size="32" resid="icon-32"/>
                      <bt:Image size="80" resid="icon-80"/>
                    </Icon>
                    <Action xsi:type="ShowTaskpane">
                      <SourceLocation resid="Taskpane.Url"/>
                    </Action>
                  </Control>
                </Group>
              </OfficeTab>
            </ExtensionPoint>
          </DesktopFormFactor>
          <MobileFormFactor>
            <ExtensionPoint xsi:type="MobileLogEventAppointmentAttendee">
              <Control xsi:type="MobileButton" id="appointmentReadFunctionButton">
                <Label resid="residLabel"/>
                <Icon>
                  <bt:Image size="25" scale="1" resid="icon-16"/>
                  <bt:Image size="25" scale="2" resid="icon-16"/>
                  <bt:Image size="25" scale="3" resid="icon-16"/>

                  <bt:Image size="32" scale="1" resid="icon-32"/>
                  <bt:Image size="32" scale="2" resid="icon-32"/>
                  <bt:Image size="32" scale="3" resid="icon-32"/>

                  <bt:Image size="48" scale="1" resid="icon-48"/>
                  <bt:Image size="48" scale="2" resid="icon-48"/>
                  <bt:Image size="48" scale="3" resid="icon-48"/>
                </Icon>
                <Action xsi:type="ShowTaskpane">
                  <SourceLocation resid="Taskpane.Url"/>
                </Action> 
              </Control>
            </ExtensionPoint>
          </MobileFormFactor>
        </Host>
      </Hosts>
      <Resources>
        <bt:Images>
          <bt:Image id="icon-16" DefaultValue="https://contoso.com/assets/icon-16.png"/>
          <bt:Image id="icon-32" DefaultValue="https://contoso.com/assets/icon-32.png"/>
          <bt:Image id="icon-48" DefaultValue="https://contoso.com/assets/icon-48.png"/>
          <bt:Image id="icon-80" DefaultValue="https://contoso.com/assets/icon-80.png"/>
        </bt:Images>
        <bt:Urls>
          <bt:Url id="residFunctionFile" DefaultValue="https://contoso.com/commands.html"/>
          <bt:Url id="Taskpane.Url" DefaultValue="https://contoso.com/taskpane.html"/>
        </bt:Urls>
        <bt:ShortStrings>
          <bt:String id="residDescription" DefaultValue="Log appointment notes and other details to Contoso CRM."/>
          <bt:String id="residLabel" DefaultValue="Log to Contoso CRM"/>
        </bt:ShortStrings>
        <bt:LongStrings>
          <bt:String id="residTooltip" DefaultValue="Log notes to Contoso CRM for this appointment."/>
        </bt:LongStrings>
      </Resources>
    </VersionOverrides>
</VersionOverrides>

提示

若要了解有关 Outlook 外接程序清单的详细信息，请参阅 Office 加载项清单和在移动设备上的 Outlook 中添加对外接程序命令的支持。

捕获约会笔记

在本部分中，了解如何在用户选择“ 日志 ”按钮时在任务窗格中显示记录的约会笔记和其他详细信息。

在同一快速入门项目中，在代码编辑器中打开文件 ./src/taskpane/taskpane.js 。

将 taskpane.js 文件的全部内容替换为以下 JavaScript。

// Office is ready.
Office.onReady(function () {
    getEventData();
  }
);

function getEventData() {
  console.log(`Subject: ${Office.context.mailbox.item.subject}`);
  Office.context.mailbox.item.body.getAsync(
    "html",
    function callback(result) {
      if (result.status === Office.AsyncResultStatus.Succeeded) {
        console.log("event logged successfully");
      } else {
        console.error("Failed to get body.");
      }
    }
  );
}

接下来，更新 taskpane.html 文件以引用 taskpane.js。

在同一快速启动项目中，在代码编辑器中打开 ./src/taskpane/taskpane.html 文件。

查找并替换为 <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script> 以下内容：

<script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>
<script type="text/javascript" src="taskpane.js"></script>

查看约会笔记

可以通过设置为此目的保留的 EventLogged 自定义属性来切换“日志”按钮标签以显示“视图”。当用户选择“ 查看 ”按钮时，他们可以查看此约会的记录笔记。加载项定义日志查看体验。

将以下函数添加到 ./src/taskpane/taskpane.js。此函数设置当前约会项上的 EventLogged 自定义属性。

function updateCustomProperties() {
  Office.context.mailbox.item.loadCustomPropertiesAsync(
    function callback(customPropertiesResult) {
      if (customPropertiesResult.status === Office.AsyncResultStatus.Succeeded) {
        let customProperties = customPropertiesResult.value;
        customProperties.set("EventLogged", true);
        customProperties.saveAsync(
          function callback(setSaveAsyncResult) {
            if (setSaveAsyncResult.status === Office.AsyncResultStatus.Succeeded) {
              console.log("EventLogged custom property saved successfully.");
            }
          }
        );
      }
    }
  );
}

然后，在加载项成功记录约会笔记后调用它。例如，可以从 getEventData 调用它，如以下函数所示。

function getEventData() {
  console.log(`Subject: ${Office.context.mailbox.item.subject}`);
  Office.context.mailbox.item.body.getAsync(
    "html",
    function callback(result) {
      if (result.status === Office.AsyncResultStatus.Succeeded) {
        console.log("event logged successfully");
        updateCustomProperties();
      } else {
        console.error("Failed to get body.");
      }
    }
  );
}

删除约会日志

如果你想要让用户撤消日志记录或删除记录的约会笔记，以便可以保存替换日志，你有两个选项。

当用户在任务窗格中选择相应的按钮时，使用 Microsoft Graph 清除自定义属性对象。

将以下函数添加到 ./src/taskpane/taskpane.js 以清除当前约会项上的 EventLogged 自定义属性。

function clearCustomProperties() {
  Office.context.mailbox.item.loadCustomPropertiesAsync(
    function callback(customPropertiesResult) {
      if (customPropertiesResult.status === Office.AsyncResultStatus.Succeeded) {
        var customProperties = customPropertiesResult.value;
        customProperties.remove("EventLogged");
        customProperties.saveAsync(
          function callback(removeSaveAsyncResult) {
            if (removeSaveAsyncResult.status === Office.AsyncResultStatus.Succeeded) {
              console.log("Custom properties cleared");
            }
          }
        );
      }
    }
  );
}

然后，在要清除自定义属性时调用它。例如，如果设置日志以某种方式失败，可以从 getEventData 调用它，如以下函数所示。

function getEventData() {
  console.log(`Subject: ${Office.context.mailbox.item.subject}`);
  Office.context.mailbox.item.body.getAsync(
    "html",
    function callback(result) {
      if (result.status === Office.AsyncResultStatus.Succeeded) {
        console.log("event logged successfully");
        updateCustomProperties();
      } else {
        console.error("Failed to get body.");
        clearCustomProperties();
      }
    }
  );
}

测试和验证

按照常规指南测试和验证加载项。
在Outlook 网页版旁加载加载项后，在 Windows (经典版或新的 (预览版) ) ，或者在 Mac 上重启 Android 或 iOS 移动设备上的 Outlook。
以与会者身份打开约会，然后验证在“会议见解”卡下，是否有一个新的卡，其中包含加载项的名称以及“日志”按钮。

UI：记录约会笔记

作为与会者，打开会议时，应会看到类似于下图的屏幕。

Android 上的约会屏幕上的“日志”按钮。

UI：查看约会日志

成功记录约会笔记后，按钮现在应标记为 “视图 ”而不是 “日志”。应会看到类似于下图的屏幕。

Android 上的约会屏幕上的“查看”按钮。

可用 API

以下 API 可用于此功能。

若要详细了解移动设备上的 Outlook 支持的 API，请参阅移动设备上的 Outlook 支持的 Outlook JavaScript API。

限制

存在一些限制。

无法更改 “日志 ”按钮名称。但是，可以通过在约会项上设置自定义属性来显示不同的标签。有关更多详细信息，请参阅函数命令或任务窗格的“查看约会说明”部分（如果适用）。
如果要将“日志”按钮的标签切换为“查看并返回”，则必须使用 EventLogged 自定义属性。
加载项图标应采用灰度，使用十六进制代码 #919191 或其等效的其他颜色格式。
加载项应在一分钟的超时期限内从约会表单中提取会议详细信息。但是，例如，在打开加载项进行身份验证的对话框中花费的任何时间都排除在超时期限之外。

在 Outlook 移动加载项中将约会笔记记录到外部应用程序

支持的客户端

设置环境

捕获和查看约会笔记

配置清单

捕获约会笔记

查看约会笔记

删除约会日志

配置清单

捕获约会笔记

查看约会笔记

删除约会日志

测试和验证

UI：记录约会笔记

UI：查看约会日志

可用 API

限制

另请参阅

反馈

其他资源