regio iT: Postkorb-Plugin - FORMCYCLE Wiki

1

[[**Plugin-Download**>>url:https://customer.formcycle.eu/index.php/apps/files/?dir=/FORMCYCLE%20-%20Plugins%20Customer/regio%20iT%3A%20Postkorb-Plugin%20(fc-plugin-regioit-postkorb)%20&fileid=13417||target="_blank"]] (erfordert Anmeldung)

2

3

4

Der Abschnitt zur Konfiguration des Plugins ist nur für Administratoren notwendig, welche die Verbindung zur Postkorbschnittstelle einrichten. Wie eine Nachricht an den Postkorb gesendet werden kann, wird im Abschnitt //Postkorb-Aktion// erläutert.

Der Postkorb ist eine Funktion des Serviceportals. Im Postkorb können sogenannte Vorgänge angelegt werden, etwa wenn jemand ein Antragsformular ausgefüllt hat. Zu jedem Vorgang können dann mehrere Nachrichten gesendet werden. Dieses Plugin ermöglicht es, Nachrichten an einen Vorgang aus {{formcycle/}} heraus zu senden. Der Vorgang im Postkorb sollte nicht mit dem Vorgang in {{formcycle/}} verwechselt werden.

Dieses kostenpflichtige Plugin ermöglicht die Anbindung der Postkorbschnittstelle von der regio iT. Über eine [[Workflow-Aktion>>doc:Formcycle.Designer.Workflow.Actions.WebHome]] können Nachrichten an den Postkorb des [[Serviceportals>>https://servicekonto.nrw/]] geschickt werden.

14

15

Das Plugin kann sowohl als System- als auch als Mandantplugin installiert werden. Nach Installation des Plugins müssen in der Plugin-Konfiguration die Verbindungsdaten zur Postkorbschnittstelle eingetragen werden. Danach kann die Workflow-Aktion genutzt werden.

16

17

== Postkorb-Aktion ==

18

19

{{figure image="plugin_regioit_postkorb_workflow_select_action_de.png" width="400"}}

20

Durch Klick auf //neue Aktion// kann die Postkorbschnittstellen-Aktion zum Worfklow hinzugefügt werden.

21

22

23

{{figure image="plugin_regioit_postkorb_workflow_action_base_de.png" width="400"}}

24

Grundlegende Einstellungen zum Versenden einer Nachricht an der Postkorb. Hier kann der Empfänger und der Inhalt der Nachricht eingestellt werden.

25

26

27

{{figure image="plugin_regioit_postkorb_workflow_action_advanced_de.png" width="400"}}

28

Fortgeschrittene Einstellungen für den Postkorb. Hier können die Metadaten des Vorgangs geändert werden, der im Postkorb erstellt wird.

29

30

31

{{figure image="plugin_regioit_postkorb_workflow_action_guest_de.png" width="400"}}

32

Eine neue Nachricht kann auch als Gast an den Postkorb gesendet werden. In dem Fall müssen einige Daten zum Gast eingetragen werden. Es kann sein, dass die Postkorbschnitstelle die Nutzung als Gast nicht erlaubt - dies sollte vorher mit dem Dienstanbieter der Postkorbschnittstelle geklärt werden.

33

34

35

Sobald das Plugin richtig konfiguriert ist, kann in der Statusverarbeitung die Aktion //Nachricht im Postkorb erstellen// ausgewählt werden.

36

37

=== Konfiguration ===

38

39

Die Einstellungen für die Postkorb-Aktion sind ähnlich zur E-Mail-Aktion und in 4 Bereiche unterteilt. Für die meisten Einstellungen sind Standardwerte gesetzt, welche im Regelfall nicht geändert werden müssen - meistens sollten nur die Felder //Betreff// und //Nachricht// geändert werden.

40

41

An den meisten Feldern ist die Verwendung von [[Platzhaltern>>doc:Formcycle.UserInterface.Variables]] möglich, um Daten aus dem Formular einzutragen. Alle Felder, an denen das Nutzen von Platzhaltern möglich sind, haben rechts am Eingabefeld eine kleines Buch-Symbol.

42

43

Für das Senden von Nachrichten sind einige Informationen zum Empfänger notwendig, wie zum Beispiel dessen Kontonummer im Serviceportal. Es wird empfohlen, die Anmeldung am Formular per regio iT (technisch: OpenID Connect) zu aktivieren. So können diese Daten aus dem Nutzerkonto des angemeldeten Benutzers per [[Platzhalter>>doc:Formcycle.UserInterface.Variables]] übernommen werden.

44

45

==== Angaben zum Empfänger ====

46

47

; Art des Versendens

48

: Die Postkorbschnittstelle bietet zwei Möglichkeiten: Es kann (a) eine neuer Vorgang im Postkorb mit einer initialen Nachricht erstellt werden oder (b) eine Nachricht an einen bestehenden Vorgang gesendet werden. Falls bekannt ist, ob der Vorgang im Postkorb schon existiert, kann hier die Option //Neuen Vorgang erstellen// beziehungsweise //Auf bestehenden Vorgang antworten// ausgewählt werden. Andernfalls, wenn es nicht sicher ist, ob der Vorgang bereits existiert, sollte hier die Option //Vorgang anlegen wenn noch nicht vorhanden// ausgewählt werden. Es wird dann zuerst versucht, auf einen bestehenden Vorgang zu antworten. Falls dies fehlschlägt, wird ein neuer Vorgang angelegt.

49

; Kontonummer des Empfängers oder Antragstellers

50

: Hier muss die Kontonummer des Empfängers oder Antragstellers eingetragen werden, an den die Nachricht gesendet werden soll. Im Regelfall melden sich Benutzer über die regio iT am Formular an (technisch: OpenID Connect). In dem Fall ist der voreingestellte Wert ausreichend: //[%$user.userName%//] Dies ist ein [[Platzhalter>>doc:Formcycle.UserInterface.Variables]], der mit der Kontonummer des angemeldeten Nutzers ersetzt wird. Diese Einstellung entspricht dem Parameter //fall.portalkonto// der Postkorbschnittstelle.

51

; Als Gast versenden

52

: Es ist beim Postkorb möglich eine Nachricht als Gast zu versenden, also ohne Kontonummer im Serviceportal zu haben. Dabei ist es nur möglich, einen neuen Vorgang anzulegen, aber nicht auf einen bestehenden zu antworten. Ist diese Option aktiviert, erscheinen zusätzliche Eingabefelder für die Angaben zum Gast. Hinweis: Bitte versichern Sie sich vor dem Nutzen der Funktion bei dem Dienstanbieter der Postkorbschnittstelle ob das Versenden als Gast erlaubt ist.

53

54

Folgende Eingabefelder erscheinen, wenn die Option //Als Gast versenden// aktiviert wurde:

55

56

; E-Mail des Gasts

57

: Falls ein Vorgang als Gast erstellt werden soll: Die E-Mail-Adresse des Gasts. Diese Einstellung entspricht dem Parameter //gast.email// der Postkorbschnittstelle.

58

; Anrede des Gasts

59

: Falls ein Vorgang als Gast erstellt werden soll: Die optionale Anrede des Gasts, etwa //Herr// oder //Frau//. Hinweis: Die Postkorbschnittstelle unterstützt nur spezielle Werte für die Anrede. Diese Einstellung entspricht dem Parameter //gast.anrede// der Postkorbschnittstelle.

60

; Titel des Gasts

61

: Falls ein Vorgang als Gast erstellt werden soll: Der optionale Titel für den Gast, etwa //Dr.//. Diese Einstellung entspricht dem Parameter //gast.titel// der Postkorbschnittstelle.

62

; Vorname des Gasts

63

: Falls ein Vorgang als Gast erstellt werden soll: Der Vorname des Gasts. Diese Einstellung entspricht dem Parameter //gast.vorname// der Postkorbschnittstelle.

64

; Nachname des Gasts

65

: Falls ein Vorgang als Gast erstellt werden soll: Der Nachname des Gasts. Diese Einstellung entspricht dem Parameter //gast.familienname// der Postkorbschnittstelle.

66

67

==== Inhalt der Nachricht ====

68

69

Hier wird der Inhalt der Nachricht eingegeben, die an den Postkorb gesendet werden soll. Optional ist es auch möglich, bis zu 10 Dateien mitzusenden. Mehr als 10 Dateien werden von der Postkorbschnittstelle nicht unterstützt.

70

71

; Absendername

72

: Der Name des Absenders der Nachricht. Standardmäßig ist hier der Platzhalter [%user.displayName%] hinterlegt. Dieser wird mit dem Namen des Benutzers ersetzt, der sich am Formular angemeldet hat. Diese Einstellung entspricht dem Parameter //nachricht.absender// der Postkorbschnittstelle.

73

; Betreff

74

: Ein einzeiliger Betreff der zu sendenden Nachricht. Diese Einstellung entspricht dem Parameter //nachricht.betreff// der Postkorbschnittstelle.

75

; Nachricht

76

: Die mehrzeilige Nachricht, welche an den Postkorb gesendet werden soll. Der Postkorb unterstützt die Nutzung einiger Formatierungsoptionen wie etwa fetter Schrift oder Aufzählungszeichen. Diese Einstellung entspricht dem Parameter //nachricht.inhalt// der Postkorbschnittstelle.

77

; Anhänge aus vorigen Aktionen

78

: Optional können Dateien aus vorigen Aktionen als Anhang mitgesendet werden. Diese Einstellung entspricht den Parametern //anhang.[1-10].*// der Postkorbschnittstelle.

79

; Anhänge aus Formular-Uploads

80

: Optional können Dateien aus Upload-Feldern im Formular als Anhang mitgesendet werden. Diese Einstellung entspricht den Parametern //anhang.[1-10].*// der Postkorbschnittstelle.

81

82

==== Auswahl des Vorgangs ====

83

84

; Neuer Status des Vorgangs im Postkorb

85

: Es ist möglich, den Status des Vorgangs im Postkorb zu ändern. Es gibt dabei die Status //offen//, //in Bearbeitung//, //abgeschlossen// und //storniert//. Standardeinstellung ist, dass der Status nicht geändert wird. Neue angelegte Vorgänge erhalten dabei automatisch den Status //offen//. Es ist zu beachten, dass die Status //in Bearbeitung// und //storniert// nur verfügbar sind, wenn auf einen vorhandenen Vorgang geantwortet wird, aber nicht beim Erstellen eines neuen Vorgangs. Diese Einstellung entspricht dem Parameter //fall.status// der Postkorbschnittstelle.

86

; Externe ID des Vorgangs im Postkorb

87

: Die externe ID des Vorgangs im Postkorb. Jeder Vorgang im Postkorb hat sowohl eine interne ID, die vom Postkorb intern genutzt wird, als auch eine externe ID. Die externe ID identifiziert den Vorgang gegenüber einem Drittsystem, in dem Fall also {{formcycle/}}. Standardmäßig ist hier der Wert //[%$PROCESS_ID%]// eingetragen. Dieser Platzhalter wird mit der Vorgangs-ID des abgesendeten Formulars ersetzt. Im Regelfall braucht dies nicht geändert zu werden. Es sollte beachtet werden, dass die Postkorbschnittstelle bestimmte Zeichen wie Leerzeichen nicht in der externen ID erlaubt. Diese Einstellung entspricht dem Wert nach dem Doppelpunkt des Parameters //extern.id// der Postkorbschnittstelle.

88

; Name des Vorgangs im Postkorb

89

: Der Name, der im Postkorb für den Vorgang angezeigt wird. Nur verfügbar, wenn ein neuer Vorgang erstellt wird. Dieser Name wird etwa auch in der Übersicht aller Vorgänge angezeigt. Als Standard ist hier der Wert //[%$PROJECT_NAME%] - [%$PROCESS_ID%]// eingetragen. Diese Platzhalter werden durch den Namen des Formulars und die Vorgangs-ID ersetzt, sodass Namen wie //Anmeldeformular - 7581f9c5-0ba9-4b9a-b7c1-cfb475eabafd// erzeugt werden. Zur Erhöhung der Lesbarkeit kann statt der Prozess-ID etwa die E-Mail des Benutzers etc. verwendet werden. Diese Einstellung entspricht dem Wert nach dem Doppelpunkt des Parameters //extern.titel// der Postkorbschnittstelle.

90

; Link (URL) für den Vorgang im Postkorb

91

: Eine optionale URL auf den Vorgang im Drittsystem (also {{formcycle/}}). Nur verfügbar, wenn ein neuer Vorgang erstellt wird. Hier ist standardmäßig der Platzhalter //[%$FORM_PROCESS_LINK%]// eingetragen, welcher durch den Link auf das abgesendete Formular ersetzt wird. Diese Einstellung entspricht dem Wert nach dem Doppelpunkt des Parameters //extern.url// der Postkorbschnittstelle.

92

; Beschreibung des Vorgangs im Postkorb

93

: Eine optionale Beschreibung für den Vorgang im Postkorb. Nur verfügbar, wenn ein neuer Vorgang erstellt wird. Diese Einstellung entspricht dem Wert nach dem Doppelpunkt des Parameters //fall.info// der Postkorbschnittstelle.

94

95

==== Überschreiben der globalen Plugin-Konfiguration ====

96

97

; Aktion bei Fehler mit Exception abbrechen

98

: Steuert, was bei einem Fehler passiert, also wenn die Nachricht nicht an den Postkorb gesendet werden konnte. Wenn diese Option aktiviert ist, wird ein Fehler geworfen, wodurch die weitere Verarbeitung abgebrochen und dem Nutzer eine Fehlerseite angezeigt wird. Weiterhin kann dann über die [[Fehlerbehandlung>>doc:Formcycle.Designer.Workflow.ErrorHandling]] in der Status- und Aktionsverarbeitung geändert werden, was genau im Fehlerfall passieren soll. Ist andererseits diese Option deaktiviert, ist die Postkorb-Aktion immer erfolgreich und liefert bei Fehlern einen entsprechenden Statuscode (siehe unten) zurück. Über [[Abarbeitungsbedingungen>>doc:Formcycle.Designer.Workflow.LegacyWorkflow.ActionConditions]] und Aktionsplatzhalter kann dann der Statuscode entsprechend abgefragt werden.

99

; ID der Dienstleistung aus BIS

100

: Hier kann die globale Einstellung aus der Plugin-Konfiguration überschrieben werden, falls dies notwendig ist. Siehe //ID der Dienstleistung aus BIS// im Abschnitt //Konfiguration des Plugins// oben für mehr Informationen.

101

; Präfix für ID des Vorgangs im Postkorb

102

: Hier kann die globale Einstellung aus der Plugin-Konfiguration überschrieben werden, falls dies notwendig ist. Siehe //ID der Dienstleistung aus BIS// im Abschnitt //Präfix für die ID des Vorgangs im Postkorb// oben für mehr Informationen.

103

104

Schließlich kann auch die Erreichbarkeit der Postkorbschnittstelle geprüft werden. Hierbei werden nur die Daten aus der globalen Plugin-Konfiguration geprüft, nicht, ob die Daten in dieser Aktion korrekt sind. Technisch handelt es sich dabei um ein sogenannten //PING//-Request an die Postkorbschnittstelle.

105

106

=== Rückgabewerte ===

107

108

Nachdem das Aktions-Plugin ausgeführt wurde, stehen folgende zusätzliche Aktionsplatzhalter zur Verfügung:

109

110

; success

111

: //true//, falls die Nachricht erfolgreich an der Postkorb versendet werden konnte, andernfalls //false//.

112

; status

113

: Der durch die Postkorbschnittstelle zurückgelieferte Status, entweder //SUCCESS// oder //ERROR//.

114

; messageThreadId

115

: Falls ein neuer Vorgang im Postkorb angelegt wurde: Die ID des angelegten Vorgangs, wie diese von der Postkorbschnittstelle zurückgeliefert wurde.

116

; errorCode

117

: Ein von diesem Plugin definierter, nummerischer Fehlercode. Eine Liste von Fehlercodes findet sich nachfolgend.

118

; errorType

119

: Technischer Name des Fehlercodes, siehe die nachfolgende Liste.

120

; errorDetails

121

: Lokalisierte Nachricht des Fehlercodes.

122

; exceptionMessage

123

: Inhalt der durch Java geworfenen Exception.

=== Statuscodes ===

Folgende Fehlercodes werden aktuell durch dieses Plugin definiert:

128

129

130

|=Statuscode|=Technischer Name|=Beschreibung

131

|0|SERVICE_COULD_NOT_BE_CREATED|Die Verbindung zur Postkorbschnittstelle konnte nicht aufgebaut werden.

132

|10|PING_REQUEST_FAILED|Die PING-Anfrage vor der eigentlichen Anfrage ist fehlgeschlagen (falls dies in der Konfiguration aktiviert wurde).

133

|20|INVALID_SERVICE_REQUEST|Die Anfrage an die Postkorbschnittstelle enthält ungültige Daten und kann deshalb nicht versendet werden. Die Konfiguration des Plugins und der Verarbeitungsaktion sollte überprüft werden.

134

|30|POSTKORB_SERVICE_ERROR|Der Webservice hat auf die gestellte Anfrage keine Antwort zurückgeliefert. Es sollte die Verfügbarkeit der Postkorbschnittstelle geprüft werden und ob diese durch den FORMCYCLE-Server erreichbar ist.

135

|40|INVALID_SERVICE_RESPONSE|Die von der Postkorbschnittstelle zurückgelieferte Antwort enhtält ungültige Daten und kann daher nicht verarbeitet werden. Es sollte die Version der Postkorbschnittstelle geprüft werden, gegebenenfalls muss dieses Plugin aktualisiert werden.

136

|50|SERVICE_REQUEST_FAILED|Die Postkorbschnittstelle hat zwar eine Antwort zurückgeliefert, aber die hat den Status ERROR.

137

|200|INTERNAL_ERROR|Ein unvorhergesehener, nicht weiter spezifierbarer Fehler ist aufgetreten.

138

139

140

== Konfiguration des Plugins ==

141

142

143

Hinweis zum [[Logging>>doc:Formcycle.SystemSettings.UserInterface.Logging]]: Das Logging von diesem Plugin kann über die Package-Pfade //de.xima.fc.plugin.regioit.postkorb// und //de.xima.fc.plugin.utils// gesteuert werden.

144

145

146

{{figure image="plugin_regioit_postkorb_settings_de.png" width="600"}}

147

Konfiguration des Postkorb-Plugins. Erforderlich sind nur die URL zur Postkorbschnittstelle sowie Benutzername, Passwort und die Service-ID. Weitere Einstellungen zu Proxy-Server und Zertifikaten sind optional.

148

149

150

Nach dem das Plugin installiert wurde, muss hier die URL auf die Postkorbschnittstelle sowie Nutzername und Passwort eingetragen werden. Weitere Einstellungen zu Proxy-Servern und SSL-Zertifikaten sind optional und nur notwendig, falls ein Proxy-Server benutzt wird beziehungsweise Zertifikate genutzt werden, die nicht im Java-Truststore enthalten sind. Bei allen Einstellungen erscheint ein Tooltip, wenn man mit der Maus darüber fährt.

151

152

Die Konfiguration gliedert sich in die folgenden fünf Abschnitte.

153

154

=== Verbindungseinstellungen ===

155

156

Diese Einstellung sind notwendig, damit eine Verbindung zur Postkorbschnittstelle aufgebaut werden kann. In der Regel werden diese Informationen von der regio iT mitgeteilt.

157

158

; Endpunkt-URL für Postkorbschnittstelle

159

: Hier wird die URL zur Postkorbschnittstelle eingetragen. Es ist zu beachten, dass hier nicht die URL zur WSDL-Datei eingetragen werden darf (diese endet meist auf //wsdl//).

160

; Nutzername

161

: Der Benutzername für die Verbindung zur Postkorbschnittstelle.

162

; Passwort

163

: Das Passwort für die Verbindung zur Postkorbschnittstelle.

164

; Connection timeout

165

: Verbindungszeitüberschreitung (Connection-Timeout) für das Herstellen der Verbindung zur Postkorbschnittstelle. Die Zeitdauer wird mit Einheit eingetragen, also etwa //10s//, //500ms// oder //2min//.

166

; Read timeout

167

: Lesezeitüberschreitung (Read-Timeout) für das Auslesen einer Methode der Postkorbschnittstelle. Die Zeitdauer wird mit Einheit eingetragen, also etwa //10s//, //500ms// oder //2min//.

168

; Vorher immer PING durchführen

169

: Entweder //true// oder //false//. In der Spezifikation der Postkorbschnittstelle wird empfohlen, vor jeder Anfrage eine sogenannte PING-Anfrage durchzuführen, um die Verfügbarkeit der Schnittstelle zu prüfen. In der Regel kann diese Einstellung aber deaktiviert werden.

170

171

=== Standardeinstellung für Anfragen ===

172

173

Diese Einstellungen betreffen grundlegende Daten, die bei jeder Anfrage an die Postkorbschnittstelle mitgesendet werden müssen. In der Regel werden diese Informationen von der regio iT mitgeteilt.

174

175

; ID der Dienstleistung aus BIS

176

: Das Dienstleistungs-ID, welche benutzt wird, um neue Nachrichten im Postkorb zu erstellen. Dies ist in der Regel eine 5-stellige Zahl. Meist sollte diese Einstellung für das gesamte System gleich sein, bei Bedarf kann diese Einstellung aber pro Workflow-Aktion auch überschrieben werden. Diese Einstellung entspricht dem Parameter //fall.dienstleistung// der Postkorbschnittstelle.

177

; Präfix für die ID des Vorgangs im Postkorb

178

: Das Präfix wird als erster Teil der ID (vor dem Doppelpunkt) des externen Fachverfahrens verwendet. Meist sollte diese Einstellung für das gesamte System gleich sein, bei Bedarf kann diese Einstellung aber pro Workflow-Aktion auch überschrieben werden. Diese Einstellung entspricht dem ersten Teil des Parameters //extern.id// der Postkorbschnittstelle.

179

180

=== TLS/SSL-Einstellungen ===

181

182

Diese Einstellungen sind nur erforderlich, falls der Server der Postkorbschnittstelle Zertifikate verwendet, die nicht auf dem FORMCYCLE-Server beziehungsweise im Java-Truststore vorhanden sind.

183

184

; Zusätzliches Zertifikat für TLS/SSL (Mandantdatei)

185

: Der Name einer [[Mandantdatei>>doc:Formcycle.UserInterface.FilesAndTemplates.WebHome]] mit einem gültigen X509-Zertifikat.

186

; Passwort für das Zertifikat

187

: Das Passwort, um das angegebene Zertifikat öffnen zu können.

188

189

=== HTTP-Basic-Auth-Einstellungen ===

190

191

Diese Einstellungen sind nur erforderlich, falls der Server der Postkorbschnittstelle eine HTTP-Basic-Authentication erfordert.

192

193

; Nutzername für HTTP-Basic-Auth

194

: Der zu benutzende Benutzername für HTTP-Basic-Auth.

195

; Passwort für HTTP-Basic-Auth

196

: Das zu benutzende Passwort für HTTP-Basic-Auth.

197

198

=== Proxy-Server-Einstellungen ===

199

200

Diese Einstellungen sind nur erforderlich, falls der FORMCYLE-Server einen Proxy-Server benötigt, um sich mit der Postkorbschnittstelle verbinden zu können.

201

202

; URL des Proxy-Servers

203

: Die URL des Proxy-Servers.

204

; Port des Proxy-Servers

205

: Der Port des Proxy-Servers.

206

; Nutzername für Proxy-Server

207