This plugin implements the Porstkorb web service provided by regio iT. It adds a new workflow action that lets you send messages to the Postkorb of the service portal.

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.

Postkorb action

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

Configuration

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.

Most settings allow the use of 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.

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.

Message type and recipient

Message type

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
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.

Kontonummer des Empfängers oder Antragstellers

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: [%$last_user.preferred_username%] Dies ist ein Platzhalter, der mit der Kontonummer des angemeldeten Nutzers ersetzt wird. Diese Einstellung entspricht dem Parameter fall.portalkonto der Postkorbschnittstelle.

Als Gast versenden

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.

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

E-Mail des Gasts

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

Anrede des Gasts

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.

Titel des Gasts

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.

Vorname des Gasts

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

Nachname des Gasts

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

Inhalt der Nachricht

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.

Absendername

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

Betreff

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

Nachricht

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.

Anhänge aus vorigen Aktionen

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

Anhänge aus Formular-Uploads

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

Auswahl des Vorgangs

Neuer Status des Vorgangs im Postkorb

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.

Externe ID des Vorgangs im Postkorb

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 Xima® 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.

Name des Vorgangs im Postkorb

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.

Link (URL) für den Vorgang im Postkorb

Eine optionale URL auf den Vorgang im Drittsystem (also Xima® 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.

Beschreibung des Vorgangs im Postkorb

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.

Überschreiben der globalen Plugin-Konfiguration

Aktion bei Fehler mit Exception abbrechen

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 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 und Aktionsplatzhalter kann dann der Statuscode entsprechend abgefragt werden.

ID der Dienstleistung aus BIS

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.

Präfix für ID des Vorgangs im Postkorb

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.

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.

Konfiguration des Plugins

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.

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

Verbindungseinstellungen

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

Endpunkt-URL für Postkorbschnittstelle

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).

Nutzername

Der Benutzername für die Verbindung zur Postkorbschnittstelle.

Passwort

Das Passwort für die Verbindung zur Postkorbschnittstelle.

Connection timeout

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

Read timeout

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

Vorher immer PING durchführen

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.

Standardeinstellung für Anfragen

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.

ID der Dienstleistung aus BIS

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.

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

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.

TLS/SSL-Einstellungen

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

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

Der Name einer Mandantdatei mit einem gültigen X509-Zertifikat.

Passwort für das Zertifikat

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

HTTP-Basic-Auth-Einstellungen

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

Nutzername für HTTP-Basic-Auth

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

Passwort für HTTP-Basic-Auth

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

Proxy-Server-Einstellungen

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

URL des Proxy-Servers

Die URL des Proxy-Servers.

Port des Proxy-Servers

Der Port des Proxy-Servers.

Nutzername für Proxy-Server

Nutzername, falls nötig, um eine Verbindung zum Proxy-Server herzustellen.

Passwort für den Proxy-Server

Nutzername, falls nötig, um eine Verbindung zum Proxy-Server herzustellen.