Bpanda-API nutzen

Die REST-Schnittstelle von Bpanda für Integrationen: welche Lizenz und welchen API-Client (technischer Benutzer mit Client-ID und Client-Secret) Du brauchst, wie Du ein Token holst — und welche Informationen aus CMDB, ERP, GRC oder Projektwerkzeugen Du mit Deinen Prozessen verknüpfen kannst.

Über die Public API legt Deine IT Informationen aus anderen Systemen als Architekturelemente in Bpanda an und verknüpft sie mit Prozessen. Außerdem liest sie Prozessinformationen, Organisationsstruktur, Benutzer und Gruppen aus. Jede Operation hat ihre eigene Seite in der API-Referenz — mit Parametern, Antwortformat, Codebeispielen und einem Try it-Bereich. Dieser Artikel sagt, was vorher zu tun ist, wie die Anmeldung läuft und wofür sich die API lohnt.

Voraussetzungen

• API-Lizenz. Dein Account braucht die Lizenz für die API. Sie wird vom Customer-Success-Team freigeschaltet: wecare@mid.de.
• API-Client. Den legst Du selbst in der Accountverwaltung an: im Abschnitt Account-Benutzer über ⋮ API Benutzer hinzufügen, siehe Account-Benutzer anlegen und verwalten. Er besteht aus einer Client-ID und einem Client-Secret und tritt in Bpanda als technischer Benutzer auf — der API-Benutzer. Das Secret siehst Du nur beim Anlegen — bewahre es wie ein Passwort auf.
• Eine Bpanda-Lizenz für den API-Benutzer. Neben der API-Lizenz bekommt der API-Benutzer in der Accountverwaltung eine normale Bpanda-Lizenz zugewiesen, wie jeder andere Benutzer. Damit hat er lesenden Zugriff auf den Prozessraum.
• Eine Bpanda-Rolle, wenn der API-Benutzer mehr können muss. Architekturelemente anlegen, importieren und veröffentlichen dürfen nur BPM-Manager und Prozessdesigner. Welche Rolle eine Operation verlangt, steht auf ihrer Seite in der Referenz unter Security. Die Rolle vergibst Du wie bei jedem anderen Benutzer, siehe Benutzer und Bpanda-Rollen zuordnen und Prozessdesigner und BPM-Manager festlegen.
• Account-ID. Sie steht im Pfad der Accountverwaltung, sobald Du Deinen Account geöffnet hast.

So meldest Du Dich an

Die Anmeldung ist ein einziger Aufruf ohne vorheriges Token: apiUserInfo. Du übergibst Account-ID, Client-ID und Client-Secret und bekommst alles zurück, was die weiteren Aufrufe brauchen. Die Basisadresse Deiner Umgebung steht in jedem Codebeispiel der Referenz.

curl -X POST https://<api-adresse>/bpm/api/v1/apiUserInfo -H "Content-Type: application/json" -d "{\"accountId\":\"<Account-ID>\",\"clientId\":\"<Client-ID>\",\"clientSecret\":\"<Client-Secret>\"}"

$body = @{ accountId = "<Account-ID>"; clientId = "<Client-ID>"; clientSecret = "<Client-Secret>" } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "https://<api-adresse>/bpm/api/v1/apiUserInfo" -ContentType "application/json" -Body $body

Die Antwort enthält fünf Felder:

Ein erster Aufruf, der alle Benutzer des Prozessraums liest, sieht so aus:

curl https://<api-adresse>/bpm/api/v1/warehouses/<processSpaceId>/users -H "Authorization: Bearer <token>" -H "BpmLicense: <licenseToken>"

Invoke-RestMethod -Uri "https://<api-adresse>/bpm/api/v1/warehouses/<processSpaceId>/users" -Headers @{ Authorization = "Bearer <token>"; BpmLicense = "<licenseToken>" }

Antwortet die Anmeldung mit 404 „No license token found”, fehlt dem Account die API-Lizenz. Bei 429 hast Du zu viele Aufrufe in kurzer Zeit abgesetzt — warte kurz und wiederhole den Aufruf. Läuft das Access-Token ab, rufst Du die Anmeldung einfach erneut auf — ein eigenes Erneuern gibt es nicht.

Informationen aus anderen Systemen mit Prozessen verknüpfen

Am meisten bringt die API, wenn Du Informationen aus anderen Systemen mit Deinen Prozessen verknüpfst. Dann siehst Du zum Beispiel, welche Anwendungen ein Prozess nutzt, welche Anforderungen er umsetzt oder welches Projekt ihn ändert. Diese Informationen legst Du in Bpanda als Architekturelemente an: Bpanda kennt die Elementtypen aller Ebenen von ArchiMate® 3.2, und jedes Element lässt sich mit Prozessen verknüpfen. Die Verknüpfungen wertest Du anschließend in Bpanda aus, siehe Verfügbare Auswertungen.

Die folgende Übersicht ist nach Werkzeugkategorien geordnet. Zu jeder Kategorie steht, was das System besitzt, welchen Elementtypen in Bpanda diese Daten entsprechen und welche Fragen Du beantworten kannst, wenn Du sie mit Prozessen verknüpfst.

Welche Elementtypen in Deinem Prozessraum aktiv sind, legst Du unter Architektur-Einstellungen festlegen fest; Verknüpfte Architekturelemente und Beziehungstypen erklärt, welche Beziehung wofür steht.

Prozesse in die Architektur einbetten

Zu jeder Prozessrevision gibt es in der Architektur automatisch ein Geschäftsprozess-Element. So bettest Du einen Prozess in die Architektur ein: Du legst eine Beziehung zwischen Deinem Element aus dem Fremdsystem und diesem Geschäftsprozess-Element an.

1. Lege das Element an oder aktualisiere es: createArchitectureElement, editArchitectureElement. Einen ganzen Bestand übernimmst Du mit importArchimateXml.
2. Hole das Geschäftsprozess-Element zur Prozessrevision: getArchitectureElementsByRepresentation.
3. Frage ab, welche Beziehungstypen zwischen beiden Elementen zulässig sind: findValidReferenceTypesWithDirections. Angeboten wird nur, was ArchiMate® zwischen den beiden Typen erlaubt.
4. Lege die Beziehung an: addArchitectureElementRelation. Besteht sie schon, gibt die API die vorhandene zurück statt eine zweite anzulegen.
5. Veröffentliche die Elemente: publishArchitectureElements. Bis dahin sind sie Entwürfe, wie beim Anlegen in der Oberfläche.

Zurücklesen kannst Du das Ergebnis mit findExternalUses: alle Beziehungen eines Elements oder einer Prozessrevision, zum Beispiel jeden Prozess, der eine bestimmte Anwendung nutzt.

Hinweis: Der Ablauf oben verknüpft Elemente aus anderen Systemen mit einem Prozess. Es geht auch umgekehrt: Legst Du ein Element vom Typ Geschäftsprozess an, entsteht dazu implizit ein Prozess in Bpanda — ohne Diagramm und ohne Inhalte. Über die API kannst Du diesen Prozess nicht veröffentlichen, weil die API den Freigabeworkflow derzeit nicht abbildet. Freigegeben und veröffentlicht wird ein Prozess wie gewohnt in Bpanda, siehe Prozesse freigeben und veröffentlichen.

Bpanda als Quelle für andere Werkzeuge

In der Gegenrichtung liest die API, was andere Werkzeuge über Deine Prozesse wissen müssen: Prozessinformationen, Versionen, das Diagramm als SVG, die Organisationsstruktur, Benutzer und Gruppen sowie die Architektur-Auswertungen. Damit bettest Du zum Beispiel Diagramme im Intranet ein, zeigst in einem Portal, welche Anwendungen ein Prozess nutzt, oder ermittelst Verantwortliche automatisch.

Zusammenhang

Die Referenz unter API beschreibt jede Operation vollständig und wird aus der API-Beschreibung erzeugt — sie ist immer auf dem Stand des Systems. Wie Architekturelemente und ihre Beziehungen in Bpanda funktionieren, steht im Bereich Architektur; wer in Bpanda was darf, in Rollen und Berechtigungen.