Aufrufen eines Outlook-Add-Ins in einer Nachricht mit Aktionen

Über Nachrichten mit Aktionen können Benutzer in einer E-Mail oder Connectorkarte schnelle Aktionen durchführen, und mit Outlook-Add-Ins können Sie Outlook um neue Features und Interaktionen erweitern. Mit dem Aktionstyp InvokeAddInCommand können Sie nun diese beiden Arten von Integration kombinieren, um leistungsstärkere und ansprechendere Benutzeroberflächen zu erstellen. So haben Sie zum Beispiel die folgenden Möglichkeiten:

  • Senden Sie neuen Benutzern nach der Registrierung für Ihren Dienst eine Begrüßungsnachricht als Aktion erfordernde E-Mail mit einer Aktion, mit der sie das Add-In schnell installieren und verwenden können.
  • Verwenden Sie ein Add-In für komplexere Aktionen (um dem Benutzer ein Formular zu präsentieren) bei Szenarien, in denen eine einfache Aktion zur Eingabe nicht ausreichend wäre.
  • Füllen Sie Elemente der Benutzeroberfläche im Add-In vorab aus, bevor Sie die Benutzeroberfläche dem Benutzer präsentieren.

InvokeAddInCommand-Aktionen können Add-Ins, die bereits vom Benutzer installiert wurden, oder noch nicht installierte Add-Ins verwenden. Wenn das erforderlich Add-In nicht installiert ist, wird der Benutzer aufgefordert, das Add-In mit einem einzigen Mausklick zu installieren.

Hinweis

Die Installation des erforderlichen-Add-Ins mit nur einem Klick wird nur unterstützt, wenn das Add-In im Office Store veröffentlicht ist.

Das folgende Beispiel zeigt die Eingabeaufforderung, die Benutzern angezeigt wird, wenn das Add-In nicht installiert ist.

Ein Screenshot der Eingabeaufforderung zum Installieren eines Add-Ins beim Aufruf des Add-Ins in einer Aktion erfordernden Nachricht

Aufrufen des Add-Ins

Nachrichten mit Aktionen rufen Add-Ins durch Angabe einer InvokeAddInCommand-Aktion in der Nachricht auf. Diese Aktion gibt das aufzurufende Add-In zusammen mit dem Bezeichner der Add-In-Schaltfläche an, die den entsprechenden Aufgabenbereich öffnet.

Die erforderlichen Informationen befinden sich im Manifest des Add-Ins. Zunächst benötigen Sie die Add-In-ID, die im Id-Element angegeben ist.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp 
  xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" 
  xmlns:xsi="http://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>

Für dieses Add-In lautet die Add-In-ID 527104a1-f1a5-475a-9199-7a968161c870.

Im nächsten Schritt benötigen Sie das id-Attribut des Control-Elements, das die Add-In-Schaltfläche definiert, die den entsprechenden Aufgabenbereich öffnet. Bedenken Sie, dass das Control-Element Folgendes erfüllen MUSS:

<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>

Für diese Add-In-Schaltfläche lautet die ID showInitContext.

Mit diesen beiden Informationen können wir eine grundlegende InvokeAddInCommand-Aktion wie folgt erstellen:

{
    "@type": "InvokeAddInCommand",
    "name": "Invoke \"View Initialization Context\"",
    "addInId": "527104a1-f1a5-475a-9199-7a968161c870",
    "desktopCommandId": "showInitContext"
}

Übergeben von Initialisierungsdaten an das Add-In

Die InvokeAddInCommand-Aktion kann auch zusätzlichen Kontext für das Add-In bereitstellen, der dem Add-In neben der Aktivierung weitere Aktionen ermöglicht. Die Aktion könnte z. B. Anfangswerte für ein Formular oder Informationen bereitstellen, die dem Add-In einen „Deep-Link“ zu einem bestimmten Element in Ihrem Back-End-Dienst ermöglicht.

Um Initialisierungsdaten zu übergeben, schließen Sie eine initializationContext-Eigenschaft in die InvokeAddInCommand-Aktion ein. Es gibt kein Satzschema für die initializationContext-Eigenschaft. Sie können jedes gültige JSON-Objekt einschließen.

Zum Erweitern der Beispielaktion von oben könnten wir die Aktion beispielsweise wie folgt ändern:

{
    "@type": "InvokeAddInCommand",
    "name": "Invoke \"View Initialization Context\"",
    "addInId": "527104a1-f1a5-475a-9199-7a968161c870",
    "desktopCommandId": "showInitContext",
    "initializationContext": {
        "property1": "Hello world",
        "property2": 5,
        "property3": true
    }
}

Empfangen von Initialisierungsdaten im Add-In

Wenn die Aktion Initialisierungsdaten übergibt, muss das Add-In darauf vorbereitet sein, sie zu empfangen. Add-Ins können Initialisierungsdaten durch einen Aufruf der Office.context.mailbox.item.getInitializationContextAsync-Methode abrufen. Dies sollte immer dann erfolgen, wenn der Aufgabenbereich geöffnet wird oder eine neue Nachricht lädt.

// Get the intialization context (if present)
Office.context.mailbox.item.getInitializationContextAsync(
  function(asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Succeeded) {
      if (asyncResult.value != null && asyncResult.value.length > 0) {
        // The value is a string, parse to an object
        var context = JSON.parse(asyncResult.value);
        // Do something with context
      } else {
        // Empty context, treat as no context
      }
    } else {
      if (asyncResult.error.code == 9020) {
        // GenericResponseError returned when there is
        // no context
        // Treat as no context
      } else {
        // Handle the error
      }
    }
  }
);

Ressourcen