Compartilhar via

Anotações de compromisso de log para um aplicativo externo nos suplementos móveis do Outlook

  • Artigo

Salvar suas anotações de compromisso e outros detalhes em um CRM (gerenciamento de relacionamento com o cliente) ou aplicativo de observação pode ajudá-lo a acompanhar as reuniões que você participou.

Neste artigo, você aprenderá a configurar seu suplemento móvel do Outlook para permitir que os usuários registrem anotações e outros detalhes sobre seus compromissos no SEU CRM ou aplicativo de anotação. Ao longo deste artigo, usaremos um provedor de serviços crm fictício chamado "Contoso".

Você pode optar por implementar um comando de função ou suplemento de painel de tarefas. Com uma implementação de comando de função, os usuários podem fazer log e exibir anotações e outros detalhes sobre seus compromissos ao selecionar o botão de suplemento. Com uma implementação do painel de tarefas, os usuários podem gerenciar diretamente suas anotações de compromisso de uma interface do painel de tarefas. Ao seguir as instruções deste artigo, selecione a guia para o tipo de suplemento que você está desenvolvendo.

Clientes com suporte

Há suporte para anotações em log em um aplicativo externo de um suplemento móvel do Outlook no Outlook no Android e no iOS com uma assinatura do Microsoft 365.

Configurar seu ambiente

Conclua o início rápido do Outlook para criar um projeto de suplemento com o gerador Yeoman para Suplementos do Office.

Configurar o manifesto

Para configurar o manifesto do suplemento, selecione o tipo de manifesto que você está usando.

Manifesto unificado para o Microsoft 365

  1. Abra o projeto de início rápido no editor de código.

  2. Abra o arquivo manifest.json localizado na raiz do projeto.

  3. Na matriz "authorization.permissions.resourceSpecific", localize o primeiro objeto e defina sua propriedade "name" como "MailboxItem.ReadWrite.User". Deve se parecer com o seguinte quando você terminar.

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

  4. Na matriz "validDomains", verifique se a URL a ser https://www.contoso.com incluída. A matriz deve se parecer com a seguinte quando você terminar.

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

  5. Na matriz "extensions.runtimes", exclua o objeto cuja "id" está definida como "TaskPaneRuntime".

  6. Na mesma matriz, navegue até o objeto restante, cuja "id" está definida como "CommandsRuntime" e substitua-a pelo objeto a seguir.

    {
    "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. Na matriz "faixas de opções", substitua o objeto existente pelo código a seguir. Observe o seguinte sobre essas alterações.

    • Os valores "desktop" e "mobile" na matriz "ribbons.requirements.formFactors" configuram o botão Log to Contoso CRM para aparecer no Outlook em dispositivos móveis e em clientes da área de trabalho.
    • O valor "logEventMeetingDetailsAttendee" na matriz "contextos" configura o botão de suplemento a ser exibido na superfície Participante do Compromisso, para que os usuários possam registrar suas anotações de compromisso.
    • O objeto na matriz "ribbons.tabs.groups.controls" configura o botão de suplemento que chama a função de registro em log de notas em clientes da área de trabalho do Outlook. A propriedade "actionId" deve corresponder ao "actions.id" do objeto na matriz "extensions.runtimes".
    • O objeto na matriz "ribbons.tabs.customMobileRibbonGroups" configura o botão de suplemento que chama a função de registro em log de notas no Outlook em dispositivos móveis. Todos os nove objetos especificados na matriz "customMobileRibbonGroups.controls.icons" são necessários para um botão móvel. Além disso, a propriedade "customMobileRibbonGroups.controls.actionId" deve corresponder à "actions.id" do objeto na matriz "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. Salve suas alterações.

Manifesto XML

Para permitir que os usuários registrem anotações de compromisso com seu suplemento, você deve configurar o ponto de extensão MobileLogEventAppointmentAttendee no manifesto no elemento MobileFormFactorpai . Não há suporte para outros fatores de formulário.

  1. Abra o projeto de início rápido no editor de código.

  2. Abra o arquivo manifest.xml localizado na raiz do projeto.

  3. Selecione o nó inteiro <VersionOverrides> (incluindo marcas abertas e fechadas) e substitua-o pelo XML a seguir. Substitua todas as referências à Contoso por informações da sua empresa.

    <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. Salve suas alterações.

Dica

Para saber mais sobre manifestos para suplementos do Outlook, confira Manifestos de suplementos do Office e Adicionar suporte para comandos de suplemento no Outlook em dispositivos móveis.

Capturar anotações de compromisso

Nesta seção, saiba como seu suplemento pode extrair detalhes do compromisso quando o usuário seleciona o botão Log .

  1. No mesmo projeto de início rápido, abra o arquivo ./src/commands/commands.js no editor de código.

  2. Substitua todo o conteúdo do arquivocommands.js pelo JavaScript a seguir.

    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. Salve suas alterações.

  4. Abra o arquivo ./src/commands/commands.html do seu projeto de suplemento.

  5. Localize <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>, em seguida, adicione o código a seguir depois dele. Isso adiciona uma referência ao arquivo commands.js .

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

  6. Salve suas alterações.

Exibir anotações de compromisso

O rótulo do botão Log pode ser alternado para exibir Exibição definindo a propriedade personalizada EventLogged reservada para essa finalidade. Quando o usuário seleciona o botão Exibir , ele pode examinar suas anotações registradas para este compromisso.

Seu suplemento define a experiência de exibição de log. Por exemplo, em uma implementação de comando de função, você pode exibir as anotações de compromisso registradas em uma caixa de diálogo quando o usuário selecionar o botão Exibir . Para obter detalhes sobre como implementar caixas de diálogo, consulte Usar a API de diálogo do Office em seus Suplementos do Office.

  1. Em ./src/commands/commands.js, adicione a função a seguir. Essa função define a propriedade personalizada EventLogged no item de compromisso atual.

    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. Salve suas alterações.

  3. Chame a função updateCustomProperties após o suplemento registrar com êxito as anotações de compromisso. Por exemplo, você pode chamá-lo do logCRMEvent , conforme mostrado no código a seguir.

    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 });
      }
    }
  );
}

Excluir o log de compromisso

Se você quiser que seus usuários desfaçam o log ou excluam as anotações de compromisso registradas para que um log de substituição possa ser salvo, você terá duas opções.

  • Use o Microsoft Graph para limpar o objeto de propriedades personalizadas quando o usuário selecionar o botão apropriado no painel de tarefas.
  • Create uma função para limpar a propriedade personalizada EventLogged no item de compromisso atual (mostrado no exemplo a seguir).

  1. Em ./src/commands/commands.js, adicione a função a seguir para limpar a propriedade personalizada EventLogged no item de compromisso atual.

    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. Salve suas alterações.

  3. Chame a função clearCustomProperties quando quiser limpar a propriedade personalizada. Por exemplo, você pode chamá-lo do logCRMEvent se a configuração do log falhar de alguma forma, conforme mostrado na função a seguir.

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

Testar e validar

  1. Siga as diretrizes habituais para testar e validar seu suplemento.
  2. Depois de carregar o suplemento no Outlook na Web, no Windows (clássico ou novo (versão prévia)) ou no Mac, reinicie o Outlook em seu dispositivo móvel Android ou iOS.
  3. Abra um compromisso como participante e verifique se, no cartão do Meeting Insights, há uma nova cartão com o nome do suplemento ao lado do botão Log.

Interface do usuário: registrar as anotações de compromisso

Como participante da reunião, você deve ver uma tela semelhante à imagem a seguir ao abrir uma reunião.

O botão Log em uma tela de compromisso no Android.

Interface do usuário: exibir o log de compromissos

Depois de registrar com êxito as anotações de compromisso, o botão agora deve ser rotulado como Exibir em vez de Log. Você deve ver uma tela semelhante à imagem a seguir.

O botão Exibir em uma tela de compromisso no Android.

APIs disponíveis

As APIs a seguir estão disponíveis para esse recurso.

Para saber mais sobre APIs com suporte no Outlook em dispositivos móveis, confira APIs JavaScript do Outlook com suporte no Outlook em dispositivos móveis.

Restrições

Várias restrições se aplicam.

  • O nome do botão Log não pode ser alterado. No entanto, há uma maneira de um rótulo diferente ser exibido definindo uma propriedade personalizada no item de compromisso. Para obter mais detalhes, confira Exibir notas de compromisso.
  • A propriedade personalizada EventLogged deve ser usada se você quiser alternar o rótulo do botão Log para Exibir e voltar.
  • O ícone de suplemento deve estar em escala de cinza usando o código #919191 hex ou o equivalente em outros formatos de cor.
  • O suplemento deve extrair os detalhes da reunião do formulário de compromisso no período de um minuto. No entanto, qualquer tempo gasto em uma caixa de diálogo, o suplemento aberto para autenticação, por exemplo, é excluído do período limite.

Confira também