Installation / Konfiguration FIT-Connect (ab Version 2.x)

Geändert am Do, 18 Sep um 11:54 VORMITTAGS

Achtung, diese Hilfeseite beschreibt die Konfiguration für das FIT-Connect Plugin ab Version 2.x.x. Sollten Sie eine ältere Version des FIT-Connect Plugins besitzen, so folgen Sie den Anweisungen auf dieser Seite.

INHALTSVERZEICHNIS

Initiale Installation
Update / Migration bei existenten FIT-Connect Plugin (Version < 2.0.0)
FIT-Connect Verbindungen

Das lizenzpflichtige FIT-Connect Plugin ist dafür vorgesehen, Antragsdaten aus Formularen an ein zuständiges Fachverfahren zu übertragen. Die Datenübertragung zwischen den verschiedenen Komponenten erfolgt dabei verschlüsselt.

Initiale Installation

Das FIT-Connect Plugin muss im Systembereich von formcycle installiert werden. (Menüpunkt: System > Systemplugins)

Für den Betrieb der FIT-Connect Plugin Version >= 2.x.x wird mindestens formcycle in Version >= 8.3.x benötigt.

Update / Migration bei existenten FIT-Connect Plugin (Version < 2.0.0)

Wenn bereits eine ältere FIT-Connect Plugin-Version im Systembereich installiert ist, so kann diese einfach aktualisiert werden. Dabei werden die aktuell am Plugin (unter Eigenschaften) enthaltenen Einstellungen verwendet, um damit eine neue FIT-Connect Onlinedienst Verbindung zu erstellen.

Anschließend wird an den zugehörigen FIT-Connect Workflow-Aktionen eine Referenz auf diese neue Verbindung hinterlegt.

Werden an einer Workflow-Aktion Verbindungsdaten übersteuert, so wird auf Grundlage dieser Übersteuerungsdaten eine zusätzliche FIT-Connect Onlinedienst Verbindung erstellt und der Workflow-Aktion zugeordnet.

FIT-Connect Verbindungen

Anbindungen an FIT-Connect werden über den Menüpunkt FIT-Connect Verbindungen gepflegt. Dieser ist unter Systemeinstellungen aufgeführt.

Hinweis: Sollte der Menüpunkt FIT-Connect Verbindungen nicht sofort ersichtlich sein, ist ein Ab- und wieder Anmelden als sadmin notwendig.

Freischaltung im Mandanten

Im jeweiligen Mandanten lassen sich die FIT-Connect Verbindungen ebenfalls pflegen. Damit ein Mandant(Admin)-Nutzer Zugriff auf den Menüpunkt erhält muss dieser zuvor per Rollen-Berechtigung zugeordnet werden:

Freigabe der FIT-Connect Verbindungen in einem Mandanten per Rollen-Zuordnung

Verbindung zu FIT-Connect Onlinediensten

FIT-Connect Onlinedienste fungieren als Sende-Komponenten und ermöglichen es verschlüsselte Daten aus dem formcycle-System an FIT-Connect zu übermitteln.

Damit das Senden von Daten aus dem Workflow heraus ermöglicht werden kann, muss zuvor eine Onlinedienst Verbindung zu FIT-Connect konfiguriert werden. Dies ist sowohl im System-Bereich (das steht diese Verbindung in allen Mandanten zur Verfügung) als auch im Mandant-Bereich (diese Verbindungen können nur im jeweiligen Mandanten genutzt werden) möglich.

Eine neue Verbindung lässt sich über dasSymbol anlegen.
Bestehende Verbindungen können, in dem Bereich (System oder Mandant) in dem sie angelegt wurden, über dasSymbol wieder gelöscht werden. Das Symbol erscheint, wenn man die entsprechende Verbindung in der Auflistung auswählt.

Die Oberfläche zur Anbindung eines FIT-Connect Onlinedienstes ist in einzelne Bereiche aufgeteilt, die in den nachfolgenden Abschnitten beschrieben werden.

FIT-Connect Schnittstelle

Im Bereich der FIT-Connect Schnittstelle werden die allgemeinen Verbindungsdaten zu einem FIT-Connect Onlinedienst erfasst. Hierfür benötigen Sie ihre Verbindungsdaten aus dem FITKO Self Service Portal.

Allgemeine Einstellungen zur Anbindung eines FIT-Connect Onlinedienstes

FIT-Connect Zugangstyp (Pflicht): Hier muss Onlinedienst (sendendes System) ausgewählt werden.
Name (Pflicht): (Sprechender) Name für die Anbindung. Der Name wird an allen Stellen als Auswahloption angezeigt, wo eine Zuordnung zu einer konkreten Onlinedienst-Anbindung notwendig ist (z.B. in Workflow-Aktionen).
Umgebung (Pflicht): Definiert die anzubindende FIT-Connect Umgebung. Folgende Werte werden unterstützt: TEST, PROD, STAGE
Client-ID (Pflicht): Client-ID aus dem FITKO Self Service Portal (SSP). Muss zum hinterlegten Client-Secret passen.
Client-Secret (Pflicht): Client-Secret aus dem FITKO SSP. Muss zur hinterlegten Client-ID passen.
Beschreibung (Optional): Nähere Beschreibung zur konkret genutzten FIT-Connect Verbindung.

Proxy-Einstellungen

Verbindungen zu FIT-Connect werden immer vom formcycle Master-Server aus aufgebaut. Dafür muss eine Verbindung vom Master-Server über das Internet zum jeweiligen FIT-Connect Dienst aufgebaut werden können.

Falls die Verbindungskommunikation einen Proxy-Server benötigt, kann an dieser Stelle eine entsprechende Konfiguration hinterlegt werden.

Einstellungsmöglichkeiten für Einbindung eines Proxy-Servers

Proxy verwenden (Optinal): Schaltet bei Aktivierung die weiteren Proxy-Server Anbindungseinstellungen frei.
Host (Pflicht, wenn Proxy verwenden aktiv): Host-Name oder IP-Adresse eines Proxy-Servers, welcher für die Kommunikation zu FIT-Connect genutzt werden soll.
Port (Pflicht, wenn Proxy verwenden aktiv): Portangabe (Zahl) für die Kommunikation über eine Proxy-Server.
Username (optional): Basic-Auth Login zur Authentifizierung an einem Proxy-Server.
Passwort (optional): Basic-Auth Passwort zur Authentifizierung an einem Proxy-Server.

Erweiterte Einstellungen

In dem Bereich Erweiterte Einstellungen sind alle zusätzlichen Optionen zusammengefasst, welche durch FIT-Connect beim Verbindungsaufbau und der Kommunikation zwischen FIT-Connect und formcycle unterstützt werden.

Im Einzelnen sind dies:

Konfiguration von Verbindungs-Timeouts
Prüfung / Validierung der eingesetzten Zertifikaten / Daten-Schemen
Einstellungen zum Handling von großen Anhängen
Zustellversuche bei kurzfristiger Systemunerreichbarkeit

Erweitere Einstellungen

Konfiguration Verbindungs-Timeouts

Connection-Timeout (in Sekunden) (Pflicht): Beschreibt den Zeitraum, wie lange für einen Verbindungsaufbau über die FIT-Connect Schnittstelle gewartet wird. Unterstützt wird ein Wert > 0 (Standardwert ist 30).
Read-Timeout (in Sekunden) (Pflicht): Beschreibt den Zeitraum, wie lange auf eine Antwort der FIT-Connect Schnittstelle gewartet wird. Unterstützt wird ein Wert > 0 (Standardwert ist 30)

Zusätzliche Einstellungen für genutzte FIT-Connect Umgebung

Self-Signed-Zertifikate erlauben?: Erlaubt die Benutzung von Self-Signed-Zertifikaten für Testzwecke (wenn aktiviert).

Achtung: Bei Anbindung des FIT-Connect Test-Systems und der Verwendung von selbst signierten Zertifikaten muss diese Option aktiviert sein, damit die Verbindung zu FIT-Connect aufgebaut werden kann.

Validierung gegen Schema-URL überspringen?: Aktiviert oder Deaktiviert die Validierung der Fachdaten gegen die in der Einreichung (Submission) angegebene Schema-URI.

Konfiguration zur Übertragung großer Attachments (Chunking)

Soll Chunking auf alle Attachmenttypen angewandt werden?: Definiert, ob ein Chunking für alle Attachment-Typen (Large oder In-Memory) angewendet werden soll. Standardmäßig findet das Chunking bei In-Memory Attachment-Typen keine Anwendung.
Max. Größe eines Fragments (in MB): Angabe der Größe eines einzelnen Attachment-Fragments in MByte (Standardwert: 50, Maximal-Wert: 350)

Einstellungen für Zustellversuche

Wiederholung bei Zustellproblemen erlauben?: Definiert ob bei Serviceantworten mit den HTTP-Statuscodes 408, 429, 500, 502, 503 oder 504 eine Zustellwiederholung initiiert werden soll.
Anzahl der Zustellversuche (Pflicht, wenn Wiederholung bei Zustellproblemen erlauben? aktiviert ist): Definiert die Anzahl der Zustellversuche bei fehlgeschlagener Datenübermittlung an FIT-Connect. (Standardwert: 3)
Initiale Wartezeit (in Sekunden) (Pflicht, wenn Wiederholung bei Zustellproblemen erlauben? aktiviert ist): Initiale Wartezeit (in Sekunden) bis zum Start der Sende-Wiederholversuche.

Übersicht der aktuellen Anbindungsnutzung

In der Übersicht werden alle Workflow-Aktionen vermerkt, welche die aktuelle Anbindung verwenden. Sie werden dabei nach Mandant und Formularprojekt aufgeschlüsselt.

Wird die Übersicht im Mandanten aufgerufen, so sind die Namen der Workflow-Aktionen verlinkt und man kann direkt auf das jeweilige Formular über den Workflow-Designer zugreifen.

Übersicht zur aktuellen Anbindungsverwendung

Die Übersicht kann auch als Entscheidungshilfe dienen, wenn man eine Verbindung löschen möchte. Hier lässt sich im Vorfeld prüfen ob und wo die Verbindung noch Verwendung findet.

Verbindung zu FIT-Connect Verwaltungssystemen

FIT-Connect Verwaltungssysteme fungieren als Empfänger-Komponenten und ermöglichen es verschlüsselte Daten aus FIT-Connect abzurufen, zu entschlüsseln und somit für eine weitere Verarbeitung im formcycle-System zur Verfügung zu stellen.

Achtung: Anbindungen an FIT-Connect Verwaltungssysteme lassen sich nur im Bereich eines Mandanten definieren.

FIT-Connect Schnittstelle

Im Bereich der FIT-Connect Schnittstelle werden die allgemeinen Verbindungsdaten zu einem FIT-Connect Verwaltungssystem erfasst. Hierfür benötigen Sie ihre Verbindungsdaten aus dem FITKO Self Service Portal.

Die Daten, welche hier konfiguriert werden, sind analog zu den Daten für die Anbindung eines Onlinedienstes - Bereich: FIT-Connect Schnittstelle - und unterscheiden sich nur in folgenden Punkt:

FIT-Connect Zugangstyp (Pflicht): Hier muss Verwaltungssystem (empfangendes System) ausgewählt werden.

Proxy-Einstellungen

Falls die Verbindungskommunikation einen Proxy-Server benötigt, kann an dieser Stelle eine entsprechende Konfiguration hinterlegt werden.

Die zu konfigurierenden Daten sind analog zu den Daten für die Anbindung eines Onlinedienstes - Bereich: Proxy-Einstellungen.

Angebundene Zustellpunkte

In diesem Abschnitt werden die an einem FIT-Connect Verwaltungssystem zugordneten Zustellpunkte verwaltet.

Dazu müssen im ersten Schritt die Zustellpunkte vom Verwaltungssystem aus dem FIT-Connect Portal ermittelt werden.

Über den Button lassen sich die Zustellpunkte von einem Verwaltungssystem abrufen. Damit dies fehlerfrei funktioniert, muss zuvor die Verbindung zum Verwaltungssystem (Bereich: FIT-Connect Schnittstelle) konfiguriert und gespeichert werden.

In einem zweiten Schritt muss der ermittelte Zustellpunkt an die Verbindung "gebunden" werden.
Dies wird über den Button realisiert.
Ein Klick auf die einzelnen Zustellpunkte öffnet die Ansicht mit den weiteren Konfigurationsmöglichkeiten. Diese stehen aber erst zur Verfügung, wenn der jeweilige Zustellpunkt an die Verbindung "gebunden" wurde.

Über den Button lassen sich die Zuordnungen wieder löschen. Dabei werden alle Konfigurations-Daten (z.B.: private Schlüssel) innerhalb des "angebundenen" Zustellpunktes ebenfalls aus dem System gelöscht.

Einstellungen für die Anbindung eines konkreten Zustellpunktes (Destination)

Einstellungen am "gebundenen" Zustellpunkts

Sobald ein ermittelter Zustellpunkt an die Verbindung gebunden ist, stehen die nachfolgenden Konfigurationsoptionen zur Verfügung:

Beschreibung (optional): Nähere Beschreibung / Notizen / Anmerkungen zum genutzten FIT-Connect Zustellpunkt.
Privater Schlüssel zum Entschlüsseln: Privater Schlüssel zum Entschlüsseln der FIT-Connect Einreichungen am ausgewählten Zustellpunkt. Die hochgeladenen Datei muss vom Typ JSON Web Key (JWK) sein.
Privater Schlüssel zur Signaturprüfung: Privater Schlüssel zum Prüfen der Signatur einer FIT-Connect Einreichungen am ausgewählten Zustellpunkt. Die hochgeladenen Datei muss vom Typ JSON Web Key (JWK) sein.

Nachdem Dateien hochgeladen wurden muss die Konfiguration gespeichert werden.

In diesem Schritt wird die Zusammengehörigkeit des hochgeladenen privaten Schlüssels und des öffentlichen Schlüssels am FIT-Connect Zustellpunkt abgeprüft.

Sollte das Schlüsselpaar nicht zusammenpassen, so wird dies mit einer entsprechenden Fehlermeldung in der Oberfläche angezeigt.

Einstellung für Callback-Zuordnung

Bei erfolgreicher Zusammengehörigkeit des Schlüsselpaares wird der Bereich Einstellung für Callback-Zuordnung in der Oberfläche angezeigt. Dadurch lässt sich am Zustellpunkt im FIT-Connect Portal eine Callback-URL registrieren.

Bedeutung der Callback-URL:

Die Definition einer Callback-URL an einem Zustellpunkt ermöglicht die automatische Weiterleitung von Einreichungen (sobald diese an das FIT-Connect Portal übermittelt wurden) an ein Verwaltungssystem, welches für die Daten-Konsumierung des Zustellpunktes zuständig ist.

Callback-Secret (Pflicht bei Registrierung eines Callbacks): Ein "Geheimnis" das für die Registrierung einer Callback-URL an einem Zustellpunkt im FIT-Connect Portal notwendig ist. Über den Button kann eine zufällige Zeichenkette generiert werden.
Callback-Server (muss über das Internet erreichbar sein)(Pflicht bei Registrierung eines Callbacks): Eine Auflistung mit allen Base-URLs zum Master-Server und Frontend-Servern, die aus dem formcycle System ermittelt wurden und potenziell als URLs für eine Rückleitung der Einreichungsdaten in Frage kommen.

Achtung: Da die Rückleitung zwangsläufig über das Internet erfolgt, muss die an dieser Stelle ausgewählte Base-URL bzw. der Server über das Internet erreichbar sein!

Callback-URL (aktuell am Zustellpunkt hinterlegt): Dieses Feld wird nur angezeigt, wenn am Zustellpunkt im FIT-Connect Portal aktuell eine Callback-URL hinterlegt ist. Das Feld zeigt dann den aktuell hinterlegten Wert.

Über den Buttonkann am Zustellpunkt im FIT-Connect Portal eine Callback-URL hinterlegt werden. Die aktualisierten Daten an der Verbindung werden dabei auch gleichzeitig gespeichert.

Über den Buttonkann die Callback-URL Zuordnung am Zustellpunkt im FIT-Connect Portal wieder aufgelöst werden. Nutzer-Einreichungen am Zustellpunkt werden dann nicht automatisch an ein Callback-Ziel weitergeleitet, sondern müssen manuell abgerufen werden.

Erweiterte Einstellungen

Im Einzelnen sind dies:

Konfiguration von Verbindungs-Timeouts
Prüfung / Validierung der eingesetzten Zertifikaten / Daten-Schemen
Einstellungen zum Handling von großen Anhängen

Die Konfigurationen in den einzelnen Unterbereichen, verhalten sich analog wie die Konfigurationsmöglichkeiten für die Anbindung eines Onlinedienstes - Bereich: Erweitere Einstellungen.

Übersicht der aktuellen Anbindungsnutzung

In der Übersicht werden alle Workflow-Ereignisse vermerkt, welche die aktuelle Anbindung verwenden. Sie werden dabei nach Mandant, Formularprojekt und verwendeter FIT-Connect Zustellpunkt-ID aufgeschlüsselt.

Die Namen der Workflow-Ereignisse sind verlinkt und man kann auf das jeweilige Formular über den Workflow-Designer zugreifen.

Übersicht zur aktuellen Anbindungsverwendung

Die Übersicht kann auch als Entscheidungshilfe dienen, wenn man eine Verbindung löschen möchte. Hier lässt sich im Vorfeld prüfen ob und wo die Verbindung noch Anwendung findet.

Verbindung prüfen

Über den Button kann geprüft werden, ob eine Verbindung mit den gespeicherten Konfigurationsdaten aufgebaut werden kann. Die Verbindung wird dabei vom formcycle Master-Server aus aufgebaut.

Wenn keine erfolgreiche Verbindung aufgebaut werden kann, sind eventuell Firewall Einstellungen abzuprüfen.
Gegebenenfalls muss an der Verbindung ein Proxy-Server konfiguriert werden.

Folgende FIT-Connect Webservice-Endpunkte werden durch das Plugin angesprochen und müssen unter Umständen in einer Firewall freigeschalten werden.

Bei Anbindung Test-System:
für Authentifizierung: https://auth-testing.fit-connect.fitko.dev
für Ermittlung der Zustellpunkte: https://test.fit-connect.fitko.dev/destination-api
für Daten-Einreichung: https://test.fit-connect.fitko.dev/submission-api
für Suche nach Zustellpunkten: https://routing-api-testing.fit-connect.fitko.dev
Bei Anbindung Stage-System:
für Authentifizierung: https://auth-refz.fit-connect.fitko.net
für Ermittlung der Zustellpunkte: https://stage.fit-connect.fitko.net/destination-api
für Daten-Einreichung: https://stage.fit-connect.fitko.net/submission-api
für Suche nach Zustellpunkten: https://routing-api-prod.fit-connect.fitko.net
Bei Anbindung Produktiv-System:
für Authentifizierung: https://auth-prod.fit-connect.fitko.net
für Ermittlung der Zustellpunkte: https://prod.fit-connect.fitko.net/destination-api
für Daten-Einreichung: https://prod.fit-connect.fitko.net/submission-api
für Suche nach Zustellpunkten: https://routing-api-prod.fit-connect.fitko.net