KomXwork-Plugin

Geändert am Do, 4 Jan um 4:00 NACHMITTAGS

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

Die nachfolgenden Einstellungen sind durch einen Administrator, der die Rechte zum Konfigurieren von Plugins besitzt, vorzunehmen. Folgende Eigenschaften für die Anbindung des KomXwork Systems können definiert werden:

rest.srv.url (Pflichtangabe): Protokoll und Host zu einen KomXwork REST Service. (Die Angabe darf keine konkrete Pfad-Angabe zu einer REST-Aktion beinhalten)
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.

Konfiguration der Authentifizierungsdaten

Die Authentifizerung am REST-Service erfolgt unter Nutzung des OAuth 2.0 Protokolls im Verfahren "Resource Owner Password Credentials". Die Werte der nachfolgend aufgeführten Parameter sind durch das jeweilige KomXwork-System vorgegeben und werden dort im Zuge einer internen Registrierung erzeugt.

client.id: Diese ID repräsentiert die öffentliche Kennung der KomXwork-Anwendung.
Der Standard-Wert ist XIMA_Formcycle.
client.secret: Das Secret, vom KomXwork-System vorgegeben.
granttype: Definiert das aktuell genutzte Authentifizierungs- und Autorisierungsverfahren.
Der Standard-Wert ist client_credentials.
username / password: Diese Angaben sind veraltet und werden ab KomXwork-Version 3.5.x nicht mehr unterstützt

Konfiguration zusätzlicher Einstellungen

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)

Workflow-Plugin KomXwork: 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 KomXwork-Prozess wird der Prozess bestimmt, an den die anschließend festgelegten Daten zu übermitteln sind.

Als Prozessname kann ein Platzhalter festgelegt werden, der den aktuell zu nutzenden Prozess-Namen zur Ausführungszeit enthält. Dadurch wird es beispielsweise möglich die Daten, je nach vorgelagerten Verarbeitungsprozessen, an verschiedene KomXwork-Prozesse zu übergeben.

In der Tabelle KomXflow-Feld-Definitionen erfolgt die eigentliche Festlegung der zu übermittelnden Daten.
Beim Anlegen der neuen KomXwork: Prozess starten-Aktion wird automatisch das mit der Statusverarbeitung verbundene Formular nach allen Elementen durchsucht und diese als neue KomXflow-Feld-Definitions-Elemente angelegt.

Bei späteren Änderungen im Formular kann über den icon_update -Button eine Aktualisierung der KomXflow-Feld-Definitions-Elemente durchgeführt werden. Es werden dabei alle nicht aktuell vorhandenen Formular-Elemente in die Auflistung eingefügt.

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.

Ermittlung vorhandener Formularelemente zur automatischen Befüllung der zu übermittelnden Elemente

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-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 angezeigenten 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 im Workflow zur Verfügung stellen, einbinden.

Übersteuern der Serverkonfiguration

Einstellungen zur Übersteuerung global definierter Verbindungsparameter

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.
Grant-Type: Definiert das aktuell genutzte Authentifizierungs- und Autorisierungsverfahren.; Übersteuert den global definierten Parameter granttype.
Nutzername / Passwort: Diese Angabe sind mit Einbindung der KomXwork-Version >= 3.5.x veraltet.

Rückgabeparameter

Im Erfolgsfall liefert die Workflow-Aktion des Ergebnis des Webservice-Aufrufs als JSON Objekt zurück.
Per Platzhalter kann auf dieses Objekt zugegriffen werden.
Der Platzhalter wird dabei nach dem folgenden Muster gebildet:

[%$<Plugin-Name>.RESULT.jsonString%]