Schnittstellen einfach mit der Meisterplan REST API erstellen (Teil 2)

Herzlich Willkommen zu Teil 2 unseres Artikels rund um die Erstellung von Schnittstellen mit Meisterplans REST API. Im ersten Teil haben wir über den Nutzen von REST API für Sie und Ihr Unternehmen gesprochen. Jetzt wollen wir Ihnen anhand konkreter Beispiele zeigen, wie einfach Sie Tools über die Meisterplan REST API anknüpfen können.

Das Wichtigste zu Teil 2 in Kürze:

• Nahezu jede Software unterstützt heute REST APIs. Im Cloud-Umfeld ist es sogar ein Muss. Mit der REST API können Systeme sicher Daten über das World Wide Web austauschen.
• Meisterplan stellt mit der REST API und der OpenAPI Dokumentation alles zur Verfügung, was für die Erstellung individueller Schnittstellen benötigt wird.
• Mit Postman haben Sie ein kostenfreies Tool zur Hand, mit dem Sie den Zugriff auf die Meisterplan REST API einfach üben können.

Wie unterstützt Meisterplan Integrationen?

Standard Integrationen

Wir haben das Ziel, Meisterplan so in die vorhandene IT-Landschaft zu integrieren, dass jeder Benutzer weiter mit seinen präferierten operativen Systemen arbeiten kann. Und das während gleichzeitig die benötigten Informationen beim Arbeiten mit Meisterplan zur Verfügung stehen. Dazu stellen wir Standard-Integrationen zu gängigen Tools bereit, mit denen häufige Anwendungsfälle im Projektportfolio- und Ressourcen Management unterstützt werden.

Zu den Meisterplan Integrationen

Jedoch haben ähnlich lautende Prozesse in jeder Organisation individuelle Ausprägungen. Das führt unter anderem dazu, dass dieselben IT-Systeme in unterschiedlichen Organisationen auch unterschiedlich eingesetzt und konfiguriert werden. Ein gutes Beispiel dafür ist Microsoft Project. Von den zahlreichen Projekt-Management-Lösungen wie Project Server, Project Online und Project for the Web kann jede anders eingesetzt werden. Projekte können klassisch nach dem Wasserfall-Prinzip, aber auch agil mit KANBAN oder Scrum gemanagt werden. Auch die Vielfalt an anderen Tools, die Ihnen zur Unterstützung Ihrer Prozesse zur Verfügung stehen, ist enorm. Damit ist oft eine individuelle Lösung gefragt.

Einer unserer Kunden setzt zum Beispiel Smartsheet für das operative Projektmanagement ein. Er hat sich entschieden, bei der Anbindung von Smartsheet an Meisterplan unsere Projektvorlage als Struktur zu verwenden.Für die Datenübertragung nach Meisterplan nutzt er aber nicht unseren Standard-Konnektor, sondern Zapier als Middleware. Für das Unternehmen war es wichtig, Änderungen an Projekten sofort zum Zeitpunkt der Änderung nach Meisterplan zu übertragen. Diese Vielfalt und Individualität der Anforderungen unterstützen wir ausdrücklich und stellen deshalb die Meisterplan REST API zur Verfügung.

Individuelle Lösungen mit der Meisterplan REST API

Mit der Meisterplan REST API steht Ihnen eine Technologie zur Verfügung, Schnittstellen zu Ihren präferierten Tools auf Ihre individuellen Bedürfnisse zugeschnitten zu erstellen. API steht für Application Programming Interface, einer Möglichkeit, mit IT-Systemen zu kommunizieren. REST ist eine Methode, mit der IT-Systeme sicher über das Internet kommunizieren können. REST APIs sind heute Standard in der Integration von IT-Systemen und werden von den meisten Systemen auf dem Markt unterstützt.

Damit erlaubt die REST API von Meisterplan eine sichere Kommunikation und einen Datenaustausch mit beliebigen anderen IT-Systemen über das Internet. Diese Fähigkeit ist von essenzieller Bedeutung, da Meisterplan als Software As a Service (SaaS) in der Cloud bereitgestellt wird. Der Zugriff auf Meisterplan über die REST API ist über ein Authentifizierungsverfahren abgesichert und damit vor unbefugtem Zugriff geschützt.

Die Middleware als Moderator

Eine REST API ist ein Dienst eines IT-System, der darauf wartet, Anfragen zu erhalten und diese dann zu beantworten. Wenn also zwei zu verbindende Systeme nur warten und lauschen, braucht es etwas, was die Kommunikation anstößt und steuert: eine Art Moderator. Der Moderator ist ein Stück Software und wird als Middleware bezeichnet.

Die Aufgabe einer Middleware ist also der sichere Informationsaustausch zwischen zwei IT-Systemen über deren APIs. Dabei berücksichtigt sie die individuellen Geschäftsregeln und führt u.a. diese Teilaufgaben durch:

• Authentifizierung an der API
• Senden von Anfragen (Requests) an die API
• Antworten (Responses) der angesprochenen API entgegennehmen und verarbeiten
• Kontrollierte Behandlung der von der API gemeldeten Fehler
• Transformation der Informationen, z.B. in ein anderes Format bringen oder aggregieren.

Zur Erstellung einer Middleware kann nun eine individuelle Software programmiert werden, entsprechende Programmierkenntnisse vorausgesetzt. Diese würden dann durch Sie, in Ihrer IT-Infrastruktur betrieben.

Integrationsplattform statt Individualsoftware

Wir empfehlen aber die Verwendung einer der vielen auf dem Markt vorhandenen Integrationsplattformen. Diese Plattformen sind speziell dafür designt, als Middleware zwischen Cloud-basierten und bei Bedarf auch On-Premises betriebenen Systemen zu fungieren. Voraussetzungen wie Betriebsinfrastruktur, Cloud-Sicherheit, Monitoring und zahlreiche Konnektoren werde dort bereits erfüllt. Viele unserer Kunden haben bereits Integrationsplattformen im Einsatz, vielleicht ist das auch bei Ihnen der Fall.

Die Plattformen können On-Premises durch Ihr IT-Team oder einen Dienstleister in Ihrer IT-Landschaft betrieben werden, oder als Service einfach im Rahmen eines Subscription-Modells in der Cloud “abonniert” werden. Man spricht dann von einer Integration Platform as a Service (iPaas).

Stellvertretend für die vielen iPaas-Lösungen möchte ich Zapier und Microsoft Power Automate nennen. Das sind sogenannte No-Code oder Low-Code Integrationsplattformen. Sie haben das Ziel, auch Menschen ohne tiefe Programmierkenntnisse die Erstellung von Integrationen zu ermöglichen. Dazu stellen Sie grafische Oberflächen zur Verfügung, mit denen Workflows oder Flows konfiguriert werden, ohne selbst Programmiercode zu schreiben. Diese Workflows kommunizieren dann zum Beispiel mit den REST APIs der beiden Systeme, die Daten austauschen wollen. Ein Workflow kann dabei entweder regelmäßig zeitgesteuert oder durch ein Ereignis in einem der Systeme ausgelöst werden.

Für die Plattform Zapier stellen wir einen Standard-Konnektor zu Meisterplan zur Verfügung. Dieser Konnektor unterstützt alle erforderlichen Methoden, um Daten nach Meisterplan zu übertragen.

Zum Meisterplan Zapier-Konnektor

Für andere Plattformen wie Microsoft Power Automate steht unsere REST API zur Verfügung.

Die Plattformen stellen grafische Komponenten zur Verfügung, mit denen der Aufruf von REST APIs konfiguriert und so unkompliziert in Workflows verwendet werden können.

REST API Dokumentation

Für die Konfiguration der REST API Komponenten der Integrationsplattform ist es erforderlich, die Fähigkeiten der anzusprechenden REST API zu kennen.

Meisterplan stellt dafür eine Online-Dokumentation zur Verfügung, in der

• die Authentifizierung,
• die verfügbaren Methoden mit Parametern, sogenannte Endpunkte, samt Beispielen und
• die Fehlerbehandlung

beschrieben sind.

API-Dokumentation (für EU gehostete Systeme)

Mit Postman die API kennenlernen

Mit Hilfe der REST-API-Dokumentation sind Sie in der Lage, die in der Middleware benötigten Aufrufe zu identifizieren, zu verstehen und in der korrekten Syntax zu formulieren.

Um sich mit der Meisterplan REST API vertraut zu machen und Endpunkte zu testen, empfehlen wir das Tool Postman, welches kostenlos erhältlich ist. Im Folgenden erfahren Sie anhand von Beispielen, wie Sie die Meisterplan REST API mit Postman ansprechen. Gerne können Sie die REST API aber auch mit einem anderen Tool Ihrer Wahl testen.

OpenAPI Dokumentation erzeugt Beispielcode

Nachdem Sie sich Zugang zu Postman verschafft haben, kann es los gehen.

Laden Sie sich zuerst die API-Dokumentation der Meisterplan REST API nach Postman.

Wir stellen die Dokumentation im OpenAPI Format, früher Swagger genannt, zur Verfügung. Die Dokumentation kann in Maschinen lesbarer Form geladen werden und unterstützt Sie dabei, die Endpunkte in der korrekten Form und Syntax anzusprechen.

Wechseln Sie dazu in Ihren Postman Workspace in den Bereich Collections und importieren Sie die OpenAPI Dokumentation von dem hier hinterlegten “Download” Link.

Sicherer Zugriff mit dem API-Token

Bevor Sie auf Meisterplan zugreifen können, brauchen Sie einen API-Token. Der API-Token ist die Zugangsberechtigung auf Ihr Meisterplan System über die REST API. Er ist an einen Meisterplan Benutzer gebunden und erbt damit die Berechtigungen des Benutzers.

Erstellen Sie also zuerst einen API-Token.

Vorbereitung der Collection für den Zugriff auf Meisterplan

Der erzeugte API-Token wird nun in Postman eingetragen, damit er von allen Endpunkten verwendet werden kann. Passen Sie die rot umrandeten Einträge an. Verwenden Sie im Feld “Key” den erzeugten API-Token.

Prüfen Sie nun noch die baseURL. Für US gehostete Meisterplan Systeme ist sie entsprechend anzupassen. Speichern Sie die Anpassung der Konfiguration für die weitere Verwendung.

Beispiel

Anhand eines Beispiels schauen wir uns die Funktionsweise der Meisterplan REST API an. Dabei wird auf diese Punkte eingegangen:

• Struktur von Requests und Responses
• Parameter verwenden
• Filter verwenden

Für tiefergehende Fragen steht die API-Dokumentation zur Verfügung.

Lesen eines Projektes mit Projektschlüssel

Zum Lesen von Projekten gibt es mehrere Endpunkte. Wir möchten das Projekt mit dem Projektschlüssel “MMP-23” lesen. Da das Feld “Projektschlüssel” (ProjectKey) nicht der technische eindeutige Schlüssel (Unique Identifier) eines Projektes ist, lesen wir aus der Liste aller Projekte und verwenden zur Identifikation des gesuchten Projektes einen Filter.

Wir verwenden den Endpunkt “Get a List of Projects”.

Sie müssen sich entscheiden, ob das Projekt aus den Plandaten oder einem Szenario gelesen wird.

Für die Plandaten wird die Konstante “PlanOfRecord” verwendet. Möchten Sie den Projektdaten eines Szenarios abfragen, verwenden Sie als scenarioId bitte die entsprechende Id. Diese kann über den Endpunkt “Get a List of Scenarios” ausgelesen werden.

Request vorbereiten

Die technischen Feldnamen finden Sie in der API-Dokumentation. Der Projektschlüssel hat den technischen Namen “projectKey” und den Typ “String”. Daraus ergibt sich folgende Syntax für den Filter:

{“projectKey”: “MPP-23”}

Alle im Bereich [Params] verwendeten Werte werden an die Aufruf-URL angefügt. Deshalb ist es erforderlich, diese in ein “URL encoded”-Format umzuwandeln. Dazu markieren Sie den umzuwandelnden Text, sodass ein Kontextmenü erscheint. Führen sie dann “Encode URl Component” durch. Nun werden alle Zeichen, die nicht in einer URL vorkommen dürfen, in Codes umgewandelt.

Aus {“projectKey”: “MPP-23”}

Wird %7B%22projectKey%22%3A%20%22MPP-23%22%7D

Um den in den vorigen Schritten festgelegten API-Token für die Abfrage zu verwenden, stellen Sie noch die [Authorization] Einstellung auf “Inherit auth from parent”.

Request ausführen

Nun können Sie Ihre erste Abfrage absenden.

Response

Als Ergebnis erhalten Sie die Daten des Projektes in einer Struktur, in unserem Beispiel im JSON-Format.

Dieses Format wird von Ihrer Middleware verstanden und kann technisch weiterverarbeitet werden.

Eine Schnittstelle entsteht.

Code Snippets generieren

Noch ein kleiner Hinweis:

Sollte Ihre Middleware Programmcode in einer bestimmten Programmiersprache benötigen, unterstützt Postman durch die Generierung von Code Snippets. Den so generierten Programmiercode können Sie in Ihrer individuellen Middleware verwenden. Es werden viele gängige Programmiersprachen unterstützt.

Starten Sie durch

Wenn sie nun erkannt haben, welches Potenzial Ihnen die Meisterplan REST API erschließen kann und wie einfach sie von etwas geübten Technikern verwendet werden kann, sprechen Sie Ihr IT-Team an. Gerne unterstützen wir Sie.

Kontakt aufnehmen