Compartilhar via

Invocar um suplemento do Outlook de uma mensagem acionável

  • Artigo

As mensagens acionáveis permitem que o utilizador realize ações rápidas numa mensagem de e-mail e os suplementos do Outlook permitem-lhe expandir o Outlook para adicionar novas funcionalidades e interações. Agora, com o tipo de ação Action.InvokeAddInCommand, você pode combinar esses dois tipos de integrações para criar experiências mais poderosas e atraentes. Por exemplo, você poderia:

  • Envie uma mensagem de boas-vindas como uma mensagem de email acionável a novos usuários depois de eles se inscreverem no seu serviço, com uma ação que permite instalar e começar a usar o suplemento rapidamente.
  • Use um suplemento para ações mais complexas (ou seja, para apresentar um formulário ao usuário), para cenários em que uma entrada de ação simples não seria suficiente.
  • Preencha previamente elementos da interface do usuário no seu suplemento antes da apresentação da interface do usuário ao usuário.

As ações Action.InvokeAddInCommand podem trabalhar com suplementos que já estão instalados pelo usuário ou podem trabalhar com suplementos não instalados. Se o suplemento necessário não estiver instalado, o usuário será solicitado a instalar o suplemento com um único clique.

Observação

A instalação de clique único do suplemento necessário só é suportada se o suplemento for publicado no AppSource.

O exemplo a seguir mostra o prompt que os usuários verão se o suplemento não estiver instalado.

Uma captura de ecrã do pedido para instalar um suplemento quando invocado a partir de uma mensagem acionável.

Invocando o suplemento

As mensagens acionáveis invocam suplementos especificando uma ação Action.InvokeAddInCommand na mensagem. Esta ação especifica o suplemento a ser invocado, juntamente com o identificador do botão do suplemento que abre o painel de tarefas apropriado.

As informações necessárias são encontradas no manifesto do suplemento. Primeiro, você precisará do identificador do suplemento, que é especificado no elemento Id.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp
  xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
  xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
  xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0"
  xsi:type="MailApp">
  <Id>527104a1-f1a5-475a-9199-7a968161c870</Id>
  <Version>1.0.0.0</Version>
  ...
</OfficeApp>

Para este suplemento, o identificador do suplemento é 527104a1-f1a5-475a-9199-7a968161c870.

Em seguida, será necessário o atributo id do elemento Control que define o botão do suplemento que abre o painel de tarefas apropriado. Tenha em mente que o elemento Control DEVE:

<ExtensionPoint xsi:type="MessageReadCommandSurface">
  <OfficeTab id="TabDefault">
    <Group id="msgReadCmdGroup">
      <Label resid="groupLabel"/>
      <Control xsi:type="Button" id="showInitContext">
        <Label resid="readButtonLabel"/>
        <Supertip>
          <Title resid="readButtonTitle"/>
          <Description resid="readButtonDesc"/>
        </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="readPaneUrl"/>
          <SupportsPinning>true</SupportsPinning>
        </Action>
      </Control>
    </Group>
  </OfficeTab>
</ExtensionPoint>

Para este botão de suplemento, a ID é showInitContext.

Com essas duas informações, podemos criar uma ação Action.InvokeAddInCommand básica da seguinte maneira:

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Invoking an add-in command from an Actionable Message card",
      "size": "large"
    }
  ],
  "actions": [
    {
      "type": "Action.InvokeAddInCommand",
      "title": "Invoke \"View Initialization Context\"",
      "addInId": "527104a1-f1a5-475a-9199-7a968161c870",
      "desktopCommandId": "showInitContext"
    }
  ]
}

Transmitindo dados de inicialização para o suplemento

A ação Action.InvokeAddInCommand também pode fornecer mais contexto para o suplemento, permitindo que o suplemento faça mais do que simplesmente ativar. Por exemplo, a ação poderia fornecer valores iniciais de um formulário ou fornecer informações que permitem que o suplemento "faça um link profundo" a um item específico em seu serviço de back-end.

Para transmitir dados de inicialização, inclua uma propriedadeinitializationContext na ação Action.InvokeAddInCommand. Não há nenhum esquema definido para a propriedade initializationContext, você pode incluir qualquer objeto JSON válido.

Por exemplo, para estender a ação de exemplo de acima, poderíamos modificar a ação da seguinte maneira:

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Invoking an add-in command from an Actionable Message card",
      "size": "large"
    }
  ],
  "actions": [
    {
      "type": "Action.InvokeAddInCommand",
      "title": "Invoke \"View Initialization Context\"",
      "addInId": "527104a1-f1a5-475a-9199-7a968161c870",
      "desktopCommandId": "showInitContext",
      "initializationContext": {
        "property1": "Hello world",
        "property2": 5,
        "property3": true
      }
    }
  ]
}

Recebendo dados de inicialização no suplemento

Se sua ação passar dados de inicialização, o suplemento deve ser preparado recebê-los. Os suplementos podem recuperar dados de inicialização chamando o método Office.context.mailbox.item.getInitializationContextAsync. Isso deve ser feito sempre que o painel de tarefas for aberto ou carregar uma nova mensagem.

// Get the initialization context (if present).
Office.context.mailbox.item.getInitializationContextAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    if (asyncResult.value.length > 0) {
      // The value is a string, parse to an object.
      const context = JSON.parse(asyncResult.value);
      // Do something with context.
    } else {
      // Empty context, treat as no context.
    }
  } else {
    // Handle the error.
  }
});

Recursos