Process-App

Process-App

 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.

 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.

 Technische Hintergrundinformationen

Die Process-App verwendet für die Bereitstellung öffentlicher API-Funktionen eine HTTP-Schnittstelle, die über die Basisadresse der HTTPGateway-App verfügbar ist. Für die Verwendung dieser Funktionen ist in den meisten Fällen eine Authentifizierung mit der Identityprovider-App 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 der Process-App '/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 der Identityprovider-App notwendig. Der Benutzer benötigt die Rolle Prozessbenutzer.

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 Inhalt

Im Inhalt kannst du die Daten des zu erstellenden Deployments mitgeben.

  • source: Die Quelle, aus der das Deployment kommt, bspw. der Name der App, die das Deployment bereitstellt. Pflichtfeld. Der Wert darf nicht leer sein und maximal 255 Zeichen enthalten. 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: Die Anfrage ist ungültig. Beachte den Hinweis zum Inhalt.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, ein Deployment zu erzeugen.

Im Erfolgsfall wird der HTTP-Statuscode 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. Mit 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. 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:


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 der Grund 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 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. Mit dieser HTML-Seite kannst du das Deployment aktivieren.

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 zu 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

Hinweise zum Inhalt

Der Inhalt muss gültiges BPMN mit einer maximalen Größe von 1MB enthalten.

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}
Accept: application/json

{
    "protocol" : true,
    "exportProtocol" : false,
    "protocolRetentionTime" : "P30D",
    "processInstanceRetentionTime" : "P30D"
}

Hinweise zum Inhalt

Im Inhalt kannst du folgende Informationen für das zu aktivierende Deployment mitgeben.

  • protocol: Wenn der Wert true ist, dann wird für Instanzen der neuen Prozessdefinition ein Protokoll erstellt. Wenn der Wert false ist, darfst du keinen der folgenden Parameter verwenden.
  • exportProtocol: Wenn der Wert true ist, dann wird das Protokoll nach Abschluss der Instanz in die DMS-App exportiert. Voraussetzung zum Verwenden der Funktion ist, dass der Protokollexport vollständig konfiguriert wurde. In diesem Fall darfst du keine Aufbewahrungsfrist im Parameter protocolRetentionTime angeben.
  • protocolRetentionTime: Gibt die Dauer an, wie lange das Protokoll nach Abschluss des Prozesses im System behalten wird. Diesen Wert musst du angeben, wenn exportProtocol den Wert false hat. Du musst einen Wert zwischen 0 und 365 Tagen im Format ISO-8601 angeben. Wenn du 0 Tage konfigurierst, wird das Protokoll unmittelbar nach Beendigung der Prozessinstanz gelöscht. Dieser Wert darf nicht größer als der Wert von processInstanceRetentionTime sein (sofern größer als 0).

Wenn du keinen Inhalt mitgibst, wird der Standard für die Protokollkonfiguration verwendet. Die standardmäßige Konfiguration lautet folgendermaßen: protocol=true, exportProtocol=false und protocolRetentionTime=P30D.

  • processInstanceRetentionTime: (Optional) Gibt die Dauer an, wie lange eine Prozessinstanz nach Abschluss des Prozesses im System behalten wird. Du musst einen Wert zwischen 0 und 365 Tagen im Format ISO-8601 angeben. Wenn du 0 Tage konfigurierst, wird die Prozessinstanz zum nächst möglichen Zeitpunkt gelöscht.

Rückgabewerte der Abfrage

  • 200: Das Deployment wurde erfolgreich aktiviert.
  • 400: Das Deployment ist ungültig. Der Wert wird auch zurückgegeben, wenn die Kombination der übergebenen Konfigurationen unlogisch ist.
  • 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.

Löschen des Deployments

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 erfolgreich 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 der Identityprovider-App 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 Verlaufsdaten 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"
        }
    }
}

Hinweise zum Inhalt

Im Inhalt kannst du die Daten des Deployments mitgeben, das erstellt werden soll.

  • source: Die Quelle, aus der 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: Die Anfrage ist ungültig. Beachte den Hinweis zum Inhalt.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, ein Deployment zu erzeugen.

Im Erfolgsfall wird der HTTP-Statuscode 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. Mit 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.

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 der Grund 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 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.

 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 Inhalt

Der Inhalt muss gültiges BPMN mit einer maximalen Größe von 1MB enthalten.

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. Beim Aktivieren 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",
    "correlationKey" : "myCorrelationKey",
    "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 Inhalt

  • businessKey: Business-Key für die Prozessinstanz. Ein Business-Key ist ein frei festzulegender externer Schlüssel, mit dem die Prozessinstanz identifiziert werden kann. Der Business-Key spielt zur Laufzeit keine Rolle (optional, max. 255 Zeichen).
  • correlationKey: Der Correlation Key stellt sicher, dass zu diesem eindeutigen Schlüssel nur eine Prozessinstanz gestartet wird. Ist schon eine Prozessinstanz mit dem übergebenen Schlüssel vorhanden, wird keine neue Prozessinstanz gestartet und trotzdem der Code 201 übermittelt. Die Prozessinstanz, die gestartet werden soll, muss inhaltlich identisch zu einer bereits existierenden Prozessinstanz mit demselben Correlation Key sein (optional, max. 255 Zeichen).
  • variables: Initiale Prozessvariablen (optional). Weitere Informationen zum Format findest du im Abschnitt 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. Der Aufruf ist identisch zum Vorgang unter Starten von Prozessen.

Rückgabewerte der Abfrage

  • 201: Das Deployment wurde erfolglreich aktiviert und der Prozess gestartet. Der URI der Prozessinstanz ist im Location-Header enthalten.
  • 400: Das Deployment oder die Prozessvariablen sind ungültig. Möglicherweise wurde der Correlation Key bereits für einen anderen, nicht identischen Prozessstart verwendet.
  • 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 erfolgreich gelöscht.
  • 401: Der Benutzer ist nicht authentifiziert.
  • 403: Der Benutzer ist nicht berechtigt, ein 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 Authentifizierung notwendig.

Verwende folgende Anfrage zum Starten eines Prozesses:

Request


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

{
    "businessKey" : "myBusinessKey",
    "correlationKey" : "myCorrelationKey"
    "variables" : {
        "variable_1" : "value"
    },
    "_links" : {
        "endCallback" : {
            "href" : "/myapp/endCallback"
        },
        "incidentCallback" : {
            "href" : "/myapp/incidentCallback"
        }
    }
}

Wenn für diesen Prozess das Starten ohne Authentifizierung konfiguriert ist, kannst du stattdessen diese HTTP-Schnittstelle verwenden:


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

{
    "businessKey" : "myBusinessKey",
    "correlationKey" : "myCorrelationKey"
    "variables" : {
        "variable_1" : "value"
    }
}

Beim Starten ohne Authentifizierung enthält die Antwort keinen Location-Header.

Die Parameter endCallback und incidentCallback sind bei Prozessstart ohne Authentifizierung nicht erlaubt.

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

Hinweise zum Inhalt

  • businessKey: Business-Key für die Prozessinstanz. Ein Business-Key ist ein frei festzulegender externer Schlüssel, mit dem die Prozessinstanz in der Prozessüberwachung identifiziert werden kann (optional, max. 255 Zeichen).
  • correlationKey: Der Correlation Key stellt sicher, dass zu diesem eindeutigen Schlüssel nur eine Prozessinstanz gestartet wird. Ist schon eine Prozessinstanz mit dem übergebenen Schlüssel vorhanden, wird keine neue Prozessinstanz gestartet und trotzdem der Code 201 übermittelt. Die Prozessinstanz, die gestartet werden soll, muss inhaltlich identisch zu einer bereits existierenden Prozessinstanz mit demselben Correlation Key sein (optional, max. 255 Zeichen).
  • variables: Initiale Prozessvariablen (optional). Weitere Informationen zu gültigen Variablen findest du im Abschnitt 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 die Zieladresse hinter der Basisadresse, erfolgt der Aufruf authentifiziert. Die Process-App verwendet hierfür den App-User "process@app.idp.d-velop.local". 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. Weitere Informationen zum Format findest du im Abschnitt Grundlegendes zu Prozessvariablen.
  • links: Verknüpfungen. Die Linkrelation instance zeigt auf die dazugehörige Prozessinstanz (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.

Der URI incidentCallback wird jedes Mal innerhalb der Prozessinstanz mit der HTTP POST-Anforderung aufgerufen, wenn ein Fehler auftritt, der im Monitoring sichtbar ist. Liegt die Zieladresse hinter der Basisadresse, erfolgt der Aufruf authentifiziert.

Die Process-App verwendet hierfür den App-User "process@app.idp.d-velop.local". Die Daten werden in folgendem Format übermittelt:

Request


POST /myapp/incidentCallback
Content-Type: application/json

{
    "process" : "myProcess",
    "event" : "INCIDENT",
    "timestamp" : "2018-07-24T08:53:55.622+02:00",
    "reason" : "The reason for the incident",
    "_links": {
        "instance": {
            "href": "/process/instances/myInstance"
        }
    }
}

Bedeutung der Felder

  • process: Der Bezeichner des Prozesses.
  • event: Das Ereignis. Enthält den Wert INCIDENT.
  • timestamp: Zeitpunkt des Ereignisses (RFC3339 formatiert).
  • reason: Der Grund für den Fehler.
  • links: Verknüpfungen. Die Linkrelation instance zeigt auf die dazugehörige Prozessinstanz (bei Einmalprozessen nicht vorhanden).

Rückgabewerte der Abfrage

  • 201: Der Prozess wurde für den Start eingeplant. Der URI der Prozessinstanz ist im Location-Header enthalten.
  • 400: Die Anfrage ist ungültig. Möglicherweise wurde der Correlation Key bereits für einen anderen, nicht identischen Prozessstart verwendet.
  • 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, Einmalprozesse per API zu starten.
  • 429: Es sind zu viele gleichzeitige Anfragen eingegangen (insbesondere bei anonymem Prozessstart). Versuche es in diesem Fall später nochmal.

 Abbrechen von Prozessinstanzen

Mit dieser HTTP-Schnittstelle kannst du eine Prozessinstanz abbrechen. Für die Nutzung dieser Schnittstelle ist eine Authentifizierung notwendig. Die Authentifizierung muss mit einem Benutzer in der Rolle Prozessadministrator durchgeführt werden.

Verwende folgende Anfrage zum Abbruch eines Prozesses:

Request


POST {Location der Instanz}/cancel
Content-Type: application/json

{
    "cancelReason" : "The process instance is not needed anymore"
}

Die Location der Prozessinstanz hast du beim Starten bereits im Location-Header erhalten.

Hinweise zum Inhalt

  • cancelReason: Der Grund für den Abbruch der Prozessinstanz (max. 280 Zeichen).

Rückgabewerte der Abfrage

  • 200: Die Prozessinstanz wurde abgebrochen.
  • 400: Die Anfrage ist ungültig. Möglicherweise hast du einen leeren oder zu langen Grund angegeben.
  • 401: Der Benutzer ist nicht angemeldet.
  • 403: Der Benutzer hat nicht das Recht, Prozessinstanzen abzubrechen.
  • 404: Es existiert keine Prozessinstanz mit dieser ID.
  • 409: Die Anfrage zum Abbrechen wurde zu einem Zeitpunkt gestellt, zu dem ein Abbrechen nicht möglich ist. Ein Abbrechen ist z.B. während des Startvorgangs oder des Abschlussvorgangs der Prozessinstanz nicht möglich. Die Anfrage kannst du zu einem späteren Zeitpunkt wiederholen.
  • 410: Die Anfrage zum Abbrechen wurde zu einem Zeitpunkt gestellt, zu dem die Prozessinstanz bereits beendet war. In diesem Fall musst du die Anfrage nicht wiederholen.

 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 einen Send Task, wird der Endpunkt des darin angegebenen 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" },
        "bpmnerror" : { "href" : "/process/custom/response/1232354/bpmnerror" }
    }
}

Bedeutung der Felder

  • 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).

Der Prozess wartet maximal fünf Sekunden auf eine Antwort. Wenn der Dienst eine Antwort in diesem Zeitfenster nicht sicherstellen kann, sollte der Dienst grundsätzlich das Konzept der asynchronen Antwort implementieren.

Synchrone Antwort

Ein synchroner Dienst kann die Anfrage auf drei Arten beantworten:

  • Erfolgsfall
  • BPMN-Fehler
  • Technischer Fehler

Antwort im Erfolgsfall

Um der Process-App mitzuteilen, dass die Anfrage erfolgreich bearbeitet worden ist, kann der Dienst die Anfrage mit dem Statuscode 200 und dem folgenden 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.

Antwort bei einem BPMN-Fehler

Wenn der externe Dienst einen BPMN-Fehler an die Process-App übermitteln soll, kann der Dienst den Statuscode 200 mit dem folgenden Body zurückgeben:

Response


Content-Type: application/json

{
    "bpmnError": "4711",
    "bpmnErrorMessage": "Some optional message to explain the bpmn error"
}

Antwort bei einem technischen Fehler

Tritt bei der Bearbeitung der Anfrage ein technischer Fehler auf, kann der externe Dienst einen der folgenden HTTP-Statuscodes zurückgeben:

  • 400: Die Anfrage ist ungültig und konnte vom externen Dienst nicht verarbeitet werden. Die Process-App wird daraufhin keine weiteren Versuche ausführen. Verwende diesen Statuscode, wenn bereits beim Validieren der Eingabeparameter ein Fehler auftritt.
  • 401: Die Authentifizierung ist ungültig. Die Process-App wird daraufhin keine weiteren Versuche ausführen.
  • 403: Die Process-App ist nicht autorisiert, den Dienst aufzurufen. Die Process-App wird daraufhin keine weiteren Versuche ausführen.
  • 404: Der Dienst ist nicht erreichbar. Die Process-App wird zu einem späteren Zeitpunkt einen erneuten Versuch ausführen.
  • 405: Der Dienst unterstützt die Methode nicht. Die Process-App wird daraufhin keine weiteren Versuche ausführen.
  • 406: Der Dienst kann den entsprechenden Medientyp nicht liefern. Die Process-App wird daraufhin keine weiteren Versuche ausführen.
  • 415: Der Dienst kann den Medientyp nicht verarbeiten. Die Process-App wird daraufhin keine weiteren Versuche ausführen.
  • 500: Es ist ein interner Fehler bei der Verarbeitung der Anfrage aufgetreten. Die Process-App wird zu einem späteren Zeitpunkt einen erneuten Versuch ausführen. Verwende diesen Statuscode, wenn während der Verarbeitung ein Fehler auftritt.

Im Body kann optional eine Fehlernachricht übertragen werden:

Response


Content-Type: application/json

{
"error" : "Error reason"
}

Asynchrone Antwort

Ein asynchroner Dienst bestätigt zunächst nur das Entgegennehmen der Anfrage, ohne die Anfrage direkt zu verarbeiten. Zum Bestätigen kann der Dienst im Erfolgsfall den Statuscode 200 oder 202 ohne Body zurückgeben. Wenn die Anfrage bereits nicht entgegengenommen werden kann, kann der Dienst einen der folgenden Statuscodes zurückgeben:

  • 400: Die Anfrage ist ungültig und konnte vom externen Dienst nicht verarbeitet werden. Die Process-App wird daraufhin keine weiteren Versuche ausführen. Verwende diesen Statuscode, wenn bereits beim Validieren der Eingabeparameter ein Fehler auftritt.
  • 401: Die Authentifizierung ist ungültig. Die Process-App wird daraufhin keine weiteren Versuche ausführen.
  • 403: Die Process-App ist nicht autorisiert, den Dienst aufzurufen. Die Process-App wird daraufhin keine weiteren Versuche ausführen.
  • 404: Der Dienst ist nicht erreichbar. Die Process-App wird zu einem späteren Zeitpunkt einen erneuten Versuch ausführen.
  • 405: Der Dienst unterstützt die Methode nicht. Die Process-App wird daraufhin keine weiteren Versuche ausführen.
  • 406: Der Dienst kann den entsprechenden Medientyp nicht liefern. Die Process-App wird daraufhin keine weiteren Versuche ausführen.
  • 415: Der Dienst kann den Medientyp nicht verarbeiten. Die Process-App wird daraufhin keine weiteren Versuche ausführen.
  • 500: Es ist ein interner Fehler bei der Verarbeitung der Anfrage aufgetreten. Die Process-App wird zu einem späteren Zeitpunkt einen erneuten Versuch ausführen. Verwende diesen Statuscode, wenn während der Verarbeitung ein Fehler auftritt.

Im Body kann optional eine Fehlernachricht übertragen werden:

Response


Content-Type: application/json

{
"error" : "Error reason"
}

Wenn die Anfrage erfolgreich entgegengenommen wurde, kann der Dienst zu einem späteren Zeitpunkt eine der Verknüpfungen success, bpmnerror oder fail mit der HTTP-Anforderung POST aufrufen, um Erfolg, einen BPMN-Fehler oder einen technischen Fehler zu melden. Eine Authentifizierung von der Identityprovider-App ist hierfür nicht erforderlich. Der Body der asynchronen Antwort entspricht je nach Antwortart dem Body der entsprechenden synchronen Antwort.

Die Process-App gibt einen der folgenden Statuscodes zurück:

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

Für einen BPMN-Fehler kann im Prozessmodell ein spezieller Pfad modelliert werden. Im Falle eines technischen Fehlers 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 die Variablen 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"],
    "variable_3" : {
      "myKey" : "myValue"
    }
}

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

DateitypÜbertragung alsBeispiel
StringJSON-String"Hello"
NumberJSON Number47.11
BooleanJSON booleantrue
IdentityJSON-String in diesem Format:
identity://{uri}
"identity:///identityprovider/scim/users/johnsmith"
DmsObjectJSON-String in diesem Format:
dmsObject://{uri}
"dmsObject:///dms/r/123/o2/xyz"
URLJSON-String in einem gültigen URL-Format entsprechend RFC 2396:"https://www.d-velop.de"
ObjectJSON-Objekt{"myKey" : "myValue"}

Entfernen einer Variable

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


{
"variable_1" : null
}

Mehrfachwerte

Mehrfachwerte werden als JSON-Arrays dargestellt. Diese Arrays müssen mindestens einen Wert des dazugehörigen Datentyps enthalten. Nullwerte sind nur zulässig, wenn das Array mindestens einen gültigen Wert enthält. 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.
  • Variablenwerte sind zu lang. Eine Variable vom Typ String darf nicht länger als 500 Zeichen sein. Bei Mehrfachwerten gilt diese Beschränkung für jeden Einzelwert.

 Zugreifen auf Prozessvariablen in einer Benutzeraktivität

Mit dieser 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" eines Bearbeitungsdialogs ermittelt werden. Nähere Informationen dazu findest du in der Dokumentation 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 Authentifizierung an der Identityprovider-App notwendig.

Verwende folgende Anforderung für den Zugriff auf Prozessvariablen:

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.

Hinweis

Nur der Benuzter, der die Benutzeraktivität aktuell geöffnet hat, darf die Variablen abfragen.

Rückgabewerte der Abfrage

  • 200: Variablen wurden erfolgreich zurückgegeben.
  • 400: Die Antwort ist ungültig.
  • 401: Es wurde keine gültige Authentifizierung übergeben.
  • 403: Der Benutzer hat nicht das Recht, die Variablen abzufragen.
  • 404: Die angegebene Aufgabe existiert nicht.
  • 409: Die angegebene Aufgabe wurde noch nicht erfolgreich an den Benutzer (Task-App) zugestellt oder der Prozess wurde aufgrund eines Fehlers unterbrochen.

Ä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"],
        "variable_5": {
            "myKey" : "myValue"
        },
        "dv_decision" : "Granted",
        "dv_comment" : "I approve"
    }
}

Hinweis

Nur der Benutzer, der die Benutzeraktivität aktuell geöffnet hat, darf die Variablen ändern.

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.
  • 409: Der Prozess ist gerade in einem Status, in dem Variablen nicht geändert werden können. Möglicherweise wurde der Prozess aufgrund eines Fehlers unterbrochen.

 Auslösen eines Prozessereignisses

Mit dieser Funktion kannst du ein Prozessereignis auslösen. Den URI kannst du in der Prozessadministration ermitteln.

Request


POST Endpunkt-URI
Content-Type: application/json
Content-Length: XXX

{ 
  ...
}

Der Endpunkt kann beliebiges JSON entgegennehmen. Durch die Zuordnung in der Endpunktkonfiguration bestimmst du, welche Eigenschaften im Prozessereignis verwendet werden.

Der Content-Length-Header muss in jedem Fall übermittelt werden. Der Content darf eine Größe von 100 KB nicht übersteigen.

Rückgabewerte der Abfrage

  • 202: Das Ereignis wurde entgegengenommen.
  • 204: Das Ereignis wurde noch nicht vollständig konfiguriert.
  • 400: Die Anfrage ist ungültig.
  • 401: Es wurde keine gültige Authentifizierung übergeben.
  • 404: Der Endpunkt existiert nicht.
  • 415: Der Content-Type wird nicht unterstützt.