process API

process-API

Einleitung

In diesem Thema findest du allgemeine Informationen zur process-App-API, zum Funktionsumfang und zu den Kenntnissen, die hilfreich beim Programmieren von Funktionen und Anpassungen sind.

Über die process-App-API

In dieser Dokumentation erfährst du, wie du die Programmierschnittstelle der process-App für eigene Entwicklungen nutzen kannst.
Diese Dokumentation richtet sich an Entwickler von Anwendungen, die in der d.ecs architecture-Systemumgebung ausgeführt werden sollen.

Die process-App ist eine Anwendung, mit der du Prozesse ausführen, überwachen und administrieren kannst.

JSON-Objekte, URLs und Abfrageparameter (Query) können jederzeit erweitert werden, ohne dass die API ihre Gültigkeit verliert. Es sind ausschließlich die in dieser Dokumentation beschriebenen Eigenschaften, Objekte und Parameter für die API-Programmierung freigegeben.
Weitere Informationen zur Funktionsweise und zur Konfiguration der process-App findest du im Handbuch von d.ecs process.

Funktionsumfang von process-App

Mit der process-App bist du in der Lage, Geschäftsprozesse zu automatisieren. Du kannst Anwender in Form von Aufgaben an Prozessen teilnehmen lassen oder automatisierte Serviceaktivitäten ausführen. Die process-App unterstützt den BPMN-Standard. Dadurch hast du vielfältige Möglichkeiten bei der Gestaltung von Prozessen.

In der Prozessüberwachung hast du die Möglichkeit, den Status aktiver Prozesse zu kontrollieren. Im Falle eines Fehlers hast du direkt die Möglichkeit, Korrekturen vorzunehmen. Damit stellst du auf einfache Weise den erfolgreichen Betrieb von Geschäftsprozessen sicher.
Die Prozessadministration unterstützt dich dabei, Aktionen über mehrere Prozessinstanzen durchzuführen. Du kannst beispielsweise mehrere Prozessinstanzen abbrechen, diese bei Prozessänderungen in eine neue Version migrieren, fehlerhafte Prozessinstanzen erneut ausführen oder eine Prozessversion löschen.

Wenn du einen eigenen Prozess modelliert hast, kannst du diesen in der Prozessadministration bereitstellen. Der Prozess steht dann in der d.3ecm-Welt zur Verfügung.

Voraussetzungen

  • Du solltest mit der Authentifizierung mit der identity provider-API im d.3ecm-Kontext vertraut sein.
  • Du solltest über Kenntnisse in der Entwicklung webbasierter Apps verfügen und sicher im Umgang mit folgenden Detailthemen sein:
    • Hypertext Transfer Protocol (HTTP) (RFC 7230)
    • RESTful HTTP-Schnittstellen
    • JavaScript Object Notation (JSON) (RFC 7159)
    • Hypertext Application Language in Verbindung mit der JavaScript Object Notation (HAL+JSON)
    • UriTemplate (RFC 6570)

Technische Hintergrundinformationen

Die process-App verwendet für die Bereitstellung öffentlicher API-Funktionen eine HTTP-Schnittstelle, die über die Basisadresse von d.ecs http gateway verfügbar ist.

Für die Verwendung dieser Funktionen ist in den meisten Fällen eine Authentifizierung mit d.ecs identity provider notwendig.

Verwenden der API-Funktionen

Im Folgenden lernst du die unterschiedlichen Möglichkeiten kennen, die Schnittstellen der process-App für deine Anforderungen zu verwenden. Alle genannten URIs beziehen sich relativ auf die URI von d.ecs process '/process'.

Authentifizierung

Einige API-Funktionen der process-App benötigen eine gültige Authentifizierung von der Identityprovider-App.

Wie eine solche Authentifizierung erlangt werden kann, kannst du der API-Dokumentation der Identityprovider-App entnehmen.

Bereitstellen von Prozessen

Mithilfe dieser HTTP-Schnittstelle kannst du einen Prozess bereitstellen. Für die Nutzung dieser Schnittstelle ist eine Authentifzierung mit IdentityProvider notwendig. Der Benutzer benötigt die Rolle Prozess-Benutzer.

Das Bereitstellen von Prozessen besteht aus drei Schritten:

  1. Erzeugen eines Deployments.
  2. Hinzufügen von BPMN.
  3. Aktivieren des Deployments.

Erzeugen des Deployments

Ein Deployment stellt einen Prozess dar, der für eine spätere Aktivierung vorgesehen ist. Solange ein Deployment nicht aktiviert ist, kann der Prozess nicht gestartet werden.

Verwende zum Erzeugen eines Deployments folgende Anforderung:

Request
   POST /process/deployment
Accept: application/json

{ 
	"source" : "app-123",
	"_links" : { 
		"processSource" : { 
			"href" : "/app-123/deployments/my-deployment-1"
		}
 	}
 }


Hinweis zum Content:

Im Content können die Daten des anzulegenden Deployments mitgegeben werden.

  • source: Die Quelle, aus der das Deployment kommt, bspw. der Name der App, die das Deployment bereitstellt. Pflichtfeld. Der Wert darf nicht leer sein. Erlaubte Zeichen sind: a-z, 0-9, -
  • _links:
    • processSource: Der URI, unter welchem das Deployment abgefragt werden kann. Die process-App speichert Prozessdefinitionen lediglich als BPMN. Dieser URI dient dazu, die Prozessdefinition in der Form bereitzustellen, in der sie erstellt worden ist.
      Dieser URI sollte dauerhaft verfügbar sein und die Prozessdefinition genau in der Version darstellen, die sie zum Zeitpunkt des Deployments innehatte. Optional.

Rückgabewerte der Abfrage:

  • 201: Erfolgsfall. Das Deployment wurde erzeugt und für eine spätere Bearbeitung und Aktivierung gespeichert.
  • 400: Der Request ist ungültig. Beachte den Hinweis zum Content.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, ein Deployment zu erzeugen.

Im Erfolgsfall wird der HTTP-Status-Code 201 zurückgegeben. Der Location-Header enthält dann den URI, unter welchem du das Deployment abfragen kannst. Zusätzlich ist das Deployment bereits im Body enthalten. Über dessen Link bpmn kannst du direkt das BPMN hinzufügen.

Abfragen des Deployments

Du kannst ein Deployment abfragen, um herauszufinden, ob es gültig ist und über welchen URI du es aktivieren kannst. Die Gültigkeit hängt davon ab, ob der enthaltene Prozess BPMN-konform ist.

Du kannst ein Deployment in zwei Formaten abfragen: als JSON oder HTML. Die HTML-Repräsentation ist ein Dialog, in dem du das Deployment über eine Benutzeroberfläche aktivieren kannst.

Abfragen des Deployments im JSON-Format

Frage das Deployment im JSON-format folgendermaßen ab:

Request
   GET /<Deployment Location Header-URI>
Accept: application/json, application/hal+json

Ersetze den Platzhalter <Deployment Location Header-URI> mit dem URI aus dem Location-Header, der beim Erzeugen des Deployments zurückgegeben wurde.

Falls das Deployment gültig ist, wird folgendes JSON zurückgegeben:

Response
   {
	 "type": "BPMN",
	 "valid": true,
	 "_links":{
		 "activation":{
			 "href": "/process/deployment/randomId/activate"
		 },
		 "bpmn" : {
			 "href" : "/process/deployment/randomId/staging/bpmn"
		 }, 
		"processSource" : {
			"href" : "/app-123/deployments/my-deployment-1"
		}
	}
}

Anmerkungen zu den Links:

  • bpmn: Mit dieser Linkrelation kannst du das BPMN zum Deployment hinzufügen.
  • activation: Mit dieser Linkrelation kannst du das Deployment aktivieren. Dieser Link ist nur verfügbar, wenn das Deployment gültig ist.

Falls das Deployment ungültig ist, wird folgendes JSON zurückgegeben:

Response
   {
	 "type": "BPMN",
	 "valid": false,
	 "invalidReason": "Process deployment is invalid: Process with ID 'myProcessId' but another capitalization already exists",
	 "invalidReasonKey": "idMismatch"
}

Der Parameter invalidReasonKey identifiziert den Grund für die Ungültigkeit des Deployments technisch lesbar, sofern dieser angegeben werden kann. Bei unspezifischen Gründen, wie z.B. einem Fehler beim Parsen des BPMN-XMLs, ist dieser Parameter in der Antwort nicht vorhanden. Folgende Werte sind aktuell möglich:

  • mixedOperation: Bei diesem Fehler existiert der zu deployende Prozess bereits als Einmalprozess.
  • idMismatch: Bei diesem Fehler existiert bereits ein Prozess mit dieser ID aber mit einer anderen Groß-/Kleinschreibung.
  • userTaskAssignment: Bei diesem Fehler wurden die Regeln für die Zuweisung von Empfängern in Bezug auf die humanPerformer- und potentialOwner-Konstrukte nicht beachtet.
  • invalidBpmn: Bei diesem Fehler wurde ein ungültiges BPMN-Modell hochgeladen.
  • unknown: Bei diesem Fehler kann der Grund nicht näher spezifiziert werden.


Abfragen des Deployments im HTML-Format

Frage das Deployment im HTML-Format folgendermaßen ab:

Request
   GET /<Deployment Location Header-URI>
Accept: text/html

Es wird eine HTML-Seite zurückgegeben, in der angezeigt wird, ob das Deployment gültig ist, und über die das Deployment aktiviert werden kann.

Rückgabewerte der Abfrage:

  • 200: Erfolgsfall. Das Deployment ist als HTML bzw. JSON im Body enthalten.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, das Deployment abzufragen.
  • 404: Das Deployment existiert nicht.

Hinzufügen von BPMN

Du kannst den BPMN-Prozess über einen separaten URI zum Deployment hinzufügen.

Request
   PUT /<Deployment bpmn-URI>
Content-Type: application/bpmn

<BPMN XML content of a process>


Hinweis zum Content:

Der Content enthält einen Prozess in BPMN.

Rückgabewerte der Abfrage:

  • 200: Das BPMN wurde zum Deployment hinzugefügt.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, ein Deployment zu bearbeiten.
  • 404: Das Deployment existiert nicht.

Aktivieren des Deployments

Wenn ein Deployment gültig ist, kannst du es aktivieren. Anschließend kannst du den Prozess ausführen. Nach erfolgreicher Aktivierung ist das Deployment nicht mehr verfügbar und du kannst es nicht mehr abfragen.

Request
   POST /<Deployment activation-URI>


Rückgabewerte der Abfrage:

  • 200: Das Deployment wurde erfolglreich aktiviert.
  • 400: Das Deployment ist ungültig.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, das Deployment zu aktivieren.
  • 404: Das Deployment existiert nicht.
  • 409: Ein Einmalprozess mit derselben ID wurde bereits gestartet.

Deployment löschen

Falls ein Deployment nicht aktiviert werden soll, kannst du es löschen.

Zum Löschen des Deployments verwendest du folgende Anforderung:

Request
   DELETE /<Deployment Location Header-URI>


Rückgabewerte der Abfrage:

  • 200: Das Deployment wurde erfolglreich gelöscht.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, das Deployment zu löschen.
  • 404: Das Deployment existiert nicht.

Bereitstellen von Einmalprozessen

Mit dieser HTTP-Schnittstelle kannst du einen Einmalprozess bereitstellen. Für die Nutzung dieser Schnittstelle ist eine Authentifzierung an IdentityProvider notwendig. Der Besitzer benötigt die Rolle Prozessbenutzer oder Prozessadministrator.

Der Einmalprozess wird nach einmaliger, erfolgreicher Ausführung oder Abbruch automatisch wieder aus dem System entfernt. Auch Historien-Daten der ausgeführten Prozessinstanz werden nach Abschluss oder Abbruch der Instanz wieder entfernt.

Der Vorgang zum Bereitstellen eines Prozesses besteht aus drei Schritten:

  1. Erzeugen eines Deployments.
  2. Hinzufügen von BPMN.
  3. Aktivieren des Deployments und starten des Prozesses.

Erzeugen des Deployments

Ein Deployment stellt einen Prozess dar, der für eine spätere Aktivierung vorgesehen ist. Solange ein Deployment nicht aktiviert ist, ist der enthaltene Prozess nicht im Workflowmodul verfügbar und kann daher nicht ausgeführt werden.

Verwende zum Erzeugen eines Deployments folgende Anforderung:

Request
   POST /process/singleusedeployment
Content-Type: application/json

{
	"source" : "app-123",
	"_links" : {
		"processSource" : {
			 "href" : "/app-123/deployments/my-deployment-1"
		}
	}
}


Hinweis zum Content:

Im Content können die Daten des anzulegenden Deployments mitgegeben werden.

  • source: Die Quelle, aus welcher das Deployment kommt, bspw. der Name der App, welche das Deployment bereitstellt. Pflichtfeld. Der Wert darf nicht leer sein. Erlaubte Zeichen sind: a-z, 0-9, -
  • _links:
    • processSource: Der URI, unter welchem das Deployment abgefragt werden kann. Die process-App speichert Prozessdefinitionen als BPMN. Dieser URI dient dazu, die Prozessdefinition in der Form bereitzustellen, in der sie erstellt worden ist. Dieser URI sollte dauerhaft verfügbar sein und die Prozessdefinition genau in der Version darstellen, die sie zum Zeitpunkt des Deployments innehatte. Optional.

Rückgabewerte der Abfrage:

  • 201: Erfolgsfall. Das Deployment wurde erzeugt und für eine spätere Bearbeitung und Aktivierung gespeichert.
  • 400: Der Request ist ungültig. Beachte den Hinweis zum Content.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, ein Deployment zu erzeugen.

Im Erfolgsfall wird der HTTP-Status-Code 201 zurückgegeben. Der Location-Header enthält dann den URI, unter welchem du das Deployment abfragen kannst. Zusätzlich ist das Deployment bereits im Body enthalten. Über dessen Link bpmnUri kannst du direkt das BPMN hinzufügen.

Abfragen des Deployments

Du kannst ein Deployment abfragen, um herauszufinden, ob es gültig ist und über welchen URI du es aktivieren kannst. Die Gültigkeit hängt davon ab, ob der enthaltene Prozess BPMN-konform ist.

Du kannst ein Deployment in zwei Formaten abfragen: als JSON oder HTML.

Abfragen des Deployments im JSON-Format

Frage das Deployment im JSON-Format folgendermaßen ab:

Request
   GET /<Deployment Location Header-URI
application/json, application/hal+json

Ersetze den Platzhalter <Deployment Location Header-URI> mit dem URI aus dem Location-Header, der beim Erzeugen des Deployments zurückgegeben wurde.

Falls das Deployment gültig ist, wird folgendes JSON zurückgegeben:

Response
   {
	"type": "BPMN",
	"valid": true,
	"_links":{
		"start":{
			"href": "/process/singleusedeployment/f4da94c4-41c1-44bb-9223-1cdfb18bbe24/start"
		},
		"bpmn" : {
			"href" : "/process/singleusedeployment/f4da94c4-41c1-44bb-9223-1cdfb18bbe24/staging/bpmn"
		},
		"processSource" : {
			"href" : "/app-123/deployments/my-deployment-1"
		}
	}
}

Anmerkungen zu den Links:

  • bpmn: Mit dieser Linkrelation kannst du das BPMN zum Deployment hinzufügen.
  • start: Mit dieser Linkrelation kannst du das Deployment aktivieren und starten. Dieser Link ist nur verfügbar, wenn das Deployment gültig ist.

Falls das Deployment ungültig ist, wird folgendes JSON zurückgegeben:

Response
   {
	"type": "BPMN",
	"valid": false,
	"invalidReason": "Process deployment is invalid: Process with ID 'myProcessId' but another capitalization already exists",
    "invalidReasonKey": "idMismatch"
}

Der Parameter invalidReasonKey identifiziert den Grund für die Ungültigkeit des Deployments technisch lesbar, sofern dieser angegeben werden kann. Bei unspezifischen Gründen, wie z.B. einem Fehler beim Parsen des BPMN-XMLs, ist dieser Parameter in der Antwort nicht vorhanden. Folgende Werte sind aktuell möglich:

  • mixedOperation: Bei diesem Fehler existiert der zu deployende Einmalprozess bereits als dauerhaft bereitgestellter Prozess.
  • idMismatch: Bei diesem Fehler existiert bereits ein Prozess mit dieser ID aber mit einer anderen Groß-/Kleinschreibung.
  • userTaskAssignment: Bei diesem Fehler wurden die Regeln für die Zuweisung von Empfängern in Bezug auf die humanPerformer- und potentialOwner-Konstrukte nicht beachtet.
  • invalidBpmn: Bei diesem Fehler wurde ein ungültiges BPMN-Modell hochgeladen.
  • unknown: Bei diesem Fehler kann der Grund nicht näher spezifiziert werden.

Rückgabewerte der Abfrage:

  • 201: Erfolgsfall. Das Deployment ist als JSON im Body enthalten.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, ein Deployment abzufragen.
  • 404: Das Deployment existiert nicht.


Abfragen des Deployments im HTML-Format

Frage das Deployment im HTML-Format folgendermaßen ab:

Request
   GET /<Deployment Location Header-URI>
Accept: text/html

Es wird eine HTML-Seite zurückgegeben, in der angezeigt wird, ob das Deployment gültig ist, und über die das Deployment aktiviert werden kann.

Rückgabewerte der Abfrage:

  • 200: Erfolgsfall. Das Deployment ist als HTML im Body enthalten.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, das Deployment abzufragen.
  • 404: Das Deployment existiert nicht.

Hinzufügen von BPMN

Du kannst den BPMN-Prozess über einen separaten URI zum Deployment hinzufügen.

Request
   PUT /<Deployment bpmn-URI>
Content-Type: application/bpmn

<BPMN file of a process>


Hinweis zum Content:

Der Content enthält einen Prozess in BPMN.

Rückgabewerte der Abfrage:

  • 200: Das BPMN wurde zum Deployment hinzugefügt.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, ein Deployment zu bearbeiten.
  • 404: Das Deployment existiert nicht.

Aktivieren des Deployments und Starten des Prozesses

Wenn ein Deployment gültig ist, kannst du es aktivieren und den Prozess starten. Hierbei wird der enthaltene Prozess im Workflowmodul bereitgestellt und anschließend gestartet. Nach erfolgreicher Aktivierung ist das Deployment nicht mehr verfügbar und du kannst es nicht mehr abfragen.

Request
   POST /<Deployment start-URI>
Content-Type: application/json

{ 
	"businessKey" : "myBusinessKey",
	"variables" : {
		"variable_1" : "value"
	},
	"_links" : {
 		"endCallback" : {
			"href" : "/myapp/callback"
		}
	}
}

Ersetze den Platzhalter <Deployment start-URI> durch den start-URI, der beim Abfragen des Deployments zurückgegeben wurde.

Hinweise zum Content:

  • businessKey: Business-Key für die Prozessinstanz. Ein Business-Key ist ein frei zu vergebener externer Schlüssel, mit dem die Prozessinstanz identifiziert werden kann. Dieser spielt zur Laufzeit keine Rolle (optional, max. 255 Zeichen).
  • variables: Initiale Prozessvariablen (optional). Format siehe Grundlegendes zu Prozessvariablen.
  • _links: Verknüpfungen (optional).


Mögliche Verknüpfungen

Der URI endCallback wird beim erfolgreichen Abschluss oder Abbruch dieser Prozessinstanz mit der HTTP POST-Anforderung aufgerufen. Der Aufruf ist identisch zu dem Vorgang unter Starten von Prozessen.

Rückgabewerte der Abfrage:

  • 200: Das Deployment wurde erfolglreich aktiviert und der Prozess gestartet.
  • 400: Das Deployment oder die Prozessvariablen sind ungültig.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, das Deployment zu aktivieren.
  • 404: Das Deployment existiert nicht.
  • 409: Ein Prozess mit derselben ID wurde bereits dauerhaft gestartet.

Wenn das Starten des Prozesses fehlschlägt, z.B. aufgrund ungültiger Variablen, bleibt das Deployment anschließend bestehen. Du kannst versuchen, die Aktivierung bzw. den Start erneut auszuführen. Wenn du das Deployment verwerfen möchtest, muss es entsprechend durch den Client gelöscht werden.


Löschen des Deployments

Falls ein Deployment nicht aktiviert werden soll, kannst du es löschen.

Zum Löschen eines Deployments verwendest du folgende Anforderung:

Request
   DELETE /<Deployment Location Header-URI>

Rückgabewerte der Abfrage:

  • 200: Das Deployment wurde erfolglreich gelöscht.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, das Deployment zu löschen.
  • 404: Das Deployment existiert nicht.

Starten von Prozessen

Mit dieser HTTP-Schnittstelle kannst du einen Prozess starten. Für die Nutzung dieser Schnittstelle ist eine Authentifzierung notwendig. Der Benutzer benötigt die Rolle Prozessbenutzer.

Verwende folgenden Request zum Starten eines Prozesses:

Request
   POST /process/processes/{id}/instances
Content-Type: application/json

{
	"businessKey" : "myBusinessKey",
	"variables" : {
		"variable_1" : "value"
	},
	"_links" : {
		"endCallback" : {
			"href" : "/myapp/callback"
		}
	}
}

Ersetze den Platzhalter {id} durch die ID der Prozessdefinition.

Hinweise zum Content:

  • businessKey: Business-Key für die Prozessinstanz. Ein Business-Key ist ein frei zu vergebener externer Schlüssel, mit dem die Prozessinstanz in der Prozessüberwachung identifiziert werden kann (optional, max. 255 Zeichen).
  • variables: Initiale Prozessvariablen (optional). Gültige Variablen siehe Grundlegendes zu Prozessvariablen.
  • _links: Verknüpfungen (optional).

Mögliche Verknüpfungen

Der URI endCallback wird beim erfolgreichen Abschluss oder Abbruch der Prozessinstanz mit der HTTP POST-Anforderung aufgerufen. Liegt der URI hinter der Basisadresse, wird der Aufruf im Namen des konfigurierten Systembenutzers der process-App aufgerufen.
Die Daten werden in folgendem Format übermittelt:

Request
   POST /myapp/callback
Content-Type: application/json

{
	"process" : "myProcess",
	"event" : "END",
	"timestamp" : "2018-07-24T08:53:55.622+02:00",
	"variables" : {
		"variable_1" : "value"
	},
	"links": {
		"instance": {
			"href": "/process/instances/myInstance"
		}
	}
}

Bedeutung der Felder:

  • process: Der Bezeichner des Prozesses.
  • event: Das Ereignis. Enthält den Wert END für einen erfolgreichen Abschluss und den Wert CANCELLED bei einem manuellen Abbruch.
  • timestamp: Zeitpunkt des Ereignisses (RFC3339 formatiert).
  • variables: Variablen zum Zeitpunkt des Endes. Wird bei manuellem Abbruch nicht gesendet. Format siehe Grundlegendes zu Prozessvariablen.
  • links: Verknüpfungen. Die Linkrelation instance zeigt auf die dazugehörige Prozessinstanz in der Prozessüberwachung (bei Einmalprozessen nicht vorhanden).


Wichtig

Sollte es bei der Konvertierung der Variablen zu einem Fehler kommen, wird die betroffene Variable nicht mit dem Callback übermittelt. Eine mögliche Fehlerursache sind z.B. Inkonsistenzen zwischen Datentyp und tatsächlichem Wert.

Rückgabewerte der Abfrage:

  • 201: Der Prozess wurde für den Start eingeplant.
  • 400: Die Anfrage ist nicht gültig.
  • 401: Der Benutzer ist nicht angemeldet.
  • 403: Der Benutzer hat nicht das Recht Prozesse zu starten.
  • 404: Es existiert keine Prozessdefinition zu dem Prozess-Key.
  • 405: Es ist nicht erlaubt Einmalrozesse per API zu starten.

Einbinden von externen Diensten

In diesem Kapitel erfährst du, wie du externe Dienste an die process-App anbinden kannst.

Erstellen eines externen Dienstes

Erreicht der Prozess eine Aktivität, wird der Endpunkt eines externen Dienstes aktiv von der process-App angesprochen. Je nach Wahl kann der Dienst die Anfrage synchron bearbeiten oder asynchron zu einem späteren Zeitpunkt beantworten.

Die Anfrage wird im Namen des Systembenutzers von der process-App durchgeführt.

Die folgenden Daten werden übermittelt:

Request
   POST /myapp/service
Content-Type: application/json

{
	"input" : {
        "variable_1": ["value 1", "value 2"],
        "variable_2": "value",
		"variable_3": 42.0,
		"variable_4": ["identity:///identityprovider/scim/users/someUserIDPId", "identity:///identityprovider/scim/groups/someGroupIDPId"]
    },
    "_links" : {
        "success" : { "href" : "/process/custom/response/1232354/success" },
        "fail" : { "href" : "/process/custom/response/1232354/fail" }
    }
}

Die Felder haben folgende Bedeutung:

  • input: Dieses Feld enthält Eingabewerte für den Service. Das Format wird im Abschnitt Grundlegendes zu Prozessvariablen genauer beschrieben.
  • _links: Verknüpfungen (nur für asynchrone Services).


Synchrone Antwort

Ein synchroner Dienst kann auf die Anfrage mit dem Statuscode 200 und folgendem Body beantworten:

Response
   Content-Type: application/json

{
    "output" : {
        "variable_1": ["value 1", "value 2"],
        "variable_2": "value",
		"variable_3": 42.0,
		"variable_4": ["identity:///identityprovider/scim/users/someUserIDPId", "identity:///identityprovider/scim/groups/someGroupIDPId"]
    }
}

Das Feld output enthält die Ausgabewerte des Dienstes.

Im Fehlerfall können folgende Daten übermittelt werden:

  • 400: Die Anfrage ist ungültig. Es werden keine weiteren Versuche ausgeführt. Verwende diesen Statuscode, wenn bereits beim Validieren der Eingabeparameter ein Fehler auftritt.
  • 404: Der Dienst ist nicht erreichbar. Es können weitere Versuche ausgeführt werden.
  • 500: Es ist ein interner Fehler aufgetreten. Es können weitere Versuche ausgeführt werden. Verwende diesen Statuscode, wenn während der Verarbeitung ein Fehler auftritt.

Im Antwortkörper kann eine Fehlernachricht übertragen werden:

Response
   Content-Type: application/json

{
    "error" : "Error reason"
}


Asynchrone Antwort

Ein asynchroner Dienst kann die Anfrage mit dem Statuscode 200 oder 202 und ohne Body beantworten. Kann die Anfrage bereits nicht entgegengenommen werden, werden die folgenden Fehlercodes übermittelt:

  • 400: Die Anfrage ist ungültig. Es werden keine weiteren Versuche ausgeführt. Verwende diesen Statuscode, wenn bereits beim Validieren der Eingabeparameter ein Fehler auftritt.
  • 404: Der Dienst ist nicht erreichbar. Es können weitere Versuche ausgeführt werden.
  • 500: Es ist ein interner Fehler aufgetreten. Es können weitere Versuche ausgeführt werden. Verwende diesen Statuscode, wenn während der Verarbeitung ein Fehler auftritt.

Zu einem späteren Zeitpunkt kann der Dienst eine der Verknüpfungen success oder fail mit der HTTP-Anforderung POST aufrufen, um Erfolg oder einen Fehler zu melden. Eine Authentifizierung von der identity provider-App ist hierfür nicht erforderlich.

Im Fehlerfall können folgende Daten übermittelt werden:

Response
   POST /process/custom/response/1232354/fail
Content-Type: application/json

{
    "error" : "Error reason"
}


Folgende Statuscodes sind sowohl bei synchronen als auch bei asynchronen Antworten möglich:

  • 200: Die Antwort ist gültig und der Prozess wird fortgeführt.
  • 400: Die Anfrage ist ungültig (z.B. weil ungültige Variablen übergeben wurden).
  • 409: Der Prozess ist aktuell nicht in einem State, in dem die Antwort verarbeitet werden kann. In diesem Fall muss die Antwort zu einem späteren Zeitpunkt noch einmal probiert werden.
  • 500: Es ist ein interner Fehler aufgetreten.

Im Falle einer nicht erfolgreichen Verarbeitung wird im Prozess ein Fehlerzustand erzeugt. Mit diesem Fehlerzustand kann ein Administrator den Service-Aufruf erneut ausführen.

Resilienz bei asynchronen Diensten

Ein asynchroner externer Dienst sollte resilient sein. Es ist möglich, dass der Endpunkt der process-App zum Zeitpunkt des Aufrufs nicht verfügbar ist. In dem Fall erhält der externe Dienst eine Antwort mit dem Statuscode 404 oder 503. Ist der Endpunkt der process-App zum Zeitpunkt des Aufrufs nicht verfügbar, muss die Antwort zu einem späteren Zeitpunkt erneut gesendet werden.

Grundlegendes zu Prozessvariablen

Folgende Funktionen verwenden Prozessvariablen:

  • Starten von Prozessen
  • Starten von Einmalprozessen
  • Benachrichtigungen beim Prozessabschluss
  • Lesen, Ändern und Hinzufügen von Prozessvariablen zu einer Benutzeraufgabe

Die Prozessvariablen werden bei all diesen Funktionen im selben Format übertragen.

Voraussetzung in der Prozessdefinition

Variablendefinitionen: Alle Variablen, die du verwenden möchtest, müssen zunächst in BPMN definiert werden. Wie du die Variablen definierst, kannst du in der Dokumentation der process-App nachlesen.

Input-Mapping: Wenn aus einer Benutzeraktivität auf Prozessvariablen zugegriffen werden soll, musst du innerhalb der Prozessdefinition ein Input-Mapping für diese Variablen hinzufügen.
Falls kein Mapping durchgeführt wird, stehen diese Variablen möglicherweise nicht zur Verfügung.

Output-Mapping: Wenn eine Benutzeraktivität Prozessvariablen verändern oder erzeugen soll, musst du hierzu ein Output-Mapping definieren. Nur dann stehen sie im weiteren Prozessverlauf zur Verfügung.

Format von Prozessvariablen

Generell erfolgt die Übergabe aller Prozessvariablen in einem JSON-Objekt. Innerhalb dieses Objektes wird ein Name-Wert-Paar pro Prozessvariable übertragen. Der Schlüssel steht dabei jeweils für den Namen der Prozessvariablen aus der Prozessdefinition.

Beispiel

   {
	"variable_1" : "some value",
    "variable_2" : ["multiple", "values"]
}

Prozessvariablen werden je nach Typ in unterschiedlichen Arten per JSON übertragen. Für die vorhandenen Datentypen gelten diese Regeln:

DatentypÜbertragung alsBeispiel
StringJSON String"Hello"
NumberJSON Number47.11
IdentityJSON String in diesem Format:
identity://{uri}
"identity:///identityprovider/scim/users/johndoe"
DmsObject

JSON String in diesem Format:
dmsObject://{uri}

"dmsObject:///dms/r/123/o2/xyz"

Entfernen einer Variable

Um einen Wert bei einer schreibenden API-Funktion zu löschen, kannst du den Wert null übergeben.
Bei anschließendem Lesen taucht diese Variable nicht mehr auf.

   {
	"variable_1" : null
}

Mehrfachwerte

Mehrfachwerte werden als JSON Arrays dargestellt. Diese müssen mindestens einen Wert des dazugehörigen Datentyps enthalten. Null-Werte und Werte eines anderen Datentyps sind in Mehrfachwerten nicht erlaubt.

Beispiel für Mehrfachwerte

   ["dog", "cat", "horse"]

Pflichtvariablen

Variablen, die als Pflichtvariablen definiert wurden, können nicht gelöscht werden, wenn diese einmal geschrieben wurden. Außerdem dürfen Pflichtvariablen vom Datentyp String keinen leeren String enthalten.

Für Pflichtvariablen bei externen Diensten gelten zusätzlich diese Regeln:

  • Eingabevariablen: Ist eine Eingabevariable nicht vorhanden oder leer, wird im Prozess ein Fehler erzeugt und der Service wird nicht aufgerufen.
  • Ausgabevariablen: Gibt der Service-Aufruf eine Pflichtvariable nicht in der Antwort mit, wird im Prozess ein Fehler erzeugt.

Validierung

Bei der Übergabe von Prozessvariablen werden alle übergebenen Daten gegen die Prozessdefinition validiert. Wenn die Validierung fehlschlägt, wird mit dem Statuscode 400 geantwortet.

Bei folgenden Situationen wird die Annahme verweigert:

  • Für eine übergebene Variable existiert keine Definition.
  • Der übergebene Datentyp weicht von der Definition ab.
  • Eine Pflichtvariable soll gelöscht werden.

Zugreifen auf Prozessvariablen in einer Benutzeraktivität

Über diese HTTP-Schnittstelle kannst du auf Prozessvariablen zugreifen. Der Zugriff ist nur dann möglich, wenn sich ein Prozess in einer Benutzeraktivität befindet und eine Prozessinstanz sich aktuell genau in diesem Schritt befindet.

Der URI dieser Ressource muss dynamisch mit dem Ausdruck ${process.task.variablesUri} für den "Form Key" einer Bearbeitungsmaske ermittelt werden. Nähere Informationen dazu findest du in der Dokumentation von der process-App.

Diese Funktion kann verwendet werden, um in einer Benutzeroberfläche auf die Prozessvariablen zuzugreifen. Für die Nutzung dieser Schnittstelle ist eine Authentifzierung am IdentityProvider notwendig.

Für den Zugriff auf Prozessvariablen verwende folgende Anforderung:

Request
   GET /${process.task.variablesUri}
Accept: application/hal+json


Response
   {
	"variables": {
		"variable_1" : ["value 1", "value 2"],
		"variable_2" : "value",
		"variable_3": 42.0,
		"variable_4": ["identity:///identityprovider/scim/users/someUserIDPId", "identity:///identityprovider/scim/groups/someGroupIDPId"] 
	}
}

Das Feld variables beinhaltet die Prozessvariablen. Nähere Informationen zum Format erhältst du im Abschnitt Grundlegendes zu Prozessvariablen.

Sollte es bei der Konvertierung der Variablen zu einem Fehler kommen, wird die betroffene Variable nicht mit der Antwort übermittelt. Ein möglicher Fehler ist beispielsweise eine Inkonsistenz zwischen Datentyp und tatsächlichem Wert.

Rückgabewerte der Abfrage:

  • 200: Variablen wurden erfolgreich zurückgegeben.
  • 400: Die Anfrage ist ungültig.
  • 401: Es wurde keine gültige Authentifizierung übergeben.
  • 404: Die angegebene Aufgabe existiert nicht.
  • 409: Die angegebene Aufgabe wurde noch nicht erfolgreich an den Benutzer (d.ecs task) zugestellt.


Ändern oder hinzufügen von Prozessvariablen aus einem Benutzerschritt

Mit dieser Funktion kannst du einen Teil der Prozessvariablen ändern.

Request
   PUT /${process.task.variablesUri}
Content-Type: application/json

{
	"variables" : {
		"variable_1" : ["value 1", "value 2"],
		"variable_2" : "value",
		"variable_3": 42.0,
		"variable_4": ["identity:///identityprovider/scim/users/someUserIDPId", "identity:///identityprovider/scim/groups/someGroupIDPId"]
	}
}

Hinweis

Nur der aktuelle Bearbeiter der Benutzeraktivität darf Änderungen an den Variablen durchführen.


Rückgabewerte der Abfrage:

  • 200: Variablen wurden erfolgreich geändert.
  • 400: Die Anfrage ist ungültig.
  • 401: Es wurde keine gültige Authentifizierung übergeben.
  • 403: Der Benutzer hat nicht das Recht, die Variablen zu ändern
  • 404: Die angegebene Aufgabe existiert nicht.

Ermitteln der Positionen einer Prozessinstanz

Über folgende HTTP-Schnittstelle kannst du auf die aktuellen Positionen in der Prozessinstanz zugreifen. Für die Nutzung dieser Schnittstelle ist eine Authentifzierung an der Identityprovider-App notwendig. Der Zugriff ist nur dann möglich, wenn dem ausführenden Benutzer die Rolle Prozessadministrator zugewiesen ist, oder wenn er diese Prozessinstanz gestartet hat.

Zum Ermitteln der Positionen einer Prozessinstanz verwende folgende Anforderung:

Request
   GET /process/instances/{instanceId}/positions
Accept: application/hal+json
Response
   {
	"positions":[
		{
			"id": "Task_12925fl",
			"name": "My User Task",
			"positionType": "USER", "positionInformation":{
			"task": "https://system.base.uri/task/tasks/3utbnl5etn81oe08768j7s1283"
			}
		}
	]
}

Rückgabewerte der Abfrage:

  • 200: Die Positionen wurden erfolgreich zurückgegeben.
  • 302: Weiterleitung an d.ecs identity provider zwecks Authentifizierung.
  • 403: Der Benutzer ist nicht berechtigt, die Positionen abzurufen.
  • 404: Die angegebene Prozessinstanz existiert nicht.
  • 410: Die angegebene Prozessinstanz läuft nicht mehr (Status Beendet oder Abgebrochen).