DigiWF Cosys Integration

Die Cosys-Integration ermöglicht die asynchrone Erstellung von Dokumenten in Cosys (opens new window) mit anschließender Speicherung in einem S3-Speicher. Mit dieser Integration können Dokumente erstellt und in einem S3-kompatiblen Speicher abgelegt werden. Diese Dokumente können anschließend beispielsweise in einer E-Mail versendet werden.

Verwendung

Durch die Cosys-Integration wird die Erstellung von Dokumenten ermöglicht, die anschließend in einem S3-Speicher abgelegt werden. Zusätzlich kann direkt im Prozess auf untenstehende Fehler reagiert werden.

Dokument erstellen

Zur asynchronen Erstellung eines Dokuments in Cosys erzeugen Sie zuerst ein GenerateDocument-Objekt und setzen den TYPE-Header auf createCosysDocument. Im Anschluss senden Sie das Objekt an das entsprechende Kafka-Topic. Den Namen des Topics finden Sie in der Konfiguration der Cosys-Integration unter spring.cloud.stream.bindings.functionRouter-in-0.destination.

Standardmäßig heißen die Topics dwf-cosys-${DIGIWF_ENV}, wobei DIGIWF_ENV die aktuelle Umgebung ist.

Nachfolgend ist ein Beispiel für ein GenerateDocument-Objekt aufgeführt:

{
  "client": "",
  "role": "",
  "guid": "",
  "variables": {},
  "documentStorageUrls": [
    {
      "url": "",
      "path": "",
      "action": ""
    }
  ]
}

Die Cosys-Integration erzeugt ein Dokument mit den angegebenen Variablen und speichert dieses in einem S3-Speicher. Dafür muss vorab eine presigned URL für das Dokument erstellt werden. Diese wird in der Variable documentStorageUrls übergeben.

In der Variable documentStorageUrls wird lediglich eine einzige presigned URL akzeptiert und es können die Aktionen POST oder PUT verwendet werden. Die Aktion POST wird für die Erstellung neuer Dateien im S3-Speicher verwendet und die Aktion PUT, um ein bereits vorhandenes Dokument zu überschreiben.

Verwendung in BPMN-Prozessen

Verwenden Sie eines unserer Element-Templates in einer Call Activity, um die Prozessentwicklung zu beschleunigen, und befüllen Sie es mit den gewünschten Informationen. Eine Liste der Element-Templates finden Sie unter Element Templates.

Zur Erstellung von presigned URLs können Sie das Element-Template s3_create_presigned_url (siehe Element Template) in einer Call Activity verwenden und das Ergebnis an die Cosys-Integration übergeben.

In der folgenden Grafik wird ein Beispiel für einen BPMN-Prozess dargestellt. Wie oben beschrieben, wird zuerst eine presigned URL erstellt, bevor ein Dokument erstellt wird.

Fehlerbehandlung

Bei der Fehlerbehandlung wird zwischen BPMN-Errors und Incident-Errors unterschieden. BPMN-Errors können im Prozess behandelt werden, während Incident-Errors nicht im Prozess behandelt werden können und einen Incident erzeugen.

Nachfolgend sind die BPMN-Errors aufgeführt, die von der Cosys-Integration geworfen werden können:

BPMN Error

Error Code	Error Message	Beschreibung	Handlungsempfehlung
VALIDATION_ERROR	Fehlermeldung der auftretenden ValidationException	Die übergebenen Daten sind nicht valide.	Korrigieren Sie die Daten und versuchen es erneut
S3_FILE_SAVE_ERROR	Document could not be saved.	Die in Cosys erzeugte Datei kann nicht im S3 Storage gespeichert werden. Die übergebene presigned URL ist fehlerhaft (nicht valide, abgelaufen, falsche Action).	Überprüfen Sie, ob die Daten valide sind und versuchen es erneut.
S3_FILE_SIZE_ERROR	The following files exceed the maximum size of <maximal Größe von Dateien> MB:<Liste von Dateien mit Größen>	Einige Dateien haben die maximal zulässige Größe überschritten	Stellen Sie sicher, dass nur Dateien mit der zulässigen Maximalgröße in den S3 Bucket geladen werden.
COSYS_DOCUMENT_CREATION_FAILED	Document could not be created.	Das Dokument konnte nicht erstellt werden. Es kann sein, dass ein technischer Fehler aufgetreten ist.	Analysieren Sie die Fehlermeldung und versuchen es erneut.

Konfiguration

Allgemeine Konfigurationen für DigiWF-Integrationen sind unter Eigene Integration erstellen beschrieben.

Die Konfiguration der CoSys Integration ist in der README.md (opens new window) beschrieben.