Apps bauen

Eine eigene Microsoft Teams App: Beispiel „Allgemeine Infos“ (Teil 2)

Nachdem im ersten Teil des Beitrags gezeigt wurde, welche grundsätzlichen Überlegungen für unseren Anwendungsfall notwendig sind und welches Tooling praktischerweise zur Anwendung kommt, geht es nun ans Eingemachte. Wir klicken uns eine Teams App zusammen um einige zentrale Dokumente übergreifend bereitzustellen. Überraschung: Code sucht man hier vergebens.

Den Beginn macht ein Ausflug in das App Studio, welches wir uns in Teams installiert haben. Wie im letzten Artikel bereits beschrieben, brauchen wir Teams gar nicht verlassen und rufen es über die drei Punkte in der linken Leiste als  App auf. Das App Studio präsentiert sich mit den bereits darüber konfigurierten Apps. Startet man es das erste Mal, ist es natürlich deutlich leerer als auf meinem Screenshot.

Teams Apps im App Studio
Teams Apps im App Studio

Das App Studio unterteilt sich in drei wesentliche Bereiche: Zum einen den Manifest Editor, mit dem sich Pakete für Apps erstellen lassen. Zum anderen gibt es aber auch einen Card Editor, der es ermöglicht, Einzelinformationen in Chatverläufen gesondert darzustellen. Wenn man z.B. einmal die Teams App „Places“ in einem Teamchat ausprobiert hat, sieht, wie eine solche App arbeitet.

Zu guter Letzt gibt es noch einen Bereich, der vor allem für React-Programmierer hilfreich ist. Denn das App Studio integriert hier eine Bibliothek von Controls, die ähnlich wie die App Fabric fertigen Quellcode ausspuckt, den man in seine Webanwendungen integrieren kann. Das Tolle dabei ist, dass man damit ohne weiteres Zutun bereits ein analoges Look and Feel für Teams Apps hat und sich direkt weiterverwendbare Komponenten direkt generieren lassen kann. Wer also nicht nur wie wir in diesem Beispiel eine App aus bestehenden Diensten zusammenschustern möchte, sondern auch den Dienst möglichst nah am Standard samt UI selbst bauen möchte, sollte sich hier reichlich bedienen.

Los gehts mit der Teams App!

Mit einem Klick auf „Create a new app“ gehts los, wir werden auf die erste Seite eines Wizards geleitet, der für die Konfiguration des Drumgerums zuständig ist.

Grundlegende Eigenschaften im Manifest
Grundlegende Eigenschaften im Manifest

Die meisten Felder hier sind selbsterklärend. Der Editor möchte die grundlegenden Informationen unserer Teams App wissen: Name, Version, Beschreibung, und so weiter. Dabei erklärt er recht genau, was er in den einzelnen Feldern erwartet, sodass das Ausfüllen recht trivial ist. Selbst für die Generierung einer neuen App ID gibt es einen Button zum klicken. Wie langweilig. 🙂

Füllen wir das Ganze also einfach mal mit den Daten unserer Beispielanwendung aus:

Asgefüllte grundlegende Informationen einer Teams App
Asgefüllte grundlegende Informationen einer Teams App

Eine kleine Besonderheit erwartet uns bei den anzugebenden Icons, denn hier entsteht schnell ein kleines Missverständnis. Für das Branding möchte der Manifest Editor drei Dinge haben: Ein Logo mit 192x192px (easy), eine Kontrastfarbe, die nach Möglichkeit dem Hintergrund unseres Icons in irgendeiner Art und Weise entspricht (auch easy) und eine sogenannte Transparent Outline, die das Icon für die Aufrufleiste darstellt, gerne in 32x32px. Also schnell einmal ein wenig am Alphakanal geschraubt und hochgeladen. Ein mögliches Ergebnis kann also so aussehen:

Ein bisschen Blingbling für die Teams App
Ein bisschen Blingbling für die Teams App

Grundsätzlich hätten wir damit schon eine Teams App, herzlichen Glückwunsch. Diese tut zwar noch nix außer zu existieren, aber das ist doch schon einmal ein Anfang.

Die Funktionen einbringen

In die so bereitgestellte Hülle können wir nun wie anfangs beschrieben unsere Funktionen der App integrieren. Dazu bietet uns das App Studio dankbare grafische Unterstützung. In der linken Spalte können wir nach und nach Tabs, Bots, Konnektoren und Messaging Extensions hinzufügen. Die beiden letzten Typen referenzieren dabei jeweils auf entsprechende Apps, die irgendwo gehostet sind und mit Hilfe von APIs passgenau die jeweils benötigten Funktionen liefern. Konnektoren verbinden dabei mit Hilfe von Webhooks andere Dienste, die damit Informationen in Kanäle pushen können. Messaging Extensions sind dafür gedacht, dass wie das oben erwähnte Places spezielle Funktionen oder besondere Darstellungsweisen von Informationen gepostet werden können. Dazu kommen wir sicherlich noch einmal in einem späteren Artikel.

Unser Anwendungsfall ist wie gesagt sehr simpel: Wir brauchen Dokumente. Diese stellen wir instinktiv über eine SharePoint Website in einer Dokumentenbibliothek bereit. Und – weils so schön ist – sortieren sie ein wenig, pinnen einzelne Dateien an, oder vergeben noch weitere Metadaten. Ganz, wie es gefällt.

Die vorbereitete SharePoint Bibliothek
Die vorbereitete SharePoint Bibliothek

Da es ja unser Ziel ist, eine Registerkarte mit diesen Dokumenten als persönliche – also nicht zu einem Team gehörende, sondern wie das App Studio in der linken Leiste beheimatete  – Registerkarte bereitzustellen, wählen wir den Punkt „Add a personal tab“. Würden wir hier eine Registerkarte für ein Team auswählen, könnte die App später den konkreten Teams zugeordnet werden und dann dort von allen Besitzern über das „+“ als neue Instanz erstellt werden können.

Registerkarten hinzufügen
Registerkarten hinzufügen

Registerkarten konfigurieren

Auch hier geschieht die Konfiguration über eine grafische Oberfläche. Wir vergeben einen Namen sowie eine interne ID für die Registerkarte und legen fest, welche URL dahintersteht.

Registerkarten hinzufügen
Registerkarten hinzufügen

Dabei sind das genau genommen zwei URLs:

  • Die Content URL gibt an, welcher Inhalt in dem Tab eingeblendet werden soll. Das bedeutet schlicht und ergreifend, dass dieser Inhalt als IFrame eingeblendet wird.
  • Die Website URL gibt an, welche Webseite angezeigt wird, wenn der Benutzer mit einem Klick auf den Button „Wechseln zur Webseite“ angezeigt wird. In diesem Fall wird der Teams Client verlassen und der angegebene Inhalt öffnet sich in einem neuen Browserfenster.

Die Unterscheidung erlaubt damit eine Unterscheidung von kontextueller Darstellungsweise und der „gesamten“ Anwendung. In unserem Fall erkennt SharePoint seine Einbettung automatisch und wir können in beiden Fällen die URL zu unserer Dokumentenbibliotheksansicht ein.

Mit einem Klick auf Speichern wird genau das getan. Ab jetzt kann die Teams App die Registerkarte darstellen und wir sind fast schon fertig.

Teams App mit einer persönlichen Registerkarte
Teams App mit einer persönlichen Registerkarte

Der Vollständigkeit halber schauen wir, welche gültigen Domains eingetragen sind. Damit steuert Teams, welche URLs von der App grundsätzlich aufgerufen werden dürfen. Um sicherzugehen, dass hier keine Manipulation von außen möglich ist, müssen alle Domains, die von der App verwendet werden und im IFrame aufgerufen werden, hier also auf die Whitelist gewuchtet werden. Das App Studio unterstützt uns hierbei, indem es die offensichtlichen Domains aus den angegebenen URLs direkt mal automatisch selber einträgt. Wie nett von ihm.

Whitelist der erlaubten Domänen
Whitelist der erlaubten Domänen

Der Vollständigkeit halber kann man sich nun das Ergebnis einmal in der Übersicht des App Studios anschauen um einen Eindruck zu bekommen, ob die eingegebenen Texte passen und alles soweit am rechten Fleck ist. Die neue Teams App erscheint in der Liste.

Teams Apps im App Studio
Teams Apps im App Studio

„Lass doch mal laufen!“

Nun ist der spannende Moment gekommen, wir probieren die neue App aus. Auch hier hilft das App Studio, indem es in der Sektion „Test and Distribute“ eine Möglichkeit gibt, die App direkt im lokalen Tenant einmal „quer“ zu installieren ohne über den Store gehen zu müssen. Das ist natürlich irre praktisch, denn so erspart man sich gerade bei kleinen, häufigen Änderungen zwischen den Tests das wiederholte Hochladen des App-Pakets in den Store.

Testen und Paketieren
Testen und Paketieren

Um uns nun das Endergebnis einmal anzuschauen, klicken wir forsch auf den „Install“-Knopf. Dahinter verbirgt sich direkt die standardmäßige Erfahrung bei der Installation von Apps in Teams. Die Installationsroutine liest das Manifest aus und präsentiert, was die App kann, welche Rechte sie benötigt, und bietet dementsprechend die dazugehörigen Optionen an. Hier kommen auch die hinterlegten Links zum Einsatz, um die rechtlichen Bestimmungen einsehen zu können.

Die Teams App installieren
Die Teams App installieren

Ist die App installiert, kann man sie direkt öffnen. Da wir keine weitere Konfiguration brauchen, können wir direkt loslegen.

Die Teams App installieren
Die Teams App installieren

Das Endergebnis

Und siehe da: Wir können die Dokumente wie konfiguriert in der App sehen. SharePoint Online erkennt, dass es in einem IFrame dargestellt werden kann und reduziert die Ansicht automatisch auf die Ansicht der Dokumentenbibliothek.

Da wir entsprechende Berechtigungen haben, werden auch die Möglichkeiten des Editierens direkt in der SharePoint Bibliothek gegeben. Möchte man also eine Dokumentenbibliothek übergreifend zur Verfügung stellen, sollte man dafür sorgen, dass die Adressaten auch ausreichend Berechtigung auf der Datenquelle haben.

Ds Endergebnis: Unsere App mit allgemeinen Informationen, die Teams-unabhängig bereitgestellt wird.
Das Endergebnis: Unsere App mit allgemeinen Informationen, die Teams-unabhängig bereitgestellt wird.

Neben unserer Registerkarte gibt es eine Info-Karte, auf der noch einmal die Funktionen der App zusammengefasst werden und auch die Links zu den rechtlichen Informationen werden hier noch einmal bereitgestellt.

Die Installation über den Store

Möchte man nun die App nicht nur lokal über das App Studio bereitstellen, sondern auch die dafür vorgesehene Infrastruktur, muss man noch einen Schritt weiter gehen. Unter der Voraussetzung, das das Querladen von Apps in der Zentraladministration des Tenants freigeschaltet wurde, können  Apps direkt im Store durch hochgeladen und für die Mitglieder der Organisation zur Verfügung gestellt werden (der Link dazu befindet sich unten links). Dabei erscheint in der linken Liste unter den Kategorien der Name der Organisation als eigene Gruppe von Teams Apps.

Die Teams App im Store
Die Teams App im Store

Das dafür notwendige Paket bekommt man wieder aus dem App Studio. Mit einem Klick auf die Schaltfläche „Download“ im Bereich „Test and Distribute“ lässt sich aus den eingegebenen Informationen ein Zip-Paket generieren, welches dann direkt in den Store gelanden werden kann.

Hierbei empfiehlt sich gerade bei Updates eine sinnvolle Versionsbeschreibung in dem Manifest. Kommt es nämlich vor, dass eine bereits veröffentlichte Teams App aktualisiert werden muss, kann so schnell unterschieden werden, um welche Version es sich handelt, wenn Benutzer z.B. von Problemen berichten. Diese Information befindet sich immer auf der Info-Registerkarte der App.

Das Aktualisieren selbst geht sehr simpel über die Oberfläche des Stores. Ist das Paket einmal hochgeladen, lässt es sich durch einen simplen Klick im Kontextmenü mit einem weiteren Paket mit derselben hinterlegten App ID überschreiben.

Teams App im Store aktualisieren
Teams App im Store aktualisieren

Auf welchem der Wege die Teams App auch für den Benutzer installiert wird: Da wir angegeben haben, dass sie eine persönliche Registerkarte enthält, erscheint sie Teams-übergreifend unter den drei Punkten in der linken Navigationsleiste von Teams. Damit kann sie jederzeit – auch ohne Kontext einers Teams – aufgerufen werden.

Aufrufen der App
Aufrufen der App

           

Bonus Content: Das Manifest im Wortlaut

Das App Studio hat uns in diesem Beispiel das meiste an Arbeit abgenommen und recht unfallsicher durch die verschiedenen Konfigurationsschritte geführt. Aber was genau ist dabei im Hintergrund passiert?

Wie schon im ersten Teil angedeutet, besteht die App eigentlich aus nicht viel mehr als einer JSON-Datei und den hochgeladenen Icons für das Branding. Lädt man das Zip-Paket aus dem Studio herunter und öffnet die Datei lokal, sieht man genau diese drei Dateien darin. Das App Studio hilft uns also hauptsächlich dabei, das richtige Format für die JSON-Definition zu finden.

Die oben skizzierte Teams App sieht also hinter den Kulissen so aus:

Jeder der Punkte findet sich in der oben dargestellten Oberfläche wieder. Mit der Definition von Konnektoren, Messaging Extensions oder Teams-bezogenen Registerkarten wird die Definition zwar etwas komplexer, aber grundsätzlich bleibt es bei dem hier dargestellten Prinzip.

5 thoughts on “Eine eigene Microsoft Teams App: Beispiel „Allgemeine Infos“ (Teil 2)

  1. Schöner Artikel Carsten! Danke für den Einblick in das Teams App Studio. Mir gefällt die Möglichkeit, teamunabhängige, aber anwenderbezogene Inhalte in Teams bereitstellen zu können. Ein weiterer Schritt in die Richtung Teams als zentrales Tool zu verwenden. Ein weiteres schönes Beispiel die die Microsoft Stream App, die den Zugriff auf meine persönliche Watchlist von Stream in Teams ermöglicht.

    Antworten

  2. hallo Carsten!

    Danke für den zweiten Teil.
    Leider funktioniert das Teil bei mir irgendwie nicht, Beim TEsten bekomme ich immer: es ist ein Fehler aufgetreten.
    dabei meine ich, mich genau an die Anweisung gehalten zu haben bis auf das Branding.

    Liebe Grüße

    Gregor

    Antworten

    1. Hey Gregor, wann genau bekommst Du die Meldung? Beim Aufruf der App, also wenn die Dokumentenbibliothek im IFrame der App erscheinen soll? Kannst Du ausmachen, ob die Meldung von Teams aus kommt oder ob das eine Meldung ist, die SharePoint in diesem Moment bringt? Wenn es das letzte ist, probiere mal, den Link über das Icon „Im Browser öffnen“ rechts oben aufzurufen. Sollte es da ein anderes Verhalten sein, könnte ggf. ATP mit Conditional Access reinspielen. Weißt Du, ob dieses Feature in Deinem Tenant aktiviert ist?

      Antworten

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.

This site uses Akismet to reduce spam. Learn how your comment data is processed.