Запись заметок о встречах во внешнее приложение в надстройках Outlook для мобильных устройств

  • Статья

Сохранение заметок о встречах и других сведений в crm-приложении или приложении для создания заметок поможет вам отслеживать собрания, на которые вы присутствовали.

Из этой статьи вы узнаете, как настроить мобильную надстройку Outlook, чтобы пользователи могли записывать заметки и другие сведения о своих встречах в CRM или приложении для создания заметок. В этой статье мы будем использовать вымышленного поставщика услуг CRM с именем Contoso.

Вы можете реализовать команду функции или надстройку области задач. С помощью реализации команды функции пользователи могут записывать и просматривать заметки и другие сведения о своих встречах при нажатии кнопки надстройки. С помощью реализации области задач пользователи могут напрямую управлять заметками о встречах из интерфейса области задач. Следуя инструкциям в этой статье, выберите вкладку для типа разрабатываемой надстройки.

Поддерживаемые клиенты

Ведение заметок во внешнее приложение из мобильной надстройки Outlook поддерживается в Outlook для Android и в iOS с подпиской Microsoft 365.

Настройка среды

Выполните краткое руководство по созданию проекта надстройки с помощью генератора Yeoman для надстроек Office.

Настройка манифеста

Чтобы настроить манифест надстройки, выберите тип манифеста, который вы используете.

Унифицированный манифест для Microsoft 365

  1. Откройте проект быстрого запуска в редакторе кода.

  2. Откройте файл manifest.json , расположенный в корне проекта.

  3. В массиве authorization.permissions.resourceSpecific найдите первый объект и задайте для его свойства name значение MailboxItem.ReadWrite.User. По завершении он должен выглядеть следующим образом.

    {
    "name": "MailboxItem.ReadWrite.User",
    "type": "Delegated"
}

  4. Убедитесь, что в массиве validDomains включен URL-адрес https://www.contoso.com . По завершении массив должен выглядеть следующим образом.

    "validDomains": [
    "https://www.contoso.com"
],

  5. В массиве extensions.runtimes удалите объект, идентификатор которого имеет значение TaskPaneRuntime.

  6. В том же массиве перейдите к оставшемуся объекту, идентификатор которого имеет значение CommandsRuntime, и замените его следующим объектом.

    {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.3"
            }
        ]
    },
    "id": "CommandsRuntime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html",
        "script": "https://localhost:3000/commands.js"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "logCRMEvent",
            "type": "executeFunction"
        }
    ]
}

  7. В массиве ribbons замените существующий объект следующим кодом. Обратите внимание на следующие сведения об этих изменениях.

    • Значения "desktop" и "mobile" в массиве "ribbons.requirements.formFactors" настраивают кнопку Log to Contoso CRM , чтобы она отображалась в Outlook на мобильных устройствах и в настольных клиентах.
    • Значение logEventMeetingDetailsAttendee в массиве contexts настраивает кнопку надстройки для отображения в области Участники встречи, чтобы пользователи могли регистрировать свои заметки о встрече.
    • Объект в массиве ribbons.tabs.groups.controls настраивает кнопку надстройки, которая вызывает функцию ведения журнала заметок в классических клиентах Outlook. Свойство actionId должно соответствовать actions.id объекта в массиве extensions.runtimes.
    • Объект в массиве ribbons.tabs.customMobileRibbonGroups настраивает кнопку надстройки, которая вызывает функцию ведения журнала заметок в Outlook на мобильных устройствах. Для мобильной кнопки требуются все девять объектов, указанных в массиве customMobileRibbonGroups.controls.icons. Кроме того, свойство customMobileRibbonGroups.controls.actionId должно соответствовать actions.id объекта в массиве extensions.runtimes.
    {
    "requirements": {
        "formFactors": [
            "desktop",
            "mobile"
        ]
    },
    "contexts": [
        "logEventMeetingDetailsAttendee"
    ],
    "tabs": [
        {
            "builtInTabId": "TabDefault",
            "groups": [
                {
                    "id": "apptReadGroup",
                    "label": "Contoso Add-in",
                    "icons": [
                        {
                            "size": 16,
                            "url": "https://localhost:3000/assets/icon-16.png"
                        },
                        {
                            "size": 32,
                            "url": "https://localhost:3000/assets/icon-32.png"
                        },
                        {
                            "size": 80,
                            "url": "https://localhost:3000/assets/icon-80.png"
                        }
                    ],
                    "controls": [
                        {
                            "id": "desktopLogToCRM",
                            "type": "button",
                            "label": "Log to Contoso CRM",
                            "icons": [
                                {
                                    "size": 16,
                                    "url": "https://www.contoso.com/assets/icon-16.png"
                                },
                                {
                                    "size": 32,
                                    "url": "https://www.contoso.com/assets/icon-32.png"
                                },
                                {
                                    "size": 80,
                                    "url": "https://www.contoso.com/assets/icon-80.png"
                                }
                            ],
                            "supertip": {
                                "title": "Log to Contoso CRM",
                                "description": "Log notes to Contoso CRM for this appointment."
                            },
                            "actionId": "logCRMEvent"
                        }
                    ]
                }
            ],
            "customMobileRibbonGroups": [
                {
                    "id": "mobileApptReadGroup",
                    "label": "Contoso Add-in",
                    "controls": [
                        {
                            "id": "mobileLogToCRM",
                            "label": "Log to Contoso CRM",
                            "buttonType": "MobileButton",
                            "icons": [
                                {
                                    "scale": 1,
                                    "size": 25,
                                    "url": "https://contoso.com/assets/icon-25.png"
                                },
                                {
                                    "scale": 1,
                                    "size": 32,
                                    "url": "https://contoso.com/assets/icon-32.png"
                                },
                                {
                                    "scale": 1,
                                    "size": 48,
                                    "url": "https://contoso.com/assets/icon-48.png"
                                },                                
                                {
                                    "scale": 2,
                                    "size": 25,
                                    "url": "https://contoso.com/assets/icon-25.png"
                                },
                                {
                                    "scale": 2,
                                    "size": 32,
                                    "url": "https://contoso.com/assets/icon-32.png"
                                },
                                {
                                    "scale": 2,
                                    "size": 48,
                                    "url": "https://contoso.com/assets/icon-48.png"
                                },                                
                                {
                                    "scale": 3,
                                    "size": 25,
                                    "url": "https://contoso.com/assets/icon-25.png"
                                },
                                {
                                    "scale": 3,
                                    "size": 32,
                                    "url": "https://contoso.com/assets/icon-32.png"
                                },
                                {
                                    "scale": 3,
                                    "size": 48,
                                    "url": "https://contoso.com/assets/icon-48.png"
                                }
                            ],
                            "actionId": "logCRMEvent"
                        }
                    ]
                }
            ]
        }
    ]
}

  8. Сохраните изменения.

XML-манифест

Чтобы разрешить пользователям регистрировать заметки о встречах в надстройке, необходимо настроить точку расширения MobileLogEventAppointmentAttendee в манифесте под родительским элементом MobileFormFactor. Другие форм-факторы не поддерживаются.

  1. Откройте проект быстрого запуска в редакторе кода.

  2. Откройте файлmanifest.xml , расположенный в корне проекта.

  3. Выберите весь <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"/>
          <!-- Configures the add-in button to appear in the Appointment Attendee surface of Outlook desktop clients. -->
          <ExtensionPoint xsi:type="AppointmentAttendeeCommandSurface">
            <OfficeTab id="TabDefault">
              <Group id="apptReadGroup">
                <Label resid="residDescription"/>
                <Control xsi:type="Button" id="apptReadDesktopFunctionButton">
                  <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"/>
          <!-- Configures the add-in button to appear in the Appointment Attendee surface of Outlook on mobile devices. -->
          <ExtensionPoint xsi:type="MobileLogEventAppointmentAttendee">
            <Control xsi:type="MobileButton" id="apptReadMobileFunctionButton">
              <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>

  4. Сохраните изменения.

Совет

Дополнительные сведения о манифестах надстроек Outlook см. в разделах Манифесты надстроек Office и Добавление поддержки команд надстроек в Outlook на мобильных устройствах.

Запись заметок о встречах

В этом разделе вы узнаете, как надстройка может извлекать сведения о встрече, когда пользователь нажимает кнопку Журнал .

  1. В том же проекте быстрого запуска откройте файл ./src/commands/commands.js в редакторе кода.

  2. Замените все содержимое файлаcommands.js следующим кодом JavaScript.

    let event;

// Add start-up logic code to the onReady function, if any.
Office.onReady();

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" },
    (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);

  3. Сохраните изменения.

  4. Откройте файл ./src/commands/commands.html проекта надстройки.

  5. Найдите <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>и добавьте следующий код после него. При этом будет добавлена ссылка на файлcommands.js .

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

  6. Сохраните изменения.

Просмотр заметок о встрече

Метку кнопки Журнал можно переключить для отображения представления , задав настраиваемое свойство EventLogged, зарезервированное для этой цели. Когда пользователь нажимает кнопку Вид , он может просмотреть зарегистрированные заметки для этой встречи.

Ваша надстройка определяет процесс просмотра журналов. Например, в реализации команды функции можно отобразить записанные заметки о встрече в диалоговом окне, когда пользователь нажимает кнопку Вид . Дополнительные сведения о реализации диалогов см. в статье Использование API диалогов Office в надстройках Office.

  1. В ./src/commands/commands.jsдобавьте следующую функцию. Эта функция задает пользовательское свойство EventLogged для текущего элемента встречи.

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

  2. Сохраните изменения.

  3. Вызовите функцию updateCustomProperties после того, как надстройка успешно зановит заметки о встрече. Например, его можно вызвать из 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" },
    (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 для очистки объекта пользовательских свойств , когда пользователь нажимает соответствующую кнопку в области задач.
  • Create функцию для очистки настраиваемого свойства EventLogged для текущего элемента встречи (показано в следующем примере).

  1. В ./src/commands/commands.jsдобавьте следующую функцию, чтобы очистить пользовательское свойство EventLogged для текущего элемента встречи.

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

  2. Сохраните изменения.

  3. Вызовите функцию clearCustomProperties , если требуется очистить пользовательское свойство. Например, его можно вызвать из 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" },
    (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();
      }
    }
  );
}

Тестирование и проверка

  1. Следуйте обычному руководству, чтобы протестировать и проверить надстройку.
  2. После загрузки неопубликованного Outlook в Интернете надстройки в Windows (классическая или новая версия (предварительная версия)) или на Mac перезапустите Outlook на мобильном устройстве с Android или iOS.
  3. Откройте встречу в качестве участника, а затем убедитесь, что в карта Аналитика собраний есть новый карта с именем вашей надстройки рядом с кнопкой Журнал.

Пользовательский интерфейс: запись заметок о встрече

При открытии собрания вы должны увидеть экран, аналогичный приведенному ниже.

Кнопка

Пользовательский интерфейс: просмотр журнала встреч

После успешного ведения журнала заметок о встрече кнопка теперь должна быть помечена как Вид , а не Журнал. Вы увидите экран, аналогичный следующему изображению.

Кнопка Просмотреть на экране встречи в Android.

Доступные API

Для этой функции доступны следующие API.

Дополнительные сведения об API-интерфейсах, поддерживаемых в Outlook на мобильных устройствах, см. в статье API JavaScript, поддерживаемые в Outlook на мобильных устройствах.

Ограничения

Применяется несколько ограничений.

  • Не удается изменить имя кнопки "Журнал ". Однако можно отобразить другую метку, задав настраиваемое свойство для элемента встречи. Дополнительные сведения см. в разделе Просмотр заметок о встрече.
  • Пользовательское свойство EventLogged необходимо использовать, если вы хотите переключить метку кнопки Журнал в режим "Вид " и "Назад".
  • Значок надстройки должен быть в оттенках серого с использованием шестнадцатеричного кода #919191 или его эквивалента в других цветовых форматах.
  • Надстройка должна извлечь сведения о собрании из формы встречи в течение одной минуты времени ожидания. Однако любое время, затраченное в диалоговом окне надстройки, открытой для проверки подлинности, например, исключается из периода ожидания.

См. также