regio iT: Postkorb plugin - FORMCYCLE Wiki

author	version	line-number	content
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"]] (requires login)
2
3	{{info}}
4	The section regarding the plugin configuration is required only for administrators who need to configure the Postkorb web service. See the //Postkorb action// section on how to send a message to the Postkorb.
5	{{/info}}
6
7	{{info}}
8	The Postkorb ("inbox") is a feature offered by the service portal. The Postkorb consists of so-called processes or message threads. Each message thread contains one more messages. This plugin lets you send message to an existing message thread from {{formcycle/}}. You can also create new message threads with an initial message.
9	{{/info}}
10
11	{{content/}}
12
13	This plugin implements the Porstkorb web service provided by regio iT. It adds a new [[workflow action>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.Actions.WebHome]] that lets you send messages to the Postkorb of the [[service portal>>https://servicekonto.nrw/]]. This plugin is subject to additional charge.
14
15	You can install this plugin both as a system plugin as well as a client plugin. Once the plugin is installed, you (or an administrator) needs to configure the connection to the Postkorb web service. Once it is configured, you can start using the Postkorb workflow action.
16
17	== Postkorb action ==
18
19	{{figure image="plugin_regioit_postkorb_workflow_select_action_en.png" width="400"}}
20	Click on //New action// to add a new Postkorb action to the workflow.
21	{{/figure}}
22
23	{{figure image="plugin_regioit_postkorb_workflow_action_base_en.png" width="400"}}
24	Basic settings for sending a message to a Postkorb message thread. Here you can the recipient and the content of the message.
25	{{/figure}}
26
27	{{figure image="plugin_regioit_postkorb_workflow_action_advanced_en.png" width="400"}}
28	Advanced settings for sending a messag to a Postkorb message thread. Here you can change the metadata of the Postkorb message thread that is created.
29	{{/figure}}
30
31	{{figure image="plugin_regioit_postkorb_workflow_action_guest_en.png" width="400"}}
32	You can also create a new message thread as a guest. This requires you to enter a few details about the guest, such as the name and email address. Please note that creating message threads as guests may be restricted by the web service - please contact your service provider for details.
33	{{/figure}}
34
35	Once the plugin is configured correctly, you can select the new workflow action //Create Postkorb message// in the workflow configuration.
36
37	=== Configuration ===
38
39	The configuration for the Postkorb action is similar to the email action and separated into 4 sections. Most settings have a default set that you do not need to change normally - usually you just have to enter a subject and message text.
40
41	Most settings allow the use of [[variables>>doc:Formcycle.UserInterface.Variables]] to insert data from the submitted form. All settings that allow variables have a little book icon next to them that opens the variable selection dialog.
42
43	In order to send am message to the Postkorb, a few pieces of information about the recipient are required, such as their account number and name. We recommend that you allow users to sign in via the services provided by regio iT (OpenID Connect). This lets you prefill the settings with the data from the registered user via [[variables>>doc:Formcycle.UserInterface.Variables]].
44
45	==== Message type and recipient ====
46
47	; Message type
48	: The Postkorb service offers two possibilies: You can (a) create a new message thread with an initial message, or (b) send a message to an existing message thread. In case you know for certain whether a message thread exists already, you can select the option //Create new message thread// or //Reply to existing message thread//. Otherwise, if you are uncertain and would like to create a new message thread in case none exists yet, you can select the option //Create message thread if none exists yet//
49	; Recipient account number
50	: Here you need to enter the account number of the recipient who should receive the Postkorb message. Usually the user would sign in via the login service provided by regio iT (OpenID Connect). In that case, you do not have to change the default value: //[%$user.userName%//] This is a [[variable>>doc:Formcycle.UserInterface.Variables]] that is replace with the account number of the user who submitted the form. This setting corresponds to the parameter //fall.portalkonto// of the Postkorb web service.
51	; Send as guest
52	: The Postkorb also allows you to create a new message thread as a guest, that is, without having an account number. Please note that it is not possible to reply to existing message threads as a guest. When this option is selected, a few more input fields will show up that let you enter the guests' data. Important: Please check with your Postkorb service provider whether they have allowed guests to create message threads.
53
54	The following input fields are available when the option //Send as guest// is checked:
55
56	; Guest' email
57	: The email of the guest. This setting corresponds the the parameter //gast.email// of the Postkorb web service.
58	; Guest's form of address
59	: An optional form of address for the guest. Please note that only certain options such as //Herr// and //Frau// are supported. This setting corresponds the the parameter //gast.anrede// of the Postkorb web service.
60	; Guest's title
61	: An optional title for the guest, such as //Dr. med.//. This setting corresponds the the parameter //gast.titel// of the Postkorb web service.
62	; Guest's first name
63	: The first or given name of the guest. This setting corresponds the the parameter //gast.vorname// of the Postkorb web service.
64	; Guest's family name
65	: The last of family name of the guest. This setting corresponds the the parameter //gast.familienname// of the Postkorb web service.
66
67	==== Message content ====
68
69	The content of the message that is sent to the Postkorb. Optionally you can also send up to 10 files as an attachment. Please note that the Postkorb web service does not support more than 10 files.
70
71	; Sender
72	: The name of the message' sender. By default this is set to the variable //[%user.displayName%]//, which is replaced with the name of the user who submitted the form. This setting corresponds the the parameter //nachricht.absender// of the Postkorb web service.
73	; Subject
74	: A single line of text with the subject of the message. This setting corresponds the the parameter //nachricht.betreff// of the Postkorb web service.
75	; Message
76	: The message that is sent to the Postkorb. A few formating options such as bold text and lists are supported by Postkorb. This setting corresponds the the parameter //nachricht.inhalt// of the Postkorb web service.
77	; Attachments from previous actions
78	: Optionally you can also add files produced by previous actions as an attachment. This setting corresponds the the parameters //anhang.[1-10].*// of the Postkorb web service.
79	; Attachments from form uploads
80	: Optionaly you can also add files uploaded by the user as an attachment. This setting corresponds the the parameters //anhang.[1-10].*// of the Postkorb web service.
81
82	==== Postkorb message thread ====
83
84	; New message thread state
85	: You can optionallt change the status of the message thread. The available status, as defined by the Postkorb, are //open//, //in progress//, //settled// and //canceled//. The default settings does not change the status (new message threads are automatically set to //open//). Please note that the two status //in progress// und //canceled// are available only when repying to an existing message thread, not when creating a new messag e thread. This setting corresponds the the parameter //fall.status// of the Postkorb web service.
86	; Message thread external ID
87	: The external ID of the message thread. Each message thread receives an internal ID used by the Postkorb service internally, as well as an external ID that identifies the form record in {{formcycle/}}. The default settings is //[%$PROCESS_ID%]//. This variable is replace with the form record ID of the {{formcycle/}} form record - this should be sufficient for most use cases. In case you want to use a different external ID, please note that the Postkorb does not allow certain characters such as spaces. This setting corresponds the the parameter //extern.id// of the Postkorb web service.
88	; Message thread name
89	: The name that is shown in the Postkorb for the message thread. This name is also shown in the list of existing message threads. This setting is available only when creating a new message thread. By default this is set to //[%$PROJECT_NAME%] - [%$PROCESS_ID%]//. These variables are replaced with the name of the form and ID of the form record, respectively, which results in message thread names such as //Registration form - 7581f9c5-0ba9-4b9a-b7c1-cfb475eabafd//. To make it easier to identify a message thread in the Postkorb, consider using other data submitted by the user, such as their email address. This setting corresponds the the parameter //extern.titel// of the Postkorb web service.
90	; Message thread link
91	: An optional URL that is shown in the Postkorb. This setting is available only when a new message thread is created. Defaults to //[%$FORM_PROCESS_LINK%]//, which is replaced with the link to the submitted form. This setting corresponds the the parameter //extern.url// of the Postkorb web service.
92	; Message thread description
93	: An optional description for the message thread. This setting is available only when creating a new message thread. This setting corresponds the the parameter //fall.info// of the Postkorb web service.
94
95	==== Global plugin configuration overrides ====
96
97	; Throw hard exception if action fails
98	: Controls the behavior when the workflow action fails, i.e. when the message could not be sent to the Postkorb. When this option is activated, an exception is thrown, which aborts the workflow processing and returns an error page to the user. You can use the [[error handling settings>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.ErrorHandling]] to control that behavior. Otherwise, when this option is deactivated, the Postkorb action is always successful and return an appropriate status code that indicates whether the message could be sent (see below). In that case you can use [[workflow conditions>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.ActionConditions]] in combination with action result variables to check the status code and act accordingly.
99	; Service ID (BIS)
100	: Lets you override the global value configured in the plugin settings, if neccessary. See the //Service ID (BIS)// option in the plugin configuration for more details.
101	; Message thread ID prefix
102	: Lets you override the global value configured in the plugin settings, if neccessary. See the //Message thread ID prefix// option in the plugin configuration for more details.
103
104	Finally, you can also check the availability of the Postkorb service. This only checks the connection details as configured in the plugin settings, not whether the data configured for this Postkorb action is valid. Technically speaking, this sends a so-called //PING// service request to the Postkorb web service.
105
106	=== Return values ===
107
108	After the plugin action was executed, the following additional [[action variables>>doc:Formcycle.UserInterface.Variables]] are available:
109
110	; success
111	: //true// if the message could be sent to the Postkorb, //false// otherwise.
112	; status
113	: The status code as returned by the Postkorb web service, either //SUCCESS// or //ERROR//.
114	; messageThreadId
115	: If the request was successful and a new message thread was created: The ID of the newly created message thread, as returned by the Postkorb web service.
116	; errorCode
117	: A numerical error code defined by this plugin. See the following list for the available codes.
118	; errorType
119	: Technical name of the error code, see below.
120	; errorDetails
121	: Localized name of the error code.
122	; exceptionMessage
123	: Message of the exception that was thrown by Java, if any.
124
125	=== Error codes ===
126
127	The following error codes are currently defined by this plugin:
128
129	{{table dataTypeAlpha="1" dataTypeNum="0" preSort="0-asc"}}
130	\|=Status code\|=Technical name\|=Description
131	\|0\|SERVICE_COULD_NOT_BE_CREATED\|The connection to the Postkorb web service could not be established.
132	\|10\|PING_REQUEST_FAILED\|The PING request preceding the actual request failed (only if enabled in the configuration).
133	\|20\|INVALID_SERVICE_REQUEST\|The request to the Postkorb web service contains invalid data and cannot be sent. Check the configuration of the plugin and the workflow action.
134	\|30\|POSTKORB_SERVICE_ERROR\|The Postkorb web service did not return any response to the request. Check whether the web service is available and can be reached from your network.
135	\|40\|INVALID_SERVICE_RESPONSE\|The response returned by the Postkorb web service is invalid and could not be parsed. Check the version of the web service and this plugin, you may have to update this plugin.
136	\|50\|SERVICE_REQUEST_FAILED\|The Postkorb web service returned a response, but the status of that response was //ERROR//.
137	\|200\|INTERNAL_ERROR\|A unexpected error occurred that cannot be specified further.
138	{{/table}}
139
140	== Plugin configuration ==
141
142	{{info}}
143	A note on [[logging>>doc:Formcycle.SystemSettings.UserInterface.Logging]]: You can control the logging messages of this plugin via the package paths //de.xima.fc.plugin.regioit.postkorb// and //de.xima.fc.plugin.utils//.
144	{{/info}}
145
146	{{figure image="plugin_regioit_postkorb_settings_en.png" width="600"}}
147	Configuration of the Postkorb plugin. Required are only the URL to the web service as well as the username, password and service ID. Additional settings regarding the proxy server and SSL certificates are optional.
148	{{/figure}}
149
150	Before you can use this plugin, you need to configure the connection to the Postkorb web service. This includes the endpoint URL, the username and password, as well as the service ID. There are some additional settings available that are optional, such as proxy server and SSL settings. If the web service can be reached without a proxy and if it does not use non-standard certificates that are not in the default system or Java trust store, you can leave these settings empty.
151
152	The configuration is split into five section. Hover over the name of a setting to see a tooltip.
153
154	=== Connection configuration ===
155
156	These settings are required in order to establish a connection to the web service. You should have received these settings from your Postkorb provider.
157
158	; Endpoint URL for the Postkorb service
159	: This the URL to the Postkorb SOAP web service. Please note that you should not enter the URL to the WSDL file here which usually ends on //wsdl//.
160	; Username
161	: The username for authenticating against the Postkorb web service.
162	; Password
163	: The password for authenticating against the Postkorb web service.
164	; Connection timeout
165	: Connection timeout, i.e. the maximum time allowed for establishing a HTTP connection. You should enter the duration with a unit, such //10 s//, //500 ms// oder //2 min//.
166	; Read timeout
167	: The read timeout, i.e. the maximum amount of time to spend waiting for a response from the web service. You should enter the duration with a unit, such //10 s//, //500 ms// oder //2 min//.
168	; Always send a PING request first
169	: Either //true// or //false//. The specification of the Postkorb service recommends that a PING is sent before each request, to check the availability of the web service. Usually you can turn this off.
170
171	=== Default request settings ===
172
173	Each request to the Postkorb web service must include certain data, such as the service ID. Here you can set a system-wide default for these settings. If required, they can be overwritten by an individual workflow action. You should have received this information from your Postkob service provider.
174
175	; Service ID (BIS)
176	: The service ID used for sending messages to the Postkorb. Usually this is a number with 5 digits. This setting applies globally, but can be overwritten by an individual workflow action if neccessary. This setting corresponds to the parameter //fall.dienstleistung// of the Postkorb web service.
177	; Message thread ID prefix
178	: The prefix is used as the first part of the external ID, i.e. the part before the colon. This setting applies globally, but can be overwritten by an individual workflow action if neccessary. This settings corresponds to the parameter //extern.id// of the Postkorb service.
179
180	=== TLS/SSL configuration ===
181
182	These settings are required only if the Postkorb web server uses non-standard certificates that are not known by the FORMCYCLE server or the Java trust store.
183
184	; Additional certificate for TLS/SSL (client file)
185	: The name of a [[client file>>doc:Formcycle.UserInterface.FilesAndTemplates.WebHome]] with a valid X509 certificate.
186	; Password for the certificate
187	: The password for opening the certificate
188
189	=== HTTP basic authorization configuration ===
190
191	These settings are required only if the Postkorb web server requires an HTTP basic authorization.
192
193	; Username for HTTP basic auth
194	: The username for the HTTP basic authorization.
195	; Password for HTTP basic auth
196	: The password for the HTTP basic authorization.
197
198	=== Proxy server settings ===
199
200	These settings are required only if the FORMCYCLE server requires a proxy server to connect to the Postkorb web service.
201
202	; Proxy server URL
203	: The URL to the proxy server.
204	; Proxy server port
205	: The port of the proxy server.
206	; Proxy server username
207	: The username, if neccessary, for connecting to the proxy server
208	; Proxy server password
209	: The password, if neccessary, for connecting to the proxy server
210
211	== Changelog
212
213	This is a list of available version of this plugin and which changes took place in which version.
214
215	=== 1.0.0
216
217	* Initial release

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"]] (requires login)

2

3

4

The section regarding the plugin configuration is required only for administrators who need to configure the Postkorb web service. See the //Postkorb action// section on how to send a message to the Postkorb.

The Postkorb ("inbox") is a feature offered by the service portal. The Postkorb consists of so-called processes or message threads. Each message thread contains one more messages. This plugin lets you send message to an existing message thread from {{formcycle/}}. You can also create new message threads with an initial message.

This plugin implements the Porstkorb web service provided by regio iT. It adds a new [[workflow action>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.Actions.WebHome]] that lets you send messages to the Postkorb of the [[service portal>>https://servicekonto.nrw/]]. This plugin is subject to additional charge.

14

15

You can install this plugin both as a system plugin as well as a client plugin. Once the plugin is installed, you (or an administrator) needs to configure the connection to the Postkorb web service. Once it is configured, you can start using the Postkorb workflow action.

16

17

== Postkorb action ==

18

19

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

20

Click on //New action// to add a new Postkorb action to the workflow.

21

22

23

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

24

Basic settings for sending a message to a Postkorb message thread. Here you can the recipient and the content of the message.

25

26

27

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

28

Advanced settings for sending a messag to a Postkorb message thread. Here you can change the metadata of the Postkorb message thread that is created.

29

30

31

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

32

You can also create a new message thread as a guest. This requires you to enter a few details about the guest, such as the name and email address. Please note that creating message threads as guests may be restricted by the web service - please contact your service provider for details.

33

34

35

Once the plugin is configured correctly, you can select the new workflow action //Create Postkorb message// in the workflow configuration.

36

37

=== Configuration ===

38

39

The configuration for the Postkorb action is similar to the email action and separated into 4 sections. Most settings have a default set that you do not need to change normally - usually you just have to enter a subject and message text.

40

41

Most settings allow the use of [[variables>>doc:Formcycle.UserInterface.Variables]] to insert data from the submitted form. All settings that allow variables have a little book icon next to them that opens the variable selection dialog.

42

43

In order to send am message to the Postkorb, a few pieces of information about the recipient are required, such as their account number and name. We recommend that you allow users to sign in via the services provided by regio iT (OpenID Connect). This lets you prefill the settings with the data from the registered user via [[variables>>doc:Formcycle.UserInterface.Variables]].

44

45

==== Message type and recipient ====

46

47

; Message type

48

: The Postkorb service offers two possibilies: You can (a) create a new message thread with an initial message, or (b) send a message to an existing message thread. In case you know for certain whether a message thread exists already, you can select the option //Create new message thread// or //Reply to existing message thread//. Otherwise, if you are uncertain and would like to create a new message thread in case none exists yet, you can select the option //Create message thread if none exists yet//

49

; Recipient account number

50

: Here you need to enter the account number of the recipient who should receive the Postkorb message. Usually the user would sign in via the login service provided by regio iT (OpenID Connect). In that case, you do not have to change the default value: //[%$user.userName%//] This is a [[variable>>doc:Formcycle.UserInterface.Variables]] that is replace with the account number of the user who submitted the form. This setting corresponds to the parameter //fall.portalkonto// of the Postkorb web service.

51

; Send as guest

52

: The Postkorb also allows you to create a new message thread as a guest, that is, without having an account number. Please note that it is not possible to reply to existing message threads as a guest. When this option is selected, a few more input fields will show up that let you enter the guests' data. Important: Please check with your Postkorb service provider whether they have allowed guests to create message threads.

53

54

The following input fields are available when the option //Send as guest// is checked:

55

56

; Guest' email

57

: The email of the guest. This setting corresponds the the parameter //gast.email// of the Postkorb web service.

58

; Guest's form of address

59

: An optional form of address for the guest. Please note that only certain options such as //Herr// and //Frau// are supported. This setting corresponds the the parameter //gast.anrede// of the Postkorb web service.

60

; Guest's title

61

: An optional title for the guest, such as //Dr. med.//. This setting corresponds the the parameter //gast.titel// of the Postkorb web service.

62

; Guest's first name

63

: The first or given name of the guest. This setting corresponds the the parameter //gast.vorname// of the Postkorb web service.

64

; Guest's family name

65

: The last of family name of the guest. This setting corresponds the the parameter //gast.familienname// of the Postkorb web service.

66

67

==== Message content ====

68

69

The content of the message that is sent to the Postkorb. Optionally you can also send up to 10 files as an attachment. Please note that the Postkorb web service does not support more than 10 files.

70

71

; Sender

72

: The name of the message' sender. By default this is set to the variable //[%user.displayName%]//, which is replaced with the name of the user who submitted the form. This setting corresponds the the parameter //nachricht.absender// of the Postkorb web service.

73

; Subject

74

: A single line of text with the subject of the message. This setting corresponds the the parameter //nachricht.betreff// of the Postkorb web service.

75

; Message

76

: The message that is sent to the Postkorb. A few formating options such as bold text and lists are supported by Postkorb. This setting corresponds the the parameter //nachricht.inhalt// of the Postkorb web service.

77

; Attachments from previous actions

78

: Optionally you can also add files produced by previous actions as an attachment. This setting corresponds the the parameters //anhang.[1-10].*// of the Postkorb web service.

79

; Attachments from form uploads

80

: Optionaly you can also add files uploaded by the user as an attachment. This setting corresponds the the parameters //anhang.[1-10].*// of the Postkorb web service.

81

82

==== Postkorb message thread ====

83

84

; New message thread state

85

: You can optionallt change the status of the message thread. The available status, as defined by the Postkorb, are //open//, //in progress//, //settled// and //canceled//. The default settings does not change the status (new message threads are automatically set to //open//). Please note that the two status //in progress// und //canceled// are available only when repying to an existing message thread, not when creating a new messag e thread. This setting corresponds the the parameter //fall.status// of the Postkorb web service.

86

; Message thread external ID

87

: The external ID of the message thread. Each message thread receives an internal ID used by the Postkorb service internally, as well as an external ID that identifies the form record in {{formcycle/}}. The default settings is //[%$PROCESS_ID%]//. This variable is replace with the form record ID of the {{formcycle/}} form record - this should be sufficient for most use cases. In case you want to use a different external ID, please note that the Postkorb does not allow certain characters such as spaces. This setting corresponds the the parameter //extern.id// of the Postkorb web service.

88

; Message thread name

89

: The name that is shown in the Postkorb for the message thread. This name is also shown in the list of existing message threads. This setting is available only when creating a new message thread. By default this is set to //[%$PROJECT_NAME%] - [%$PROCESS_ID%]//. These variables are replaced with the name of the form and ID of the form record, respectively, which results in message thread names such as //Registration form - 7581f9c5-0ba9-4b9a-b7c1-cfb475eabafd//. To make it easier to identify a message thread in the Postkorb, consider using other data submitted by the user, such as their email address. This setting corresponds the the parameter //extern.titel// of the Postkorb web service.

90

; Message thread link

91

: An optional URL that is shown in the Postkorb. This setting is available only when a new message thread is created. Defaults to //[%$FORM_PROCESS_LINK%]//, which is replaced with the link to the submitted form. This setting corresponds the the parameter //extern.url// of the Postkorb web service.

92

; Message thread description

93

: An optional description for the message thread. This setting is available only when creating a new message thread. This setting corresponds the the parameter //fall.info// of the Postkorb web service.

94

95

==== Global plugin configuration overrides ====

96

97

; Throw hard exception if action fails

98

: Controls the behavior when the workflow action fails, i.e. when the message could not be sent to the Postkorb. When this option is activated, an exception is thrown, which aborts the workflow processing and returns an error page to the user. You can use the [[error handling settings>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.ErrorHandling]] to control that behavior. Otherwise, when this option is deactivated, the Postkorb action is always successful and return an appropriate status code that indicates whether the message could be sent (see below). In that case you can use [[workflow conditions>>doc:Formcycle.UserInterface.MyForms.WorkflowProcessing.ActionConditions]] in combination with action result variables to check the status code and act accordingly.

99

; Service ID (BIS)

100

: Lets you override the global value configured in the plugin settings, if neccessary. See the //Service ID (BIS)// option in the plugin configuration for more details.

101

; Message thread ID prefix

102

: Lets you override the global value configured in the plugin settings, if neccessary. See the //Message thread ID prefix// option in the plugin configuration for more details.

103

104

Finally, you can also check the availability of the Postkorb service. This only checks the connection details as configured in the plugin settings, not whether the data configured for this Postkorb action is valid. Technically speaking, this sends a so-called //PING// service request to the Postkorb web service.

105

106

=== Return values ===

107

108

After the plugin action was executed, the following additional [[action variables>>doc:Formcycle.UserInterface.Variables]] are available:

109

110

; success

111

: //true// if the message could be sent to the Postkorb, //false// otherwise.

112

; status

113

: The status code as returned by the Postkorb web service, either //SUCCESS// or //ERROR//.

114

; messageThreadId

115

: If the request was successful and a new message thread was created: The ID of the newly created message thread, as returned by the Postkorb web service.

116

; errorCode

117

: A numerical error code defined by this plugin. See the following list for the available codes.

118

; errorType

119

: Technical name of the error code, see below.

120

; errorDetails

121

: Localized name of the error code.

122

; exceptionMessage

123

: Message of the exception that was thrown by Java, if any.

=== Error codes ===

The following error codes are currently defined by this plugin:

128

129

130

|=Status code|=Technical name|=Description

131

|0|SERVICE_COULD_NOT_BE_CREATED|The connection to the Postkorb web service could not be established.

132

|10|PING_REQUEST_FAILED|The PING request preceding the actual request failed (only if enabled in the configuration).

133

|20|INVALID_SERVICE_REQUEST|The request to the Postkorb web service contains invalid data and cannot be sent. Check the configuration of the plugin and the workflow action.

134

|30|POSTKORB_SERVICE_ERROR|The Postkorb web service did not return any response to the request. Check whether the web service is available and can be reached from your network.

135

|40|INVALID_SERVICE_RESPONSE|The response returned by the Postkorb web service is invalid and could not be parsed. Check the version of the web service and this plugin, you may have to update this plugin.

136

|50|SERVICE_REQUEST_FAILED|The Postkorb web service returned a response, but the status of that response was //ERROR//.

137

|200|INTERNAL_ERROR|A unexpected error occurred that cannot be specified further.

138

139

140

== Plugin configuration ==

141

142

143

A note on [[logging>>doc:Formcycle.SystemSettings.UserInterface.Logging]]: You can control the logging messages of this plugin via the package paths //de.xima.fc.plugin.regioit.postkorb// and //de.xima.fc.plugin.utils//.

144

145

146

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

147

Configuration of the Postkorb plugin. Required are only the URL to the web service as well as the username, password and service ID. Additional settings regarding the proxy server and SSL certificates are optional.

148

149

150

Before you can use this plugin, you need to configure the connection to the Postkorb web service. This includes the endpoint URL, the username and password, as well as the service ID. There are some additional settings available that are optional, such as proxy server and SSL settings. If the web service can be reached without a proxy and if it does not use non-standard certificates that are not in the default system or Java trust store, you can leave these settings empty.

151

152

The configuration is split into five section. Hover over the name of a setting to see a tooltip.

153

154

=== Connection configuration ===

155

156

These settings are required in order to establish a connection to the web service. You should have received these settings from your Postkorb provider.

157

158

; Endpoint URL for the Postkorb service

159

: This the URL to the Postkorb SOAP web service. Please note that you **should not** enter the URL to the WSDL file here which usually ends on //wsdl//.

160

; Username

161

: The username for authenticating against the Postkorb web service.

162

; Password

163

: The password for authenticating against the Postkorb web service.

164

; Connection timeout

165

: Connection timeout, i.e. the maximum time allowed for establishing a HTTP connection. You should enter the duration with a unit, such //10 s//, //500 ms// oder //2 min//.

166

; Read timeout

167

: The read timeout, i.e. the maximum amount of time to spend waiting for a response from the web service. You should enter the duration with a unit, such //10 s//, //500 ms// oder //2 min//.

168

; Always send a PING request first

169

: Either //true// or //false//. The specification of the Postkorb service recommends that a PING is sent before each request, to check the availability of the web service. Usually you can turn this off.

170

171

=== Default request settings ===

172

173

Each request to the Postkorb web service must include certain data, such as the service ID. Here you can set a system-wide default for these settings. If required, they can be overwritten by an individual workflow action. You should have received this information from your Postkob service provider.

174

175

; Service ID (BIS)

176

: The service ID used for sending messages to the Postkorb. Usually this is a number with 5 digits. This setting applies globally, but can be overwritten by an individual workflow action if neccessary. This setting corresponds to the parameter //fall.dienstleistung// of the Postkorb web service.

177

; Message thread ID prefix

178

: The prefix is used as the first part of the external ID, i.e. the part before the colon. This setting applies globally, but can be overwritten by an individual workflow action if neccessary. This settings corresponds to the parameter //extern.id// of the Postkorb service.

179

180

=== TLS/SSL configuration ===

181

182

These settings are required only if the Postkorb web server uses non-standard certificates that are not known by the FORMCYCLE server or the Java trust store.

183

184

; Additional certificate for TLS/SSL (client file)

185

: The name of a [[client file>>doc:Formcycle.UserInterface.FilesAndTemplates.WebHome]] with a valid X509 certificate.

186

; Password for the certificate

187

: The password for opening the certificate

188

189

=== HTTP basic authorization configuration ===