Die Aktivität Webdienst bindet einen Webdienst in einen Workflow ein und ermöglicht so den Datenaustausch zwischen dem Workflow und anderen Systemen.
So können Sie beispielsweise einen Webdienst in einem Workflow nutzen, um Informationen in Drittanwendungen zu erstellen, zu aktualisieren oder zu löschen. Der Webdienst kann auch Daten aus Geschäftsanwendungen wie CRM- oder Buchhaltungssystemen abrufen und für einen DocuWare Workflow bereitstellen. DocuWare Workflows unterstützen die Einbindung von REST- und SOAP-Webdiensten.
Hinweis: Fügen Sie zuerst einen Webdienst hinzu
Fügen Sie den Webdienst zunächst zu Ihrer DocuWare Organisation hinzu. Bevor Sie einen Webdienst in einen Workflow einbinden können, müssen Sie unter DocuWare Konfigurationen > Web Services eine Verbindung zu diesem Webdienst anlegen.
Hier finden Sie eine allgemeine Übersicht zur Konfiguration:
Um einen Webdienst zum Workflow hinzuzufügen, navigieren Sie zu DocuWare Konfigurationen > Zusammenarbeit > Workflow Designer.
Klicken Sie auf die Schaltfläche Neuer Workflow oder Bearbeiten, um einen neuen oder bestehenden Workflow auf der Arbeitsfläche zu öffnen.
Klicken Sie in der linken Seitenleiste auf Webdienst.
Wählen Sie Ihre Methode: REST oder SOAP. Die Einrichtung von REST- und SOAP-Webdiensten wird im Folgenden ausführlich beschrieben.
Sie haben außerdem die Möglichkeit, bedingte Ausgänge für eine Webdienst-Aktion zu erstellen.
Nach Abschluss der Konfiguration müssen Sie die Webdienst-Aktivität mit weiteren Workflow-Aktivitäten verbinden.
.png)
Der Dialog der Webdienst-Aktivität im webbasierten Workflow Designer
REST-Webdienst
Den Datenaustausch über einen RESTful-Webdienst konfigurieren Sie in einem Assistenten mit drei Registerkarten: Allgemein, Datenzuweisung und Statuscodes.
Allgemein: Webdienst auswählen
Adresse
Damit Sie einen REST-Webdienst in einem Workflow verwenden können, muss er unter DocuWare Konfigurationen > Web Services registriert sein. Nur registrierte Dienste erscheinen in diesem Bereich.
Alle REST-Webdienste, die in Ihrer DocuWare Organisation installiert sind und für die Sie berechtigt sind, werden im Bereich Allgemein > Adresse aufgelistet.
Definierter Webdienst: Wählen Sie den REST-Webdienst aus, der aufgerufen werden soll.
Webdienst-URL: Die URL des REST-Webdienstes für den ausgewählten Dienst. Dieses Feld wird auf Grundlage der Auswahl unter Definierter Webdienst automatisch ausgefüllt und ist schreibgeschützt.
Um die URL zu ändern, aktualisieren Sie die Webdienst-Registrierung unter DocuWare Konfigurationen > Web Services.Format: Geben Sie das Format für den Datenaustausch an (JSON oder XML). Die Datenzuweisung unterscheidet sich je nach gewähltem Format.
Endpunkt
Ein Endpunkt ist eine bestimmte URL des Webservers, an die die Anfrage gesendet wird. Der Endpunkt empfängt die Daten und legt fest, welche Aktion ausgeführt wird.
Der Standard-Endpunkt ist das Stammverzeichnis bzw. die Basis-URL (/). Dies ist der erste Einstiegspunkt zum Webdienst.
Wenn der Webdienst eine OpenAPI-Spezifikationsdatei (*.json, .txt, .yml oder *.yaml) bereitstellt, können Sie diese über die Importschaltfläche importieren. Nach dem Import werden alle verfügbaren Endpunkte in der Dropdown-Liste angezeigt.
Information: Standard-DocuWare Platform API
Wenn Sie Endpunkte aus einer OpenAPI-Spezifikation, der Standard-DocuWare Platform API oder DocuWare E-Rechnungen verwenden, werden alle erforderlichen Routen und Parameter auf Grundlage des gewählten Endpunkts automatisch voreingestellt. Das vereinfacht die Konfiguration der HTTP-Anfrage des Webdienstes.
Parameterkonfiguration: HTTP-Anfrage definieren
Klicken Sie auf die URL, die hinter dem ausgewählten Endpunkt angezeigt wird, um den Assistenten Parameterkonfiguration zu öffnen. Hier geben Sie die Informationen und Eigenschaften an, die zum Ausführen der HTTP-Anfrage benötigt werden, z. B. Routen, Abfrageparameter oder den Header und den Body der Anfrage. Diese Angaben sind erforderlich, damit dem Webdienst alle notwendigen Daten zur Verfügung stehen.
.png)
Anfrage
In diesem Bereich konfigurieren Sie die Anfrage, die an den Endpunkt gesendet wird. Welche Konfigurationsoptionen verfügbar sind, hängt vom ausgewählten Webdienst und Endpunkt ab. Oben wird eine Vorschau der Anfrage (URL) angezeigt.
Methode: Die HTTP-Methode legt fest, was mit dem Endpunkt geschehen soll. DocuWare unterstützt GET, POST, PUT und DELETE.
Wenn Sie eine OpenAPI-Spezifikationsdatei, die Standard-DocuWare Platform API oder DocuWare E-Rechnungen verwenden, wird die HTTP-Methode auf Grundlage des gewählten Endpunkts automatisch voreingestellt.
Routen: Mit Routen sprechen Sie einzelne Ressourcen am Endpunkt gezielt an.
Wenn Sie eine OpenAPI-Spezifikationsdatei, die Standard-DocuWare Platform API oder DocuWare E-Rechnungen verwenden, wird die Route auf Grundlage des gewählten Endpunkts automatisch voreingestellt.
Sie können feste Werte, Werte aus Indexdaten sowie globale oder Systemvariablen übergeben.Abfrageparameter: Hier geben Sie Schlüssel-Wert-Paare ein, um dem Webdienst genau mitzuteilen, was abgefragt werden soll. Abfrageparameter sind häufig optional und werden bei Endpunkten verwendet, die die GET-Methode nutzen, um ein Ergebnis zu filtern oder einzugrenzen.
Wenn Sie eine OpenAPI-Spezifikationsdatei, die Standard-DocuWare Platform API oder DocuWare E-Rechnungen verwenden, werden die Abfrageparameter auf Grundlage des gewählten Endpunkts automatisch voreingestellt.
Sie können feste Werte, Werte aus Indexdaten sowie globale oder Systemvariablen übergeben.Dokumentanhang: Legen Sie fest, ob das aktuell im Workflow befindliche Dokument an die Anfrage angehängt werden soll. Das Dokument kann im Originalformat oder als PDF angehängt werden. Enthält das DocuWare Dokument mehrere Dateien (geklammert), werden alle Dateien exportiert und separat angehängt. Die HTTP-Anfrage enthält dann mehrere Datei-Objekte.
So können Sie beispielsweise ein Dokument wie eine Rechnung an einen externen Dienst senden.Kodierung: Geben Sie die Kodierung für die Werte an, die in Routen und Abfragen übergeben werden. Je nach den Werten in Ihrer Anfrage müssen die Zeichen in der URL gegebenenfalls kodiert werden. Für die Kodierung stehen drei Optionen zur Verfügung:
Sonderzeichen kodieren (empfohlen): Alle Sonderzeichen werden kodiert. Aus „AT&T" wird zum Beispiel „AT%26T" und aus „Rapid Transport" wird „Rapid%20Transport".
Sonderzeichen kodieren (außer reservierte URL-Zeichen): (*&^%$#@!:
Alle Sonderzeichen außer den reservierten URL-Zeichen werden kodiert. „AT&T" bleibt also unverändert, aus „Rapid Transport" wird „Rapid%20Transport".
Sonderzeichen nicht kodieren: Weder Sonderzeichen noch Leerzeichen werden kodiert.
Die Kodierung wird auf alle Werte angewendet, die in Routen und Abfrageparametern angegeben sind.
HTTP-Header
Die Header stehen am Anfang der Anfrage, direkt nach der Statuszeile der Anfrage. HTTP-Header sind Schlüssel-Wert-Paare, die Metadaten zur Anfrage liefern: zum Beispiel zum Absender, zum gesendeten Datenformat, zur Authentifizierung oder dazu, wie die Antwort des Webdienstes aussehen soll – im Rahmen der vom Webdienst selbst gesetzten Möglichkeiten.
HTTP-Body
Der HTTP-Body ist der Teil der Anfrage, in dem Sie Daten senden (z. B. mit POST oder PUT).
Geben Sie die Informationen und Eigenschaften an, die zum Ausführen des ausgewählten Vorgangs erforderlich sind, beispielsweise die GUID des anzubringenden Stempels. Oder, falls Sie einen neuen Benutzer anlegen, enthält der HTTP-Body die Benutzerdaten im JSON-Format. Die Validierung des HTTP-Bodys erfolgt entweder beim Senden oder automatisch beim Speichern der Konfiguration. Wird ein Teil des Inhalts als ungültig erkannt, wird der entsprechende Fehler hervorgehoben und eine passende Meldung angezeigt. Die Konfiguration kann auch bei Validierungsproblemen gespeichert werden.
Strukturieren Sie den Inhalt des HTTP-Bodys mit festen Werten, Indexdaten oder globalen und Systemvariablen. Beachten Sie, dass Sie die Konfiguration auch bei Validierungsproblemen speichern können.
Test
Testen Sie die Anfrage über die Schaltfläche Anfrage senden und prüfen Sie die „Antwort", um den Erfolg des Vorgangs zu verifizieren. Beachten Sie, dass Sie für jede Variable einen Testwert angeben müssen, um den Test ausführen zu können. Sie können hier auch ein Testdokument angeben, das in die Test-Anfrage an den Webdienst aufgenommen wird.
Datenzuweisung: Anfragedaten im Workflow verwenden
Die aus der Antwort des Webdienstes zurückgegebenen Informationen können im Workflow weiterverwendet werden. Unter Datenzuweisung legen Sie fest, wo diese Daten im Workflow gespeichert werden. Die Struktur der Antwort wird vom Webdienst vorgegeben, nicht vom DocuWare Workflow. Im Workflow Designer entscheiden Sie lediglich, ob und welche Teile der Antwort verwendet werden.
Weisen Sie Werte aus der Antwort entweder globalen Variablen oder Indexdaten zu. Wählen Sie die benötigten Werte direkt aus der JSON- oder XML-Struktur der Antwort aus.
Beispiel: Der Webdienst ruft die Details eines Unternehmens aus dem CRM oder weiterführende Informationen zu einem Auftrag aus dem ERP-System ab.
Wenn Sie alle zurückgegebenen Einträge verarbeiten möchten, ersetzen Sie den Index im Array-Indexer manuell durch ein Sternchen (*). So lassen sich alle Einträge des Arrays vollständig verarbeiten.
Statuscodes
REST-Webdienste geben nach ihrer Ausführung einen sogenannten HTTP-Statuscode zurück. Dieser Code zeigt an, ob die Anfrage erfolgreich war oder ob ein Fehler aufgetreten ist.
Typische Statuscodes sind zum Beispiel:
200 = OK (alles in Ordnung)
201 = Created (etwas wurde erstellt)
400 = Bad Request (Fehler in den gesendeten Daten)
404 = Not found (Ressource nicht gefunden)
500 = Serverfehler
Wenn Sie die Funktion Zurückgegebenen Code einer Workflow-Variablen zuweisen aktivieren, wird der zurückgegebene Statuscode in einer globalen Workflow-Variablen gespeichert.
Der in der Variablen gespeicherte Code lässt sich anschließend im Workflow auswerten, z. B. für die Fehlerbehandlung oder die Protokollierung.
Fehlerbehandlung
Wechseln Sie zur Registerkarte Fehler, um festzulegen, wie der Workflow weiterlaufen soll, falls der Aufruf des Webdienstes fehlschlägt. Ist beispielsweise der externe Webdienst nicht verfügbar, können Sie den Workflow so konfigurieren, dass das Dokument an eine andere automatisierte Aktion weitergeleitet wird, etwa an eine E-Mail-Benachrichtigung mit der Aufforderung, die fehlenden Informationen manuell einzugeben.
Wählen Sie eine der folgenden Optionen:
Keine Fehlerbehandlung: Diese Option ist standardmäßig aktiviert.
Workflow neu starten: Das Dokument wird automatisch erneut von Anfang an durch die Workflow-Schritte geleitet.
Workflow beenden: Das Dokument wird automatisch ans Ende des Workflows weitergeleitet. Alle bis zu diesem Zeitpunkt vorgenommenen Änderungen bleiben erhalten.
Zu Schritt wechseln: Diese Option fügt der Aktivität Daten zuweisen einen Ausgang Fehler hinzu. Verbinden Sie ihn mit einer anderen Aktivität, um das Dokument im Workflow manuell weiterzuleiten.
SOAP-Webdienst
SOAP (Simple Object Access Protocol) ist ein standardisiertes Messaging-Protokoll, das XML für den Datenaustausch verwendet. Im Gegensatz zu REST, wo Sie HTTP-Methoden, Header, Routen und einen Anfrage-Body manuell konfigurieren, werden SOAP-Webdienste über eine WSDL-Datei (Web Services Description Language) beschrieben. Die WSDL definiert die verfügbaren Vorgänge, deren Parameter und das Datenformat. Der Workflow Designer ruft diese Informationen daher automatisch ab und stellt sie als auswählbare Optionen bereit.
Nachdem Sie auf der Registerkarte Methode die Option SOAP-Webdienst gewählt haben, klicken Sie auf Webdienst festlegen, um das Konfigurationsfeld zu öffnen:
Adresse: Webdienst auswählen
Damit Sie einen SOAP-Webdienst in einem Workflow verwenden können, muss er unter DocuWare Konfigurationen > Web Services registriert sein. Nur registrierte Dienste erscheinen in diesem Bereich.
Alle SOAP-Webdienste, die in Ihrer DocuWare Organisation installiert sind und für die Sie berechtigt sind, werden im Bereich Allgemein > Adresse aufgelistet.
Definierter Webdienst: Wählen Sie den SOAP-Webdienst aus, der aufgerufen werden soll. Jeder registrierte Dienst verweist auf einen bestimmten WSDL-Endpunkt, der die vom Dienst bereitgestellten Vorgänge und Datenstrukturen beschreibt.
Webdienst-URL: Die URL des WSDL-Endpunkts für den ausgewählten Dienst. Dieses Feld wird auf Grundlage der Auswahl unter Definierter Webdienst automatisch ausgefüllt und ist schreibgeschützt.
Um die URL zu ändern, aktualisieren Sie die Webdienst-Registrierung unter DocuWare Konfigurationen > Web Services.
Methode: Vorgang auswählen
Die Dropdown-Liste Methode zeigt alle Vorgänge, die der ausgewählte SOAP-Webdienst bereitstellt. Diese Vorgänge werden automatisch aus der WSDL-Definition des Dienstes abgerufen.
Wählen Sie den Vorgang aus, den der Workflow ausführen soll. Im Beispiel ist die Methode „DeleteUnsignedDocument" ausgewählt – ein Vorgang des Signaturdienstes, der ein nicht signiertes Dokument entfernt. Sobald Sie eine Methode auswählen, wird der Bereich Parameter darunter automatisch aktualisiert und zeigt die für diesen Vorgang erforderlichen Eingabeparameter an.
Parameter: HTTP-Anfrage definieren
Der Bereich Parameter zeigt die für die ausgewählte Methode erforderlichen Eingabedaten an. Diese Parameter sind in der WSDL definiert und werden automatisch angezeigt – Sie müssen sie nicht manuell hinzufügen oder entfernen. Jeder Parameter hat einen Namen, einen Datentyp und Felder zur Konfiguration:
Quelltyp: Legt fest, woher der Wert stammt. Folgende Quellen stehen zur Verfügung:
Dokumentindex: Ein Indexfeldwert des Dokuments, das sich aktuell im Workflow befindet.
Fester Wert: Ein statischer Wert, den Sie direkt eingeben.
Globale Variable: Eine Workflow-Variable, die während der Workflow-Ausführung gesetzt und geändert werden kann.
Systemvariable: Ein von DocuWare bereitgestellter vordefinierter Wert, etwa die Archiv-GUID oder die Dokument-ID.
Wert: Das konkrete Feld, die Variable oder der feste Wert, der übergeben werden soll. Welche Werte in der Dropdown-Liste verfügbar sind, hängt vom gewählten Quelltyp ab.
Im Screenshot oben erfordert die Methode „DeleteUnsignedDocument" drei Parameter:
DocId: zugeordnet zur Dokument-ID aus dem Dokumentindex)
FileCabinetId: zugeordnet zur Systemvariablen Archiv-GUID,
Token: zugeordnet zu einer globalen Variablen.
Datenzuweisung: Antwortdaten im Workflow verwenden
Nach der Ausführung gibt der SOAP-Webdienst eine Antwort mit Ergebnisdaten zurück. Im Bereich Datenzuweisung stellen Sie diese Daten dem Workflow zur Verfügung, indem Sie Antwortfelder globalen Variablen zuordnen.
Die Struktur der Antwort wird vom SOAP-Webdienst selbst vorgegeben und automatisch als zusammenklappbare Baumstruktur angezeigt. Jedes Feld zeigt seinen Namen und Datentyp an. Sie konfigurieren die Struktur nicht selbst, sondern entscheiden nur, welche Felder übernommen werden sollen.
Um einen Wert zuzuweisen, wählen Sie eine globale Variable für das Antwortfeld aus, das Sie verwenden möchten. Felder, die nicht zugewiesen werden, werden ignoriert. Die Zuweisung selbst erfolgt automatisch zur Laufzeit: Jedes Mal, wenn der Workflow diese Aktivität ausführt, werden die Antwortwerte in die zugeordneten globalen Variablen geschrieben. Diese Variablen können anschließend in den weiteren Workflow-Schritten verwendet werden – zum Beispiel in Bedingungen, Benachrichtigungen oder anderen Aktivitäten.
Anders als bei REST-Webdiensten, bei denen sich Antwortdaten sowohl globalen Variablen als auch Indexfeldern des Dokuments zuweisen lassen, unterstützt die SOAP-Datenzuweisung ausschließlich globale Variablen.
Im Beispiel im Screenshot gibt die Methode „DeleteUnsignedDocument" ein „DeleteUnsignedDocumentResult" mit einem Feld „Message" vom Typ String zurück. Dieses Feld könnte einer globalen Variablen zugeordnet werden, um eine Bestätigung oder Fehlermeldung des Signaturdienstes zu erfassen.
Fehlerbehandlung
Wechseln Sie zur Registerkarte Fehler, um festzulegen, wie der Workflow weiterlaufen soll, falls der Aufruf des Webdienstes fehlschlägt. Ist beispielsweise der externe Webdienst nicht verfügbar, können Sie den Workflow so konfigurieren, dass das Dokument an eine andere automatisierte Aktion weitergeleitet wird, etwa an eine E-Mail-Benachrichtigung mit der Aufforderung, die fehlenden Informationen manuell einzugeben.
Wählen Sie eine der folgenden Optionen:
Keine Fehlerbehandlung: Diese Option ist standardmäßig aktiviert.
Workflow neu starten: Das Dokument wird automatisch erneut von Anfang an durch die Workflow-Schritte geleitet.
Workflow beenden: Das Dokument wird automatisch ans Ende des Workflows weitergeleitet. Alle bis zu diesem Zeitpunkt vorgenommenen Änderungen bleiben erhalten.
Zu Schritt wechseln: Diese Option fügt der Aktivität Daten zuweisen einen Ausgang Fehler hinzu. Verbinden Sie ihn mit einer anderen Aktivität, um das Dokument im Workflow manuell weiterzuleiten.