KomXwork-Plugin
Plugin-Download (erfordert Anmeldung)
Über das kostenpflichtige KomXwork Plugin ist es möglich die durch das KomXwork System bereitgestellte Schnittstelle zum KomXflow in Formcycle anzubinden.
Konfiguration der Verbindungseinstellungen zum KomXwork System
- rest.srv.url (Pflichtangabe)
- Protokoll und Host zu einen KomXwork REST Service. (Die Angabe erfolgt ohne konkrete Pfad-Angabe zu einer REST-Aktion.
- Die vom System unterstützten Pfade werden in anderen Einstellungen hinterlegt.)
- rest.api.auth (Pflichtangabe)
- REST-API für die Ermittlung eines Authentifizerungstokens unter Zuhilfenahme der Daten aus dem unten stehenden Bereich Konfiguration der Authentifizierungsdaten.
- (Hinweis: Der hier vorgegebene Standardwert api/v1/token muss nur angepasst werden, wenn sich die Schnittstelle auf Seiten von KomXwork ändert.)
- rest.api.workflow (Pflichtangabe)
- REST API für das Starten eines KomXflow-Prozesses. Der Platzhalter '{key}' wird dabei in der jeweiligen Konfiguration eines Aktions-Plugin gesetzt, welches diese REST-API nutzt.
- (Hinweis: Der hier vorgegebene Standardwert workflow/process-definition/key/{key}/start muss nur angepasst werden, wenn sich die Schnittstelle auf Seiten von KomXwork ändert.)
- rest.srv.connection.timeout
- Wert für ein Connection-Timeout in Millisekunden. (Standardwert: 10 Sekunden)
- rest.srv.read.timeout
- Wert für ein Read-Timeout in Millisekunden. (Standardwert: 30 Sekunden)
- rest.srv.proxy.host
- Die Host-Angabe, bei Kommunikation über einen Proxy-Server.
- rest.srv.proxy.port
- Die Port-Angabe, bei Kommunikation über einen Proxy-Server.
- client.id
- Diese ID repräsentiert die öffentliche Kennung der KomXwork-Anwendung
- client.secret
- Das Secret, vom KomXwork-System vorgegeben.
- username
- Namen des Nutzers (=Resource-Owner) über den der Zugriff auf die Web-Service erfolgen soll.
- password
- Passwort für den zuvor definierten Nutzer
- granttype
- Definiert das aktuell genutzte Authentifizierungs- und Autorisierungsverfahren. Momentan wird nur "Resource Owner Password Credentials" in der KomXwork-Anbindung unterstützt, weshalb der Parameter standardmäßig leer ist.
- transmit.empty.parameter
- Diese Einstellung bestimmt, ob die innerhalb der KomXwork-Aktion konfigurierten Parameter, welche zur Laufzeit über keinen Wert verfügen, an KomXwork übertragen werden sollen.
- Standardwert ist: false (Parameter ohne einen Wert, werden nicht an KomXwork übermittelt)
Aktions-Plugin KomXwork:Workflow-Prozess starten
Für die Übermittlung von Formulardaten an die KomXwork-interne Workflow-Engine (KomXflow) steht das Aktions-Plugin KomXwork:Workflow-Prozess starten zur Verfügung.
Dieses ermöglicht es, an einen in KomXflow erstellten Prozess, Daten zu übergeben, welche sich anschließend weiterverarbeiten und gegebenenfalls im KomXwork-DMS ablegen lassen.
Die Konfigurationsoberfläche des Aktions-Plugins ist in einzelne Bereiche unterteilt die nachfolgend kurz beschrieben werden.
Festlegung des zu verwendenden KomXwork-Prozesses und der zu übermittelnden Daten
Über den Konfigurations-Parameter Name des KomXwork-Prozesses wird der Prozess bestimmt, an den die anschließend festgelegten Daten zu übermitteln sind.
In der Tabelle KomXflow-Feld-Definitionen erfolgt die eigentliche Festlegung der zu übermittelnden Daten.
Beim Anlegen der neuen KomXwork:Workflow-Prozess starten-Aktion wird automatisch das mit der Statusverarbeitung verbundene Formular nach allen Elementen durchsucht und diese als neue
KomXflow-Feld-Definitions-Elemente angelegt.
Die nachfolgende Abbildung zeigt wie anhand eines Beispiel-Formulars die Tabelle befüllt wird.
Die Felder, welche mit einemmarkiert sind, wurden dabei als "wiederholbare" Elemente identifiziert. Bei der Übermittlung an KomXwork werden diese gesondert behandelt.
Hinweis: Felder welche automatisiert aus dem Formular ermittelt wurden und bei denen es sich nicht um Upload-Felder handelt, können im Bereich Wert nicht angepasst werden.
Über den-Button können der Tabelle weitere Elemente hinzugefügt werden.
Für ein einzelnes Feld sind dabei Datentyp, KomXflow-Feld-Id, und (zu übermittelnder) Wert festzulegen.
Diese Einstellungen haben folgende Bedeutung:
- Datentyp
- Unterstützt wird: Textfeld, Boolean (Wahrheitswert), Ganzzahl, Fließkommazahl und Datei.
- Der ausgewählte Datentyp hat dabei Auswirkung darauf, in welcher Form der zur Laufzeit übermittelte Wert interpretiert und an KomXwork übermittelt wird.
- Beispielsweise wird bei Festlegung des Datentyps Ganzzahl vor der Übermittlung an KomXwork geprüft, ob der zu übermittelnde Wert, welcher perse eine Zeichenkette darstellt, sich in eine Ganzzahl umwandeln lässt.
- Ist dies nicht der Fall, wird die Datenübermittlung mit einem entsprechenden Fehler abgebrochen. Dadurch ist es möglich bereits vor Übermittlung eine Datentyp-Sicherheit zu gewährleisten.
- KomXflow-Feld-Id
- Enthält den Namen der Variablen, wie er auf Seiten von KomXflow genutzt werden kann. Zu beachten ist dabei, dass sich bei Übermittlung von wiederholbaren Formular-Elementen dieser Name dynamisch,
- um ein Suffix der Form: "_<aktuelle Laufvariable, beginnend bei 1>" erweitert. Näheres dazu ist der Beschreibung im Fieldset Verarbeitungshinweise bei wiederholbaren Elementen, welche sich unterhalb der
- Tabelle KomXflow-Feld-Definitionen befindet, zu entnehmen.
- Wert
- Enthält den an KomXflow zu übermittelnden Wert. Dieser kann aus Platzhalter(n) oder fest hinterlegten Werten bestehen. Bei einer vom Datentyp Textfeld abweichenden Festlegung, muss sich der zu Laufzeit ergebende Gesamtwert,
- in den entsprechenden Datentyp umwandeln lassen.
- Wird zur Laufzeit kein Wert ermittelt, weil beispielsweise ein Platzhalter keinen Wert referenziert, dann wird dieses KomXflow-Feld von der Übermittlung ausgenommen.
Im unteren Beispiel wurde zusätzlich ein neues Feld (Id: FormToPDF) vom Typ Datei hinzugefügt und mit dem Ergebnis einer "dateibereitstellenden"-Aktion belegt.
Zusätzlich zu Upload-Elementen aus dem Formular lassen sich damit auch Aktionen, welche als Ergebnis ihrer Abarbeitung eine Datei in der Statusverarbeitung zur Verfügung stellen, einbinden.
Übersteuern der Serverkonfiguration
In diesem Bereich besteht die Möglichkeit die global am Plugin-Bundle registrierten Eigenschaften für den anzubindenden KomXwork-Server und deren Authentifizierungs-Informationen formular-prozess-spezifisch zu übersteuern.
Es können Platzhalter (Auswahlmöglichkeit über Button ) für einzelne Einstellungen verwendet werden.
- REST-Service URL
- Protokoll und Host zu einen KomXwork REST Service. (z.B. https://my.komxwork-server.de)
- Übersteuert den global definierten Parameter rest.srv.url.
- Client-Id
- Die ID, welche die öffentliche Kennung der KomXwork-Anwendung repräsentiert.
- Übersteuert den global definierten Parameter client.id.
- Client-Secret
- Das Client-Secret, vom KomXwork-System vorgegeben.
- Übersteuert den global definierten Parameter client.secret.
- Nutzername
- Namen des Nutzers (=Resource-Owner) über den der Zugriff auf den Web-Service erfolgen soll.
- Übersteuert den global definierten Parameter username.
- Passwort
- Passwort zum Nutzernamen. Übersteuert den global definierten Parameter password.
- Grant-Type
- Definiert das aktuell genutzte Authentifizierungs- und Autorisierungsverfahren.
- Übersteuert den global definierten Parameter granttype.
Allgemeine Rückgabeparameter
In diesem Bereich werden die vom Plugin als Ergebnis des KomXflow Service-Aufrufs zurückgelieferten Parameter aufgeführt.
Für die einzelnen Parameter kann ein Alias vergeben werden.
In weiteren Aktionen kann auf den entsprechenden Rückgabeparameter per Platzhalter-Syntax zugegriffen werden.
Der Platzhalter wird dabei nach dem folgenden Muster gebildet:
- ResultCode
- Das Ergebnis der Ausführung der Plugin-Aktion wird in Form eines Statuscode zurückgeliefert.
- Dabei definiert der Statuscode "0", dass das Plugin fehlerfrei ausgeführt werden konnte.
- Im Fehlerfall werden unterschiedliche Statuscodes zurückgeliefert, welche die folgenden Bedeutungen haben:
- 10:
- Es konnte kein KomXwork-Prozess zur Ausführung ermittelt werden.
- (Prüfen Sie bitte die Einstellungen im Bereich Name des KomXwork-Prozesses)
- 11:
- Es konnten keine Daten für eine Übermittlung an KomXwork ermittelt werden.
- (Prüfen Sie bitte die Einstellungen im Bereich KomXflow-Feld-Definitionen auf Korrektheit)
- 12:
- Die Werte von folgenden KomXflow-Felder konnten nicht in den festgelegten Datentyp umgewandelt werden: <Auflistung aller betroffenen KomXflow-Feld-ID's>
- 30:
- Es konnte keine Verbindung zum Service unter dem URL '<URL des angefragten Service>' aufgebaut werden.
- 31:
- Der Serviceaufruf lieferte folgenden Fehler: <Detailierte Fehlerinformationen die vom gerufenen Service zurückgeliefert wurde>
- 40:
- In FORMCYCLE ist ein nicht näher spezifizierter Fehler aufgetreten: <Platzhalter für nähere Fehlerbeschreibung>
- ResultMessage
- Eine zum Statuscode zugehörige Meldung
- ResultJSONString
- Das vom Service-Aufruf zurückgelieferte JSON (JavaScript Object Notation) - Objekt zur weiteren Verarbeitung
Videos
Demonstration der Schnittstelle zwischen FORMCYCLE und komXwork Teil 1
Demonstration der Schnittstelle zwischen FORMCYCLE und komXwork Teil 2
Versionshistorie
2.2.0
- Ab dieser Plugin-Version wird mindesten Xima® Formcycle in Version 7.4.0+ benötigt
- In KomXwork (ab Version 3.5.0) wurde eine Authentifizierungsschnittstelle für die m2m-Authentifizierung eingeführt. Diese wird jetzt automatisch angesprochen, wenn sich die angebundene KomXwork-Umgebung entsprechend ihrer Versions-Nummer >= 3.5.0 ausweist. Bei dieser Authentifizierung entfällt die Angabe von Nutzername / Passwort.
2.1.0
- Erweiterung Business-Logik: Parameter ohne eine Wert zur Laufzeit können jetzt übertragen werden. Dafür wurde in den Bundle-Properties ein Steuerparameter (transmit.empty.parameter) hinzugefügt.
2.0.1
- Fehlerbehebung: fehlerhaften Java-Import entfernt
2.0.0
- Erweiterung: Bereitstellung Workflow-Aktion für Anbindung von KomXwork in V7-Formularen
1.1.2
- Fehlerbehebung: Ein Fehler, welcher beim Aktualisieren der KomXflow-Feld-Definitionen aus den Formulardaten in der Oberfläche aufgetreten ist, wurde behoben.
1.1.1
- Fehlerbehebung: Einstellungen für Read- und Connection-Timeout bei der Webservice-Kommunikation werden jetzt beachtet.
- Refactoring: Umstellung von ID auf UUID
1.1.0
- Erweiterung der Schnittstelle, um die Möglichkeit zur Übermittlung von dynamischen (wiederholbaren) Elementen.
- Es können zusätzlich zu Upload-Elementen aus dem Formular, auch dateibereitstellende Aktionen angebunden werden
1.0.0
- initiale Anbindung der KomXflow-Schnittstelle