Microsoft WOPI & CSPP: So integrierst du Microsoft Office nahtlos in deine Anwendung

Wie funktioniert das Zusammenspiel von WOPI (Web Application Open Platform Interface) und dem Cloud Storage Partner Program (CSPP)? Welche Herausforderungen gibt es, und welche Best Practices helfen dir, diese zu meistern?

In diesem Blogbeitrag geben wir dir Antworten auf all diese Fragen. Du erhältst eine Schritt-für-Schritt-Anleitung zur Integration, technische Einblicke und unsere Erfahrungen aus der Praxis.

Was ist das CSPP?

Das Cloud Storage Partner Program (CSPP) ist ein Programm von Microsoft, das Drittanbieter-Cloud-Speicherdiensten eine problemlose Integration mit Microsoft Office im Web ermöglicht. Über CSPP können Anbieter WOPI (Web Application Open Platform Interface) nutzen, um Office-Dokumente direkt aus der Cloud zu bearbeiten und anzuzeigen. Dies sorgt für eine sichere und effiziente Zusammenarbeit innerhalb externer Cloud-Speicherlösungen. Wie läuft der Prozess ab?

1. Bewerbung und Zugang zur Testumgebung: Nachdem die Bewerbung für das CSPP erfolgreich war, erhältst du Zugang zur Testumgebung.
2. Subdomain-Freigabe: Deine Anwendung muss über eine passende Subdomain erreichbar sein, die freigegeben wird.
3. Entwicklung und Test: In der CSPP-Testumgebung kannst du die Integration entwickeln und testen.
4. Review und Produktionsumgebung: Nach Abschluss wird ein Review durch Microsoft durchgeführt. Bei Erfolg erfolgt die Freischaltung für die Produktionsumgebung. Hinweis: Der gesamte Prozess kann bis zu vier Wochen dauern.

Was ist WOPI?

1. WOPI Discovery
   Die WOPI Discovery stellt die nötigen Informationen bereit, damit Anwendungen wie Microsoft Office im Web reibungslos eingebunden werden können. Microsoft liefert dafür XML-Daten, die unter anderem alle verfügbaren Aktionen für unterstützte Dateitypen enthalten. Auch Links zu Favicons und URL-Templates für das Einbetten von Office-Anwendungen sind hier zu finden.
2. WOPI REST-Endpunkte
   REST-Endpunkte sind das Herzstück der Integration. Damit Microsoft Office im Web auf Dateien auf dem eigenen Server zugreifen kann, müssen spezifische REST-Endpunkte implementiert werden, die Microsoft vorschreibt. Diese Endpunkte decken typische Dateioperationen ab (CRUD), aber auch spezifische Anforderungen wie Locking (Sperren von Dateien), Versionierung und Authentifizierung müssen implementiert werden.
3. Einbetten von Microsoft Office im Web
   Um Dokumente in einer Anwendung darzustellen, wird die passende Anwendung (z. B. Word, Excel oder PowerPoint) je nach Dateityp in einem iFrame eingebettet. Hierbei hilft die WOPI Discovery, die richtige Anwendung auszuwählen. Parameter wie die Datei-ID werden als URL-Parameter übergeben, sodass Microsoft Office im Web die Datei direkt laden kann.

Technische Details zur Integration

Die erfolgreiche Integration von Microsoft Office im Web erfordert ein tiefes Verständnis der zugrunde liegenden Konzepte. Die folgenden Kernaspekte waren bei unserer Implementierung besonders wichtig:

1. Authentifizierung
   Damit sich Microsoft Office im Web gegenüber der Anwendung authentifizieren kann, wird ein Token-Endpunkt benötigt. Beim ersten Aufruf holt sich Microsoft Office im Web ein Token, das dann für alle weiteren Anfragen genutzt wird. Die Anwendung validiert dieses Token und prüft die Berechtigungen, um sicherzustellen, dass nur autorisierte Nutzer Zugriff auf die jeweiligen Dateien haben. Das Token ist benutzerspezifisch und muss mit den Berechtigungen aus dem CheckFileInfo-Endpunkt übereinstimmen. Auch ein Ablaufdatum des Tokens ist wichtig, um sicherzustellen, dass keine abgelaufenen Anfragen verarbeitet werden.
2. Versionierung
   WOPI verlangt eine Versionierung der Dateien, sodass beim Abruf immer die aktuelle Versionsnummer mitgeliefert wird. Diese Nummer wird bei jeder Änderung hochgezählt. Microsoft Office im Web nutzt sie zur Kollisionserkennung – so können Konflikte vermieden werden, wenn mehrere Nutzer gleichzeitig an einer Datei arbeiten. Ein weiterer Vorteil: Frühere Versionen lassen sich bei Bedarf wiederherstellen.
3. Dateisperrung (Locking)
   Um Datenkonflikte zu vermeiden, sperrt Microsoft Office im Web eine Datei, sobald die Bearbeitung beginnt. Eine gültige Lock-ID ist erforderlich, um eine Datei zu bearbeiten, und wird bei jeder Änderung der Datei (über den PutFile-Endpunkt) mitgeschickt und geprüft. Dabei ist es wichtig, dass die eigene Anwendung ebenfalls das Lock beachtet, um eine gelockte Datei nicht irrtümlich zu überschreiben.

Herausforderungen bei der Implementierung

1. Fehleranalyse
   Die Debugging-Möglichkeiten sind bei einer WOPI-Integration eingeschränkt, da Microsoft Office im Web nur auf freigegebene Domains zugreift. Hier kann ein Remote-Debugging-Setup hilfreich sein. Auch gibt Microsoft Office im Web nur generische Fehlermeldungen aus – ein Problem, das der WOPI Validator von Microsoft teilweise löst, indem er verschiedene Szenarien testet und die Endpunkte auf Konsistenz prüft. Für tiefergehende Analysen ist es zudem ratsam, detailliertes Logging zu implementieren, um die Reihenfolge und Details der Schnittstellenaufrufe nachvollziehen zu können.
2. Locking
   Obwohl Locking in vielen Dateiverwaltungslösungen Standard ist, kann es negative Effekte haben, wenn bereits ein Locking-Mechanismus besteht. So können Hintergrundprozesse, die ebenfalls Dateien bearbeiten, durch das WOPI-Locking blockiert werden. Daher haben wir für WOPI einen separaten Locking-Mechanismus implementiert: Die Locks und zugehörigen Datei-IDs werden in einer Map gespeichert. Ein Task überwacht die Ablaufzeiten und bereinigt abgelaufene Locks.
3. Konsistenz und Transaktionalität
   Eine robuste WOPI-Implementierung erfordert sowohl konsistente als auch transaktionale Schnittstellen. Das bedeutet, dass ein Endpunkt bei gleichen Parametern immer das gleiche Ergebnis liefern sollte, was auch durch den WOPI Validator geprüft wird. Transaktionalität ist ebenfalls entscheidend: Sobald ein Endpunkt eine Antwort zurückgibt, müssen alle Änderungen bereits dauerhaft gespeichert sein. In unserem Fall führte ein asynchroner Prozess, der eine Datei nach Abschluss der Abfrage erneut aktualisierte, zu Problemen, da die Konsistenz nicht gewährleistet werden konnte.

Fazit

Eine CSPP-Implementierung mag auf den ersten Blick unkompliziert wirken, birgt aber einige versteckte Herausforderungen. Dementsprechend lohnt es sich, die Dokumentation bereits im Vorfeld genau zu lesen und zu verstehen. Auch sollte eine Analyse der eigenen Anwendung durchgeführt werden, um potenzielle Probleme frühzeitig zu erkennen. Die Implementierung sollte dann möglichst vom Rest der Anwendung abgekapselt werden.¹