Wiki-Quellcode von KomXwork-Plugin

Zeige letzte Bearbeiter
1 [[**Plugin-Download**>>url:https://customer.formcycle.eu/index.php/apps/files/?dir=/FORMCYCLE%20-%20Plugins%20Customer/KomXwork-Plugin%20(plugin-bundle-komxwork)&fileid=13425||rel="noopener noreferrer" target="_blank"]] (erfordert Anmeldung)
2
3 {{content/}}
4
5 Über das kostenpflichtige KomXwork Plugin ist es möglich die durch das KomXwork System bereitgestellte Schnittstelle zum KomXflow in Formcycle anzubinden.
6
7
8 {{panel title="Konfiguration der Verbindungseinstellungen zum KomXwork System" initial="hidden" triggerable="true"}}
9
10 {{figure image="bundle_props.png"}}
11 Globale Einstellungen am Plugin-Bundle
12 {{/figure}}
13
14 (((
15 Die nachfolgenden Einstellungen sind durch einen Administrator, der die Rechte zum Konfigurieren von Plugins besitzt, vorzunehmen.
16 )))
17
18 (((
19 Folgende Eigenschaften für die Anbindung des KomXwork Systems können definiert werden:
20
21
22 )))
23
24 ; rest.srv.url (Pflichtangabe) {{id name="bundle_prop_rest_url"/}}
25 : Protokoll und Host zu einen KomXwork REST Service. (Die Angabe erfolgt ohne konkrete Pfad-Angabe zu einer REST-Aktion.
26 : Die vom System unterstützten Pfade werden in anderen Einstellungen hinterlegt.)
27 ; rest.api.auth (Pflichtangabe)
28 : REST-API für die Ermittlung eines Authentifizerungstokens unter Zuhilfenahme der Daten aus dem unten stehenden Bereich //Konfiguration der Authentifizierungsdaten//.
29 : (Hinweis: Der hier vorgegebene Standardwert //api~/v1~/token// muss nur angepasst werden, wenn sich die Schnittstelle auf Seiten von KomXwork ändert.)
30 ; rest.api.workflow (Pflichtangabe)
31 : 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.
32 : (Hinweis: Der hier vorgegebene Standardwert //workflow~/process-definition~/key~/~{key~}~/start// muss nur angepasst werden, wenn sich die Schnittstelle auf Seiten von KomXwork ändert.)
33 ; rest.srv.connection.timeout
34 : Wert für ein Connection-Timeout in Millisekunden. (Standardwert: 10 Sekunden)
35 ; rest.srv.read.timeout
36 : Wert für ein Read-Timeout in Millisekunden. (Standardwert: 30 Sekunden)
37 ; rest.srv.proxy.host
38 : Die Host-Angabe, bei Kommunikation über einen Proxy-Server.
39 ; rest.srv.proxy.port
40 : Die Port-Angabe, bei Kommunikation über einen Proxy-Server.
41
42 (((
43 **Konfiguration der Authentifizierungsdaten**
44
45 )))
46 Die Authentifizerung am REST-Service erfolgt unter Nutzung des OAuth 2.0 Protokolls im Verfahren "Resource Owner Password Credentials".
47 Die Werte der nachfolgend aufgeführten Parameter sind durch das jeweilige KomXwork-System vorgegeben und werden dort im Zuge einer internen Registrierung erzeugt.
48
49
50 ; client.id {{id name="bundle_prop_client_id"/}}
51 : Diese ID repräsentiert die öffentliche Kennung der KomXwork-Anwendung
52 ; client.secret {{id name="bundle_prop_client_secret"/}}
53 : Das Secret, vom KomXwork-System vorgegeben.
54 ; username {{id name="bundle_prop_user"/}}
55 : Namen des Nutzers (~=Resource-Owner) über den der Zugriff auf die Web-Service erfolgen soll.
56 ; password {{id name="bundle_prop_pwd"/}}
57 : Passwort für den zuvor definierten Nutzer
58 ; granttype {{id name="bundle_prop_granttype"/}}
59 : 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.
60
61 (((
62 **Konfiguration zusätzlicher Einstellungen**
63
64 )))
65
66 ; transmit.empty.parameter
67 : Diese Einstellung bestimmt, ob die innerhalb der //KomXwork//-Aktion konfigurierten Parameter, welche zur Laufzeit über keinen Wert verfügen, an //KomXwork// übertragen werden sollen.
68 : Standardwert ist: **false** (Parameter ohne einen Wert, werden nicht an KomXwork übermittelt)
69
70 {{/panel}}
71
72
73 == Aktions-Plugin //KomXwork:Workflow-Prozess starten// ==
74
75 Für die Übermittlung von Formulardaten an die //KomXwork//-interne Workflow-Engine (//KomXflow//) steht das Aktions-Plugin **KomXwork:Workflow-Prozess starten** zur Verfügung.
76 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.
77
78 Die Konfigurationsoberfläche des Aktions-Plugins ist in einzelne Bereiche unterteilt die nachfolgend kurz beschrieben werden.
79
80 === Festlegung des zu verwendenden KomXwork-Prozesses und der zu übermittelnden Daten ===
81
82 Über den Konfigurations-Parameter **Name des KomXwork-Prozesses** wird der Prozess bestimmt, an den die anschließend festgelegten Daten zu übermitteln sind.
83
84 {{info}}
85 Mittels [[image:icon_placeholder.png]]-Button kann ein Platzhalter festgelegt werden, der den aktuell zu nutzenden Prozess-Namen zur Ausführungszeit enthält.
86 Dadurch wird es beispielsweise möglich die Daten, je nach vorgelagerten Verarbeitungsprozessen, an verschiedene KomXwork-Prozesse zu übergeben.
87 {{/info}}
88
89
90 In der Tabelle **KomXflow-Feld-Definitionen** erfolgt die eigentliche Festlegung der zu übermittelnden Daten.
91 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
92 **KomXflow-Feld-Definition**s-Elemente angelegt.
93
94 {{info}}
95 Bei späteren Änderungen im Formular kann über den [[image:icon_update]]-Button eine Aktualisierung der **KomXflow-Feld-Definition**s-Elemente durchgeführt werden.
96 Es werden dabei alle nicht aktuell vorhandenen Formular-Elemente in die Auflistung eingefügt.
97 {{/info}}
98
99
100 Die nachfolgende Abbildung zeigt wie anhand eines Beispiel-Formulars die Tabelle befüllt wird.
101 Die Felder, welche mit einem[[image:icon_info.png]]markiert sind, wurden dabei als "wiederholbare" Elemente identifiziert. Bei der Übermittlung an //KomXwork// werden diese gesondert behandelt.
102 __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.
103
104
105 Über den[[image:icon_add.png]]-Button können der Tabelle weitere Elemente hinzugefügt werden.
106 Für ein einzelnes Feld sind dabei //Datentyp//, //KomXflow-Feld-Id//, und (zu übermittelnder) //Wert //festzulegen.
107 Diese Einstellungen haben folgende Bedeutung:
108
109 ; Datentyp
110 : Unterstützt wird: //Textfeld//, //Boolean// (Wahrheitswert), //Ganzzahl//, //Fließkommazahl// und //Datei//.
111 : Der ausgewählte Datentyp hat dabei Auswirkung darauf, in welcher Form der zur Laufzeit übermittelte Wert interpretiert und an //KomXwork// übermittelt wird.
112 : 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.
113 : 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.
114 ; KomXflow-Feld-Id
115 : 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,
116 : 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
117 : Tabelle **KomXflow-Feld-Definitionen** befindet, zu entnehmen.
118 ; Wert
119 : 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,
120 : in den entsprechenden Datentyp umwandeln lassen.
121 : Wird zur Laufzeit kein Wert ermittelt, weil beispielsweise ein Platzhalter keinen Wert referenziert, dann wird dieses //KomXflow-Feld// von der Übermittlung ausgenommen.
122
123 Im unteren Beispiel wurde zusätzlich ein neues Feld (Id: FormToPDF) vom Typ //Datei// hinzugefügt und mit dem Ergebnis einer "dateibereitstellenden"-Aktion belegt.
124 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.
125
126
127 [[image:plugin_elem_config_example.png]]
128
129
130 === Übersteuern der Serverkonfiguration ===
131
132 {{figure image="plugin_srv_config.png"}}
133 Einstellungen zur Übersteuerung global definierter Verbindungsparameter
134 {{/figure}}
135
136 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.
137 Es können Platzhalter (Auswahlmöglichkeit über Button [[image:icon_placeholder.png]]) für einzelne Einstellungen verwendet werden.
138
139 ; REST-Service URL
140 : Protokoll und Host zu einen KomXwork REST Service. (z.B. //https:~/~/my.komxwork-server.de//)
141 : Übersteuert den global definierten Parameter **[[rest.srv.url>>doc:||anchor="bundle_prop_rest_url"]]**.
142 ; Client-Id
143 : Die ID, welche die öffentliche Kennung der KomXwork-Anwendung repräsentiert.
144 : Übersteuert den global definierten Parameter **[[client.id>>doc:||anchor="bundle_prop_client_id"]]**.
145 ; Client-Secret
146 : Das Client-Secret, vom KomXwork-System vorgegeben.
147 : Übersteuert den global definierten Parameter **[[client.secret>>doc:||anchor="bundle_prop_client_secret"]]**.
148 ; Nutzername
149 : Namen des Nutzers (=Resource-Owner) über den der Zugriff auf den Web-Service erfolgen soll.
150 : Übersteuert den global definierten Parameter **[[username>>doc:||anchor="bundle_prop_user"]]**.
151 ; Passwort
152 : Passwort zum //Nutzernamen//. Übersteuert den global definierten Parameter **[[password>>doc:||anchor="bundle_prop_pwd"]]**.
153 ; Grant-Type
154 : Definiert das aktuell genutzte Authentifizierungs- und Autorisierungsverfahren.
155 : Übersteuert den global definierten Parameter **[[granttype>>doc:||anchor="bundle_prop_granttype"]]**.
156
157 === Allgemeine Rückgabeparameter ===
158
159 {{figure image="plugin_result.png"}}
160 Konfiguration der Plugin Rückgabedaten (Platzhalter)
161 {{/figure}}
162
163 (((
164 In diesem Bereich werden die vom Plugin als Ergebnis des //KomXflow// Service-Aufrufs zurückgelieferten Parameter aufgeführt.
165 Für die einzelnen Parameter kann ein Alias vergeben werden.
166 In weiteren Aktionen kann auf den entsprechenden Rückgabeparameter per Platzhalter-Syntax zugegriffen werden.
167 Der Platzhalter wird dabei nach dem folgenden Muster gebildet:
168 )))
169
170 {{code language="javascript"}}
171 [%$<Plugin-Name>.RESULT[0].<Name oder vergebener Alias der Rückgabeparameters>%]
172 {{/code}}
173
174 {{info}}
175 Über den [[image:icon_copy.png]] Button kann der aus dem Namen oder Alias erzeugte Platzhalter einfach in die Zwischenablage kopiert
176 und an anderer Stelle, zum Beispiel im Text einer E-Mail-Aktion, mittels {{code language="none"}}Ctrl+V{{/code}} eingefügt werden.
177 {{/info}}
178
179
180 ; ResultCode
181 : Das Ergebnis der Ausführung der Plugin-Aktion wird in Form eines Statuscode zurückgeliefert.
182 : Dabei definiert der Statuscode **"0"**, dass das Plugin fehlerfrei ausgeführt werden konnte.
183 : Im Fehlerfall werden unterschiedliche Statuscodes zurückgeliefert, welche die folgenden Bedeutungen haben:
184 :; 10:
185 :: Es konnte kein //KomXwork//-Prozess zur Ausführung ermittelt werden.
186 :: (Prüfen Sie bitte die Einstellungen im Bereich **Name des KomXwork-Prozesses**)
187 :; 11:
188 :: Es konnten keine Daten für eine Übermittlung an //KomXwork// ermittelt werden.
189 :: (Prüfen Sie bitte die Einstellungen im Bereich **KomXflow-Feld-Definitionen** auf Korrektheit)
190 :; 12:
191 :: Die Werte von folgenden KomXflow-Felder konnten nicht in den festgelegten Datentyp umgewandelt werden: //<Auflistung aller betroffenen KomXflow-Feld-ID's>//
192 :; 30:
193 :: Es konnte keine Verbindung zum Service unter dem URL '//<URL des angefragten Service>//' aufgebaut werden.
194 :; 31:
195 :: Der Serviceaufruf lieferte folgenden Fehler: //<Detailierte Fehlerinformationen die vom gerufenen Service zurückgeliefert wurde>//
196 :; 40:
197 :: In FORMCYCLE ist ein nicht näher spezifizierter Fehler aufgetreten: //<Platzhalter für nähere Fehlerbeschreibung>//
198 ; ResultMessage
199 : Eine zum Statuscode zugehörige Meldung
200 ; ResultJSONString
201 : Das vom Service-Aufruf zurückgelieferte JSON (**J**ava**S**cript **O**bject **N**otation) - Objekt zur weiteren Verarbeitung
202
203 == Videos ==
204
205 Demonstration der Schnittstelle zwischen FORMCYCLE und komXwork Teil 1
206
207 {{externalVimeoVideo id="451130593" image="Workshops.WebHome@fc_video_play.png" height="400"/}}
208
209
210 Demonstration der Schnittstelle zwischen FORMCYCLE und komXwork Teil 2
211
212 {{externalVimeoVideo id="451130661" image="Workshops.WebHome@fc_video_play.png" height="400"/}}
213
214
215 == Versionshistorie ==
216
217 === 2.2.0 ===
218
219 * Ab dieser Plugin-Version wird mindesten {{formcycle/}} in Version {{version major="7" minor="4"}}{{/version}}benötigt
220 * 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.
221
222 === 2.1.0 ===
223
224 * 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. 
225
226 === 2.0.1 ===
227
228 * Fehlerbehebung: fehlerhaften Java-Import entfernt
229
230 === 2.0.0 ===
231
232 * Erweiterung: Bereitstellung Workflow-Aktion für Anbindung von KomXwork in V7-Formularen
233
234 === 1.1.2 ===
235
236 * Fehlerbehebung: Ein Fehler, welcher beim Aktualisieren der KomXflow-Feld-Definitionen aus den Formulardaten in der Oberfläche aufgetreten ist, wurde behoben.
237
238 === 1.1.1 ===
239
240 * Fehlerbehebung: Einstellungen für Read- und Connection-Timeout bei der Webservice-Kommunikation werden jetzt beachtet.
241 * Refactoring: Umstellung von ID auf UUID
242
243 === 1.1.0 ===
244
245 * Erweiterung der Schnittstelle, um die Möglichkeit zur Übermittlung von dynamischen (wiederholbaren) Elementen.
246 * Es können zusätzlich zu Upload-Elementen aus dem Formular, auch dateibereitstellende Aktionen angebunden werden
247
248 === 1.0.0 ===
249
250 * initiale Anbindung der KomXflow-Schnittstelle