Wiki-Quellcode von d.3: DMS-Plugin

Zeige letzte Bearbeiter
1 [[**Plugin-Download**>>url:https://customer.formcycle.eu/index.php/apps/files/?dir=/FORMCYCLE%20-%20Plugins%20Customer/plugin-bundle-d3&fileid=2596||target="_blank"]] (erfordert Anmeldung)
2
3 {{content/}}
4
5 Über das kostenpflichtige d.3 DMS (**D**okumenten **M**angement **S**ystem) Plugin ist es möglich Dokumente aus {{formcycle/}} an das d.3 DMS zu übermitteln. Das Plugin nutzt dafür die vom d.3 System bereitgestellte [[SOAP>>https://de.wikipedia.org/wiki/SOAP||rel="noopener noreferrer" target="_blank" title="Simple Object Access Protocol"]]-Webservice Schnittstelle.
6
7 == Aktions-Plugin: //d.3 DMS: Dokument importieren// ==
8
9 Für die Übermittlung von Dokumenten an das d.3 System steht das Aktions-Plugin **d.3 DMS: Dokument importieren** zur Verfügung. 
10 Dieses ermöglicht es, Dateien, welche über eine [[(Datei-)bereitstellende Aktion>>doc:Formcycle.Designer.Workflow.Actions.WebHome||target="_blank"]] in der Statusverarbeitung verfügbar sind, in ein d.3 DMS zu überführen.
11
12 Die Konfigurationsoberfläche des Aktions-Plugins ist in einzelne Bereiche unterteilt, die nachfolgend kurz beschrieben werden.
13
14 === Globale d.3 Server-Konfiguration übersteuern ===
15
16 {{figure image="plugin_config.png"}}
17 Einstellungen zum Übersteuern der global definierten Verbindungsparameter
18 {{/figure}}
19
20 In diesem Bereich besteht die Möglichkeit die global am Plugin-Bundle registrierten Eigenschaften für den anzubindenden d.3 Server und deren Authentifizierungs-Informationen formular-prozess-spezifisch zu übersteuern.
21 Wenn für eine Eigenschaft kein Wert festgelegt ist, werden die [[global am Plugin-Bundle hinterlegten Einstellungen>>doc:||anchor="plugin_bundle_props" target="_blank"]] verwendet.
22 Es können Platzhalter (Auswahlmöglichkeit über Button [[image:icon_placeholder.png]]) für einzelne Einstellungen verwendet werden.
23
24 ; IP-Adresse
25 : IP-Adresse, unter welcher der d.3 Server erreichbar ist
26 ; Port
27 : Port, unter dem der d.3 Servers angesprochen werden kann
28 ; Archiv
29 : Kürzel für das genutzte Archiv auf dem d.3 Server
30 ; Sprache
31 : Kürzel für die zu verwendende Sprache. Format muss zweistellig sein (z.B.: //de// bzw. //en//).
32 ; Nutzer
33 : Nutzer-Account für den Zugriff auf den d.3 Server
34 ; Passwort
35 : Das zum Nutzer-Account zugehörige Passwort
36 ; Nutzergruppe
37 : Nutzerguppe der der Nutzer angehört. Diese Angabe wird **zwingend** benötigt, wenn von einem Dokument eine neue Version erzeugt werden soll.
38 ; Endpoint URL
39 : Endpoint-URL zum angebundenen d.3 Server.
40
41 {{info}}
42 Über den [[image:btn_check.png]]-Button kann die Erreichbarkeit des d.3 Systems geprüft werden.
43 Beachten Sie dabei, dass bei Verwendung von Platzhaltern keine Prüfung der Erreichbarkeit durchgeführt werden kann, da Platzhalter erst zur Ausführungszeit des Plugins mit realen Werten belegt werden.
44 {{/info}}
45
46 === Einstellungen für den DMS Dokumentimport ===
47
48 {{figure image="plugin_config_import.png"}}
49 Einstellungen für den Dokumentimport ins d.3 DMS
50 {{/figure}}
51
52 ; Zu importierende(s) Dokument(e) (Pflichtfeld)
53 : In diesem Auswahlfeld werden alle (datei)-bereitstellenden Aktionen, welche dem Import-Plugin vorangestellt sind, aufgeführt. Die hier getroffene Auswahl bestimmt die Medien (Dokument(e) oder Bild(er)) welches ins d.3 DMS übermittelt werden sollen.
54 {{id name="doc_type"/}}
55 ; Dokument-Typ (Pflichtfeld)
56 : In diesem Auswahlfeld werden alle durch den d.3 Systembetreuer definierten und für einen Import aus {{formcycle/}} bestimmten d.3 Objekt-Typen aufgeführt.
57 ; Dokument Metadaten
58 : In dieser Konfigurations-Tabelle werden die Dokument Metadaten zum jeweiligen //d.3 Dokument-Typ// verwaltet. Die Metadaten können dabei manuell durch den Nutzer angelegt oder aus dem d.3 System bezogen werden. Für eine automatische Ermittlung muss im Vorfeld durch einen d.3 Systembetreuer eine entsprechende Definition der Metadaten im d.3 System durchgeführt werden.
59
60 {{info title="**Was sind Dokument Metadaten im Zusammenhang mit d.3?**"}}
61 Mit der Definition von Dokument-Typen im d.3 DMS ist meist die Definition von zusätzlichen Eigenschaften an diesen Objekten (sogenannten Metadaten) verbunden. Diese Metadaten werden im d.3 System benötigt um verschiedene Prozesse zu steuern (z.B.: interne Verarbeitung, Suche, Verschlagwortung von Objekten etc.). Ein Teil dieser Metadaten muss bereits beim Neuanlegen von Objekten bekannt sein, weshalb sich an dieser Stelle die Notwendigkeit zur Definition der Metadaten in der {{formcycle/}} Oberfläche erklärt.
62 {{/info}}
63
64 ; Dokument-Nummer
65 : An dieser Stelle können Sie eine individuelle Dokumentennummer für die Ablage des Dokuments im d.3 DMS festlegen.
66 : Wenn bereits ein Dokument mit dieser Nummer im d.3 System existiert, wird versucht das übermittelte Dokument als neue Version im System abzulegen.
67
68 {{info title="Hinweis:"}}
69 Die Angabe einer Dokument-Nummer ist nur sinnvoll, wenn es sich bei den "zu importierenden Dokumenten" um eine einzelne Datei handelt.
70 {{/info}}
71
72 ==== Interaktionsmöglichkeiten innerhalb der Konfigurations-Tabelle //Dokument Metadaten// ====
73
74
75 Über die Schaltfläche [[image:icon_add.png]] kann ein neues Dokument Metadatum in die Konfigurations-Tabelle eingefügt werden.
76 Anschließend muss für dieses Metadatum der Datentyp, Datenfeldnummer und der mit dem Metadatum zu übertragene Wert und gegebenenfalls eine Bezeichnung (dient als Erläuterung) definiert werden.
77
78 {{info title="Hinweis:"}}
79 Die auswählbaren Datenfeld-Nummern ergeben sich aus dem gewählten Datentyp, sowie aus den noch verfügbaren Nummern. Wenn sie Metadaten manuell anlegen, fragen sie gegebenenfalls ihren d.3 Systembetreuer, welche Datentypen und Datenfeldnummern sie verwenden müssen, damit die übermittelten Metadaten ordnungsgemäß im d.3 System verarbeitet werden können.
80 {{/info}}
81
82 Die zu übertragenen Werte, die den einzelnen Metadaten zugeordnet werden, können dabei über die {{formcycle/}}-[[Platzhalter>>doc:Formcycle.UserInterface.Variables||target="_blank"]]-Logik [[image:icon_placeholder.png]] oder als fest vorgegeben Werte hinterlegt werden. Zu beachten ist dabei, dass der übergebene Wert dem vorgegebenen Datentyp entspricht. Die Tabelle //[[Unterstützte Eingabeformate für Datentypen>>doc:||anchor="metadata_types"]]// listet die verfügbaren Datentypen und deren Eingabeformate auf.
83
84 Zusätzlich zu den in {{formcycle/}} standardmäßig vorhandenen Platzhaltern gibt es die nachfolgend aufgeführten Platzhalter, die nur in diesem Plugin verwendet werden können. Diese Platzhalter sind dafür gedacht, auf spezielle Dateieigenschaften einzelner Dateien zuzugreifen, wenn durch das Feld //Zu importierende(s) Dokument(e)// **mehrere** Dateien gleichzeitig ins DMS überführt werden.
85
86 * **[%%FILE_NAME%%]**: Liefert den Dateinamen der aktuell in Bearbeitung befindlichen Datei
87 * **[%%FILE_SIZE%%]**: Liefert die Dateigröße (in Byte) der aktuell in Bearbeitung befindlichen Datei
88
89 {{id name="metadata_update"/}}
90 Über die Schaltfläche [[image:icon_update.png]] können, anhand des ausgewählten Dokument-Typs (oder einer [[initialen Vorgabe>>doc:||anchor="init_docfield_config"]]), Metadaten aus dem d.3 System ermittelt und in die Konfigurations-Tabelle eingefügt werden.
91 Sollte ein Metadatum bereits in der Tabelle existieren, so wird dieses als Pflichtfeld ausgewiesen und kann nicht mehr gelöscht werden.
92 Ein Metadatum gilt dabei als bereits existent, wenn es die gleiche Datenfeldnummer bzw. Datenbank-Position, wie ein einzufügendes Feld besitzt.
93
94
95 Über die Schaltfläche [[image:icon_collapse.png]] kann man sich Metadaten-Details wie Datenfeld-Bezeichnung und Datenfeldnummer einblenden lassen. Mittels [[image:icon_expand.png]] Button lassen sich die Details anschließend wieder ausblenden.
96
97 Über den Button [[image:icon_del.png]] wird das selektierte Metadatum aus der Konfigurations-Tabelle entfernt.
98 Metadaten, welche aus dem d.3 System als Pflichtfelder ermittelt wurden, können nicht gelöscht werden.
99
100 {{id name="metadata_types"/}}
101
102 ==== Unterstützte Eingabeformate für Datentypen ====
103
104
105 Die nachfolgende Tabelle listet alle Datentypen, welche für die Ablage von Metadaten im d.3 System zur Auswahl stehen und deren gefordertes Eingabeformat, auf.
106
107 (% summary="Unterstützte Eingabeformate für Datentypen" %)
108 |=Datentyp|=Erläuterung zum Eingabeformat
109 |Alphanumerisch|Unterstützt werden alle Eingabezeichen (Buchstaben, Ziffern, Sonderzeichen)
110 |Datum|(((
111 Unterstützt werden Datumseingaben der Form **dd.MM.yyyy** (z.B.: //01.01.1970//)
112
113 * **dd:** Tag, zweistellig
114 * **MM:** Monatsangabe, zweistellig
115 * **yyyy:** Jahresangabe, vierstellig
116 )))
117 |Tabelle|(((
118 Beim Datentyp Tabellenfeld werden dynamische Formulareingaben, vom Typ **Alphanumerisch **unterstützt.
119 Für jeden Wert aus einem [[dynamischen Eingabefeld>>doc:Formcycle.Designer.Workflow.DynamicElements||target="_blank"]] wird im d.3 System ein Wert hinterlegt.
120 )))
121 |Geld|Unterstützt werden zweistellige Fließkommazahlen. Als Dezimaltrennzeichen muss ein Komma angegeben werden. (z.B.: //123,50//)
122 |Numerisch|Unterstützt werden positive und negative Fließkommazahlenwerte. Als Dezimaltrennzeichen muss ein Komma angegeben werden. (z.B. //-123,45//)
123
124 === Allgemeine Rückgabewerte ===
125
126 {{figure image="plugin_result.png"}}
127 Konfiguration der Rückgabewerte
128 {{/figure}}
129
130 In diesem Bereich werden die vom Plugin als Ergebnis des DMS Datei-Upload Prozesses 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:
131
132 {{code}}
133
134 [%$<Name der Plugin-Aktion>.RESULT[0].<Name oder vergebener Alias der Rückgabeparameters>%]
135 {{/code}}
136
137 ; ResultCode
138 : Enthält einen Zahlenwert, welchen den Abarbeitungs- bzw. Fehlerstatus des Plugins wiedergibt.
139 ; ResultMessage
140 : Enthält eine Klartextmeldung, welche den zurückgelieferten //ResultCode// näher erläutert.
141 ; ResultDocumentID
142 : Enthält die vom d.3 System zurückgelieferte Dokument-ID, wenn das Dokument erfolgreich im d.3 System abgelegt werden konnte, sonst den Wert -1.
143
144 {{info}}
145 Über den [[image:icon_copy.png]] Button kann der aus dem Namen oder Alias erzeugte Platzhalter einfach in die Zwischenablage kopiert
146 und an anderer Stelle, z.B.: im Text einer E-Mail-Aktion, eingefügt werden.
147 {{/info}}
148
149 Wenn mehrere Dateien gleichzeitig an das DMS übertragen werden, so wird für jede Datei ein entsprechender //ResultCode//, //ResultMessage// und //ResultDocumentID// zurückgeliefert. Um auf die //ResultDocumentID// (einer Plugin-Aktion mit Namen "D3DMSUpload") der dritten übertragenen Datei zuzugreifen muss dann beispielsweise folgender Platzhalter benutzt werden:
150
151 {{code}}
152
153 [%$D3DMSUpload.RESULT[2].ResultDocumentID%]
154 {{/code}}
155
156 Bei gleichzeitiger Übertragung mehrerer Dateien ist es manchmal sinnvoll den Gesamtstatus zu erfragen, um beispielsweise zu wissen, ob ein Fehler beim Import einer Datei aufgetreten ist.
157 Dies kann über den Platzhalter
158
159 {{code}}
160
161 [%$<Name der Plugin-Aktion>.SUCCESS%]
162 {{/code}}
163
164 erfolgen. Dieser liefert "true" zurück, wenn alle Dateien erfolgreich an das DMS übermittelt werden konnten, sonst "false".
165 Der Platzhalter
166
167 {{code}}
168
169 [%$<Name der Plugin-Aktion>.COUNT%]
170 {{/code}}
171
172 wiederum kann genutzt werden, wenn man die Gesamtanzahl der zurückgelieferten Ergebnisse wissen möchte.
173
174 Die nachfolgende Tabelle liefert eine Übersicht über alle vom Plugin zurückgelieferten Status- bzw. Fehlercodes:
175
176 |=Status / Fehlercode|=Bedeutung
177 |0|Das Plugin wurde fehlerfrei ausgeführt.
178 |10|Die Authentifizierung am d.3 DMS ist fehlgeschlagen, überprüfen Sie bitte die Eigenschaften des anzusprechenden d.3 Servers.
179 |20|Der d.3 DMS-Webservice konnte aufgrund fehlender Pflicht-Parameter (//…Name der fehlenden Pflichtparameter…//) nicht aufgerufen werden.
180 |21|Fehler beim Einlesen des zu importierenden Dokuments
181 |22|Es konnte keine Dokument für einen Import ermittelt werden.
182 |23|Folgende Dokument-Metadaten beinhalten fehlerhafte Werte: …//Auflistung der fehlerhaften Werte//
183 |24|Fehler beim Erzeugen einer neuen Dokument Version.
184 |30|Es konnte keine Verbindung zum d.3 DMS Webservice aufgebaut werden.
185 |31|Aufruf einer Webservice-Methode lieferte Fehler: ...//Detaillierte Fehlermeldung aus d.3 System//
186 |40|In FORMCYCLE ist ein nicht näher spezifizierter Fehler aufgetreten.
187
188 == Globale Plugin-Einstellungen ==
189
190 {{info}}
191 Dieser Abschnitt ist nur für {{formcycle/}}-Administratoren relevant, die das Plugin-Bundle initial im System einrichten.
192 {{/info}}
193
194 Das d.3 DMS Plugin-Bundle kann sowohl im System- als auch im Mandant-Kontext installiert werden.
195 Die Menüpunkte für die jeweiligen Kontexte sind:
196
197 * **System-Kontext:** System > Systemplugins
198 * **Mandant-Kontext:** Mandant > Plugins
199
200 {{id name="plugin_bundle_props"/}}
201
202 === Konfiguration der Plugin-Bundle Properties ===
203
204 {{figure image="plugin_bundle_config.png"}}
205 Globale Einstellungen am Plugin-Bundle
206 {{/figure}}
207
208 Über die nachfolgend beschriebenen Einstellungen wird das Plugin ein d.3 System angeschlossen. Die Verbindung erfolgt dabei über einen SOAP-Webservice, welcher vom d.3 System zu Verfügung gestellt wird.
209
210 ==== Einstellungen für die Anbindung des d.3 Webservice ====
211
212
213 ; dms.webservice.url (Pflichtfeld)
214 : Endpoint-URL zum d.3 SOAP-Webservice. Die Angabe muss in der Form
215
216 : **//http:~/~/<host>:<port>/ws/servicesD3WService.wsdl//**
217
218 : erfolgen.
219 ; dms.webservice.connection.timeout
220 : Wert für Connection-Timeout in Millisekunden, bei der Kommunikation mit dem d.3 Webservice.
221 : (Standardwert: //10000,// dies entspricht 10 Sekunden)
222 ; dms.webservice.read.timeout
223 : Wert für Read-Timeout in Millisekunden, bei der Kommunikation mit dem d.3 Webservice.
224 : (Standardwert: //30000, //dies entspricht 30 Sekunden)
225
226 ==== Einstellungen für den verwendeten d.3 Server ====
227
228
229 ; d3.server.ip (Pflichtfeld)
230 : IP-Adresse des anzubinden d.3 Systems.
231 ; d3.server.port (Pflichtfeld)
232 : Port, über den das anzubindende d.3 System erreichbar ist.
233 ; d3.server.archive (Pflichtfeld)
234 : Kürzel mit dem das Repository bzw. Archive des anzubindenden d.3 Systems angesprochen werden kann.
235 ; d3.server.language (Pflichtfeld)
236 : Kürzel für die zu verwendende Sprache. Format muss zweistellig sein (z.B.: //de// bzw. //en//).
237 ; d3.server.login (Pflichtfeld)
238 : Nutzer-Login, um Zugriff zum d.3 System zu erhalten.
239
240 {{info}}
241 Alle nutzerabhängigen Webservice-Funktionen, verwenden ebenfalls diesen Login.
242 {{/info}}
243
244 ; d3.server.pwd (Pflichtfeld)
245 : Nutzer-Passwort für den Zugriff zum d.3 System.
246 ; d3.user.group
247 : d.3-Nutzergruppe, welchem der Nutzer-Login angehört.
248
249 {{info}}
250 Diese Angabe ist notwendig, wenn für ein bestehendes Dokument eine neue Version im d.3 System erzeugt werden soll.
251 Das Dokument muss dann gegebenenfalls in den „Bearbeiten“-Status überführt werden und dies geht nur durch Angabe einer Nutzergruppe.
252 {{/info}}
253
254 ==== Einstellungen für das Statusverarbeitungs-Plugin "Dokument importieren" ====
255
256
257 ; d3.import.doc.types
258 : Definiert eine Auflistung von d.3 Objekt-Typen, welche als Auswahl innerhalb des Aktions-Plugins dargestellt werden.
259 : Ein Objekttyp definiert sich über sein, im d.3 DMS festgelegtes, Dokument-Kürzel.
260 : Ein Listenwert besteht immer aus Dokument-Kürzel und Anzeige-Name und ist nach folgender Bildungsvorschrift zu hinterlegen:
261
262 : **//<Dokument-Kürzel aus d.3>//~://<Anzeigename in Auswahlliste>//,...**
263
264 : Einzelne Listenwerte sind durch Komma zu trennen.
265 {{id name="init_docfield_config"/}}
266 ; d3.initial.docfield.config.doc.type
267 : Definiert ein //d.3 Dokument-Typ//-Kürzel, welches Definitionen für eine automatisierte Erstellung von //[[Dokument Metadaten>>doc:||anchor="metadata_update"]]// Feldern enthält.
268
269 {{info title="Hinweis für {{formcycle/~}~} Systembetreuer:"}}
270 Wurde für diese Plugin-Einstellung **kein** Wert hinterlegt, greift bei der automatisierten Metadaten Ermittlung im [[Aktions-Plugin>>doc:||anchor="metadata_update"]] eine Rückfall-Logik welche untersucht, ob am gewählten [[Dokument-Typ>>doc:||anchor="doc_type"]], innerhalb des d.3 Systems, Pflichtfelder (sogenannte "DocFields") definiert sind. Ist dies der Fall, werden diese als Metadaten in die Konfigurations-Tabelle übernommen.
271 {{/info}}
272
273 ; d3.initial.docfield.config.mapping
274 : Definiert die Auflistung der Zuordnungen, welche für die Definition eines Metadatums in der Plugin-Oberfläche herangezogen werden.
275 : Es ist immer eine //Eigenschaft// zu einer d.3 //Datenfeld-Nummer// zuzuordnen, welche die Eigenschaft auf dem angebundenen d.3 System enthält.
276
277 : Folgende Eigenschaften sind zuzuordnen:
278
279 * Dokumentart
280 * Kuerzel
281 * Datenfeld-Bezeichnung
282 * Datenfeld-Nummer
283 * Datenfeld-Typ
284
285 : Die Konfiguration ist nach folgender Bildungsvorschrift zu hinterlegen:
286
287 : **//<Eigenschaft>//~://<d.3 DocField-Nummer, in der die Eigenschaft definiert ist>//,...**
288
289 : (Standardwert: //Dokumentart:1,Kuerzel:2, DatenfeldBezeichnung:3,DatenfeldNummer:4,DatenfeldTyp:5//)
290
291