Registar notas de compromisso para uma aplicação externa nos suplementos do Outlook Mobile

  • Artigo

Guardar as suas notas de compromisso e outros detalhes numa gestão de relações com os clientes (CRM) ou numa aplicação de escrita de notas pode ajudá-lo a controlar as reuniões em que participou.

Neste artigo, irá aprender a configurar o seu suplemento outlook para dispositivos móveis para permitir que os utilizadores regisem notas e outros detalhes sobre os respetivos compromissos para o CRM ou a aplicação de escrita de notas. Ao longo deste artigo, vamos utilizar um fornecedor fictício de serviços CRM com o nome "Contoso".

Pode optar por implementar um comando de função ou suplemento do painel de tarefas. Com a implementação de um comando de função, os utilizadores podem registar e ver notas e outros detalhes sobre os compromissos quando selecionarem o botão de suplemento. Com a implementação de um painel de tarefas, os utilizadores podem gerir diretamente as notas de compromisso a partir de uma interface do painel de tarefas. À medida que segue as instruções neste artigo, selecione o separador para o tipo de suplemento que está a desenvolver.

Clientes com suporte

O registo de notas numa aplicação externa a partir de um suplemento móvel do Outlook é suportado no Outlook para Android e no iOS com uma subscrição do Microsoft 365.

Configurar seu ambiente

Conclua o guia de introdução 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 está a utilizar.

Manifesto unificado para o Microsoft 365

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

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

  3. Na matriz "authorization.permissions.resourceSpecific", localize o primeiro objeto e defina a respetiva propriedade "name" como "MailboxItem.ReadWrite.User". Deverá ter o seguinte aspeto quando terminar.

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

  4. Na matriz "validDomains", certifique-se de que o URL a https://www.contoso.com está incluído. Quando terminar, a matriz deverá ter o seguinte aspeto.

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

  5. Na matriz "extensions.runtimes", elimine o objeto cujo "id" está definido como "TaskPaneRuntime".

  6. Na mesma matriz, navegue para o objeto restante, cujo "id" está definido como "CommandsRuntime" e substitua-o pelo seguinte objeto.

    {
    "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 "frisos", substitua o objeto existente pelo seguinte código. Tenha em atenção o seguinte sobre estas alterações.

    • Os valores "desktop" e "mobile" na matriz "ribbons.requirements.formFactors" configuram o botão Registar na Contoso para aparecer no Outlook em dispositivos móveis e em clientes de ambiente de trabalho.
    • O valor "logEventMeetingDetailsAttendee" na matriz "contexts" configura o botão de suplemento para aparecer na superfície Participante do Compromisso, para que os utilizadores possam registar as notas de compromisso.
    • O objeto na matriz "ribbons.tabs.groups.controls" configura o botão de suplemento que chama a função de registo de notas nos clientes de ambiente de trabalho do Outlook. A propriedade "actionId" tem de 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 registo 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" tem de corresponder ao "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",
                            "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",
                            "type": "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 apenas de suplemento

Para permitir que os utilizadores registem notas de compromisso com o seu suplemento, tem de configurar o ponto de extensão MobileLogEventAppointmentAttendee no manifesto no elemento MobileFormFactorprincipal . Outros fatores de forma não são suportados.

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

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

  3. Selecione todo <VersionOverrides> o nó (incluindo etiquetas abertas e fechadas) e substitua-o pelo XML seguinte. Certifique-se de que substitui todas as referências à Contoso pelas 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"/>
      </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, consulte Manifestos de suplementos do Office e Adicionar suporte para comandos de suplementos no Outlook em dispositivos móveis.

Capturar notas de compromisso

Nesta secção, saiba como o seu suplemento pode extrair detalhes do compromisso quando o utilizador seleciona o botão Registo .

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

  2. Substitua todo o conteúdo do ficheiro commands.js pelo seguinte 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. Salve suas alterações.

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

  5. Localize <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js"></script>e, em seguida, adicione o seguinte código após o mesmo. Esta ação adiciona uma referência ao ficheiro commands.js .

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

  6. Salve suas alterações.

Ver notas de compromisso

A etiqueta do botão Registo pode ser alternada para apresentar a Vista ao definir a propriedade personalizada EventLogged reservada para esta finalidade. Quando o utilizador seleciona o botão Ver , pode ver as notas registadas para este compromisso.

O suplemento define a experiência de visualização de registos. Por exemplo, numa implementação de comando de função, pode apresentar as notas de compromisso registadas numa caixa de diálogo quando o utilizador seleciona o botão Ver . Para obter detalhes sobre como implementar caixas de diálogo, consulte Utilizar a API de caixa de diálogo do Office nos seus Suplementos do Office.

  1. Em ./src/commands/commands.js, adicione a seguinte função. Esta 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 depois de o suplemento registar com êxito as notas de compromisso. Por exemplo, pode chamá-lo a partir de logCRMEvent , conforme mostrado no código seguinte.

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

Eliminar o registo de compromissos

Se quiser que os seus utilizadores anulem o registo ou eliminem as notas de compromisso registadas para que um registo de substituição possa ser guardado, tem duas opções.

  • Utilize o Microsoft Graph para limpar o objeto de propriedades personalizadas quando o utilizador selecionar o botão adequado no painel de tarefas.
  • Crie uma função para limpar a propriedade personalizada EventLogged no item de compromisso atual (mostrado no exemplo seguinte).

  1. Em ./src/commands/commands.js, adicione a seguinte função 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 pretender limpar a propriedade personalizada. Por exemplo, pode chamá-lo a partir de logCRMEvent se a definição do registo tiver falhado de alguma forma, conforme mostrado na seguinte função.

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 a documentação de orientação habitual para testar e validar o seu suplemento.
  2. Depois de carregar o suplemento em sideload no Outlook na Web, no Windows (novo ou clássico) ou no Mac, reinicie o Outlook no seu dispositivo móvel Android ou iOS.
  3. Abra um compromisso como participante e, em seguida, verifique se, no card Informações da Reunião, existe uma nova card com o nome do seu suplemento juntamente com o botão Registo.

IU: Registar as notas de compromisso

Enquanto participante da reunião, deverá ver um ecrã semelhante à imagem seguinte ao abrir uma reunião.

O botão Registar num ecrã de compromisso no Android.

IU: Ver o registo de compromissos

Depois de registar com êxito as notas de compromisso, o botão deverá agora ter o nome Vista em vez de Registo. Deverá ver um ecrã semelhante à imagem seguinte.

O botão Ver num ecrã de compromissos no Android.

APIs disponíveis

As seguintes APIs estão disponíveis para esta funcionalidade.

Para saber mais sobre as APIs suportadas no Outlook em dispositivos móveis, consulte ApIs JavaScript do Outlook suportadas no Outlook em dispositivos móveis.

Restrições

Aplicam-se várias restrições.

  • O nome do botão Registo não pode ser alterado. No entanto, existe uma forma de apresentar uma etiqueta diferente ao definir uma propriedade personalizada no item de compromisso. Para obter mais detalhes, consulte Ver notas de compromisso.
  • A propriedade personalizada EventLogged tem de ser utilizada se quiser alternar a etiqueta do botão Registo para Ver e voltar.
  • O ícone do suplemento deve estar em tons de cinzento com código #919191 hexadecima ou equivalente noutros formatos de cor.
  • O suplemento deve extrair os detalhes da reunião do formulário de compromisso dentro do período de tempo limite de um minuto. No entanto, qualquer tempo despendido numa caixa de diálogo, o suplemento aberto para autenticação, por exemplo, é excluído do período de tempo limite.

Confira também