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

INHALTSVERZEICHNIS

• Übersicht
• Sender-Funktionalität
  • Workflow-Aktion: Senden an FIT-Connect
    • Einstellungen für FIT-Connect Zustellpunkt
    • Einstellung für Datenübermittlung
    • Konfiguration zusätzlich zu übermittelnder Anhänge
    • Rückgabewerte
• Empfänger-Funktionalität
  • Workflow-Ereignis: FIT-Connect Datenabruf
    • Zustellpunkt-Einstellungen
    • Informationen zum ausgewählten Zustellpunkt
    • Rückgabewerte 
      • Bereitgestellte Werte
      • Bereitgestellte Dateien

Übersicht

Das kostenpflichtige FIT-Connect Plugin dient zur Übertragung von (verschlüsselten) Antragsdaten aus Formularen an ein zuständiges Fachverfahren. Ab Version 2.0.0 des Plugins kann formcycle auch als Fachverfahren agieren und die eingereichten Daten aus FIT-Connect abrufen und in einem Formular-Projekt weiter verarbeiten.

Mit dem Einsatz des Plugins lassen sich somit sowohl FIT-Connect Sender- (Onlinedienste) als auch Empfänger-Systeme (Verwaltungssysteme) abbilden.

Sender-Funktionalität

Um die FIT-Connect Sender Funktionalität in formcycle abzubilden müssen folgende Voraussetzungen gegeben sein:

• Im FIT-Connect Portal muss ein Onlinedienst registriert sein, sodass ein Zugriff auf FIT-Connect möglich wird
• Im FIT-Connect Portal muss ein Zustellpunkt existent sein, an den man Daten versenden kann. Das heißt, der Zustellpunkt darf entweder keine Absenderbeschränkung aufweisen, oder muss den gewählten Onlinedienst Zugang gewähren. Die DestinationId des Zustellpunktes muss bekannt sein.
• In formcycle muss ein Anbindung an einen Onlinedienst konfiguriert sein.
• In formcycle muss ein Formular existieren, welches die nachfolgend beschriebene Workflow-Aktion Senden an FIT-Connect beinhaltet.

Workflow-Aktion: Senden an FIT-Connect

Das Workflow-Aktion Senden an FIT-Connect kann in einem Formular als Datenexporteur an FIT-Connect genutzt werden. 

Einstellungen für FIT-Connect Zustellpunkt

Im Bereich Einstellungen für FIT-Connect Zustellpunkt können folgende Einstellungen konfiguriert werden:

• FIT-Connect Onlinedienst (Pflicht): An dieser Stelle muss eine FIT-Connect Verbindung vom Typ Onlinedienst ausgewählt werden. Diese Verbindung wird zur Laufzeit zum Senden der Einreichungen an FIT-Connect verwendet.
  Näheres zu Konfiguration von FIT-Connect Onlinedienst-Verbindungen finden Sie hier.
  
  Über den Buttonlässt sich prüfen, ob mit dem ausgewählten Onlinedienst eine Verbindung zu FIT-Connect hergestellt werden kann.
  
  
• Empfänger- / Zustellpunkt-UUID (Pflicht): Ein Identifier der den Empfänger der Nachricht in FIT-Connect eindeutig referenziert (Angabe in Form einer UUID: 00000000-0000-0000-0000-000000000000).

Der konfigurierte FIT-Connect Zustellpunkt muss mindestens ein Metadatenschema in der Version 1.3 oder größer unterstützen. Die veralteten Metadatenschemata-Versionen < 1.3 werden durch das eingebundene FIT-Connect SDK nicht mehr unterstützt. 
Die unterstützten Metadatenschemen lassen sich direkt am jeweiligen Zustellpunkt über das FITKO SSP konfigurieren.

• FIT-Connect Vorgangs-ID (Optional): Durch Angabe einer existierenden FIT-Connect Vorgangs-ID, kann die übermittelte Einreichung diesem FIT-Connect Vorgang hinzugefügt werden, ansonsten wird auf Seiten von FIT-Connect ein neuer Vorgang erzeugt.
  
  
• Service Identifier (Verwaltungsleistung / LeiKa-ID) (Pflicht): Eine ID zum Identifizieren einer konkreten Service-/Verwaltungsleistung. Ist in URN-Notation (Uniform Resource Name) anzugeben, zum Beispiel mittels eines Leistungs-Katalog (LeiKa) - Schlüssels
  z.B.: urn:de:fim:leika:leistung:99108008252000, urn:myleistung
  
  
• Service-Bezeichnung (Optional): Bezeichnung für den Service. Wenn an dieser Eigenschaft kein Wert definiert ist, wird der Name der Workflow-Aktion als Bezeichnung an FIT-Connect übermittelt.

Einstellung für Datenübermittlung

In diesem Bereich können folgende Eigenschaften konfiguriert werden:

• Art der Nachricht (Pflichtangabe): Definiert die Quelle (aus Datei oder aus Textfeld) und den Typ (JSON oder XML) der zu übermittelnden Nachricht. Je nach Festlegung in diesem Feld, wird entweder eine Texteditor zur direkten Erzeugen der Nachricht, oder ein Dateiauswahl-Feld zur Angabe einer Nachrichtendatei für die weitere Konfiguration angezeigt.
  
  
• Nachricht im JSON / XML - Format (Pflichtangabe): Im eingeblendeten Editor muss, je nach der zuvor festgelegten Nachrichten - Art (JSON oder XML) eine entsprechende Datenstruktur angelegt werden. Dabei können Platzhalter verwendet werden. Zum Ausführungszeitpunkt der Plugin-Aktion wird die erzeugte Nachricht (mit ersetzten Platzhaltern) grundsätzlich in Hinblick auf den festgelegten Nachrichten-Typ (JSON oder XML) hin, geprüft. Wenn diese Prüfung fehlschlägt, so wird die Plugin-Verarbeitung mit dem Fehlercode PARAMETER_FORMAT_ERROR beendet.
  Eine konkrete Prüfung der Nachricht, gegen das in der Eigenschaft Schema-URI definierte Schema, erfolgt nicht, da dies Aufgabe der FIT-Connect-Schnittstelle ist.
  Die Schema-Validierung kann über eine Einstellung am jeweilig gewählten Onlinedienst deaktiviert werden. Die dafür zuständig Konfiguration ist hier beschrieben.
  
  
• oder 
  Nachrichten-Datei im JSON / XML - Format (Pflichtangabe): Hier kann eine Datei aus einer vorherigen Workflow-Aktion, einem Upload-Feld oder einer externen Ressourcen-URL ausgewählt werden. Es ist dabei auf den zuvor festgelegten Nachrichten-Typ (JSON oder XML) zu achten. Zum Ausführungszeitpunkt der Plugin-Aktion wird der Nachrichten-Typ (JSON oder XML) geprüft, wenn diese Prüfung fehlschlägt, so wird die Plugin-Verarbeitung mit dem Fehlercode PARAMETER_FORMAT_ERROR beendet.
  
  
• Schema-URI (Pflichtangabe): URI zur Definition des Schemas, welches dem gemeinsamen Datenaustausch zwischen Sender und Empfänger dient und die Struktur der übermittelten Daten definiert. Eine Prüfung gegen das definierte Schema erfolgt auf Seiten von FIT-Connect. Wenn diese Überprüfung fehlschlägt, wird diese mit einem entsprechenden Fehlercode (WEBSERVICE_ERROR) an der Plugin-Aktion quittiert.

Konfiguration zusätzlich zu übermittelnder Anhänge

Im Bereich der zusätzlich zu übermittelnden Anhänge können folgende Eigenschaften konfiguriert werden:

• Dateien (Optional): Hier können Dateien aus einer vorherigen Workflow-Aktion, Upload-Feldern oder einer externen Ressourcen-URL ausgewählt werden. 

Rückgabewerte

Wenn eine Nachricht erfolgreich an FIT-Connect übermittelt werden konnte, terminiert die Plugin-Aktion normal und liefert folgende Informationen als Rückgabeparameter zurück:

• Vorgangs-ID: ([%$Senden an FIT-Connect.RESULT.caseId%]) Die von FIT-Connect gelieferte Vorgangs-ID, unter der die aktuelle Einreichung abgespeichert wurde. (Kann in einer weiteren Senden an FIT-Connect Aktion dazu genutzt werden, eine weitere Einreichung dem gleichen Vorgang zuzuordnen.)
  
  
• ID des Zustellpunktes: ([%$Senden an FIT-Connect.RESULT.destinationId%]) ID des Zustellpunktes, an den die Einreichung übermittelt wurde.
  
  
• Einreichungs-ID: ([%$Senden an FIT-Connect.RESULT.submissionId%]) Die von FIT-Connect zurück gelieferte ID der Einreichung.

Bei erfolgreicher Nachrichtenübermittlung an FIT-Connect werden die aktuelle Einreichungs-ID, die FIT-Connect Vorgangs-ID und die UUID des genutzten Zustellpunktes als Information im Postkorb-Verlauf hinterlegt.

Fehler, während der Plugin-Verarbeitung, welche zu einem Abbruch der Workflow-Verarbeitungskette führen:

• AUTHORIZATION_FAILED: Tritt auf, wenn mit den hinterlegten Login-Daten keine erfolgreiche Authentifizierung am FIT-Connect System durchgeführt werden konnte.
  
  
• MANDATORY_PARAMETER_MISSING: Tritt auf, wenn der FIT-Connect Service aufgrund fehlender Parameter zu Laufzeit nicht aufgerufen werden konnte.
  
  
• NO_MESSAGE_FILE_FOUND: Tritt auf, wenn keine Nachricht zur Übertragung an FIT-Connect ermittelt werden konnte.
  
  
• PARAMETER_FORMAT_ERROR: Tritt auf, wenn die zu übermittelnde Nachricht nicht dem geforderten JSON oder XML Format entsprach.
  
  
• WEBSERVICE_ERROR: Tritt auf, wenn der Aufruf einer FIT-Connect Webservice-Methode einen Fehler zurück lieferte.
  
  
• INTERNAL_ERROR: Tritt auf, wenn es bei der Verarbeitung zu einer Ausnahme kam, welche nicht mit den anderen Fehler-Typen bereits verarbeitet wurde.

Fehler, während der Plugin-Verarbeitung, welche nicht zu einem Abbruch der Workflow-Verarbeitungskette führen:

• NO_ATTACHMENTS_FOUND: Tritt auf, wenn zur Laufzeit keine Daten zusätzlichen Anhänge ermittelt werden konnten, obwohl diese an der Plugin-Aktion definiert sind.
  Es wird eine Warnung über das Auftreten dieser Ausnahme im Protokoll erzeugt.

Empfänger-Funktionalität

Um die FIT-Connect Empfänger Funktionalität in formcycle abzubilden müssen folgende Voraussetzungen gegeben sein:

• Im FIT-Connect Portal muss ein Verwaltungssystem registriert sein
• Im FIT-Connect Portal muss ein Zustellpunkt konfiguriert sein.  Inklusive der notwendigen öffentlichen Schlüssel (JWKs) zum Verschlüsseln und Signieren. Der Zustellpunkt muss dem Verwaltungssystem zugeordnet sein, sodass dieses auf den Zustellpunkt zugreifen darf
• In formcycle muss ein Anbindung an ein Verwaltungssystem konfiguriert sein. An dieser Verbindung müssen die privaten Schlüssel zum Entschlüsseln und zur Signaturprüfung hinterlegt sein.
• In formcycle muss ein Formular existieren, welches das nachfolgend beschriebene Workflow-Ereignis FIT-Connect Datenabruf beinhaltet.

Workflow-Ereignis: FIT-Connect Datenabruf

Das Ereignis FIT-Connect Datenabruf kann in einem Formular als Einstieg für den Empfang von Einreichungsdaten aus FIT-Connect genutzt werden. Dabei gibt es 2 Möglichkeiten den Datenempfang zu realisieren:

• die Anbindung mittels "Callback":
  Bei diesem Mechanismus wird formcycle vollautomatisch von FIT-Connect über neue Einreichungen informiert.
  Im eingebundenen Formular wird für jede neue Einreichung automatisch ein neuer Vorgang angelegt und die übermittelten Einreichungsdaten werden diesem Vorgang zur Verfügung gestellt.
• oder mittels "Polling":
  Dafür muss manuell eine Abfrage nach neuen Einreichungen gestartet werden. Ermittelt die Abfrage neue Einreichungen wird für jede Einreichung ebenfalls ein neuer Vorgang erstellt.

Hinweis:
Damit ein Datenempfang mittels Callback möglich wird, muss der angebundene Zustellpunkt an der genutzten Verwaltungssystem-Anbindung entsprechend konfiguriert sein. 
Wenn kein "Callback" am Zustellpunkt konfiguriert ist, steht automatisch das "Polling" als Abfragemethodik zur Verfügung.

Jeder verarbeitete Vorgang, der auf Grundlage einer ermittelten Einreichung entstanden ist, wird im Protokoll des entsprechenden Mandanten vermerkt.

Zustellpunkt-Einstellungen

• Rückmeldungstyp (Pflicht): Definiert den Typ der Rückmeldung aus dem FIT-Connect Portal, welche mit dem Ereignis behandelt werden soll. Aktuell steht nur Einreichung zur Auswahl.
  
  
• Angebundenes Verwaltungssystem (Pflicht): An dieser Stelle muss eine FIT-Connect Verbindung vom Typ Verwaltungssystem ausgewählt werden. Diese Verbindung wird zur Laufzeit zum Empfangen von Einreichungen aus FIT-Connect verwendet. Näheres zu Konfiguration von FIT-Connect Verwaltungssystem-Verbindungen finden Sie hier.
  
  
• Empfänger- / Zustellpunkt-UUID (Pflicht): Hier werden alle an der Verwaltungssystem-Verbindung gebundenen und vollständig konfigurierten Zustellpunkte aufgeführt und zur Auswahl angezeigt. Näheres zur Verwaltung der Zustellpunkte an der Verwaltungssystem-Verbindung finden Sie hier.

Hinweis:
Ein Zustellpunkt gilt als "vollständig konfiguriert", wenn er an eine Verwaltungssystem-Verbindung "gebunden" ist und die privaten Schlüssel zum Entschlüsseln und zur Verifizierung der Signierung hinterlegt sind.

Informationen zum ausgewählten Zustellpunkt

Sobald die oben beschriebenen Einstellungen korrekt hinterlegt sind, wird mit diesen Konfigurationsdaten ein Abgleich mit dem konfigurierten Verwaltungssystem im FIT-Connect Portal. Das Ergebnis dieses Abgleichs wird in diesem Bereich angezeigt und beinhaltet folgenden Informationen:

• Name: "sprechender" Name des angebundenen Zustellpunktes aus dem FIT-Connect Portal
  
  
• Zugeordnete Callback-URL: Dieses Feld ist nur vorhanden, wenn die Anbindung mittels "Callback" erfolgt und enthält die aktuell am Zustellpunkt aus dem FIT-Connect Portal hinterlegte Callback-URL. Über diese URL informiert das FIT-Connect Portal das formcycle System über neue Einreichungen.

Da die Rückmeldung (Callback) aus dem FIT-Connect Portal heraus über das Internet passiert, muss die hier hinterlegte URL/Domain auch über das Internet erreichbar sein. Sollte dies nicht der Fall sein, so müssen an der Verwaltungssystem-Anbindung entsprechende Anpassungen vorgenommen werden, um ein Callback zu ermöglichen.

• Verbindungsstatus: Zeigt den aktuellen Status der Callback Verbindung an. Gleicht dabei den Wert der Callback-URL am angebundenen Zustellpunkt in formcycle, mit dem ermittelten Wert des Zustellpunktes aus dem FIT-Connect Portal, ab.

Sind die Werte nicht gleich oder konnte kein Wert für die Callback-URL aus FIT-Connect Portal ermittelt werden, so ist aktuell kein Callback möglich und es wird 
der Buttonangezeigt.
 
Mittels Klick auf den Button kann dann eine Abfrage an das FIT-Connect Portal über neuen Einreichungen gestellt werden. Werden neue Einreichungen gefunden, so wird für diese Einreichung jeweils ein neuer Vorgang am aktuellen Formular erzeugt und das Ereignis wird entsprechend in den Vorgängen aufgerufen und dabei werden die jeweils übermittelten Daten im Workflow zur Verfügung gestellt.

Rückgabewerte 

Bereitgestellte Werte

• Vorgangs-ID: ([%$Trigger.caseId%]) Die von FIT-Connect gelieferte Vorgangs-ID, unter der die aktuelle Einreichung registriert ist.
  
  
• Daten als JSON-Objekt (Optional): ([%$Trigger.dataAsJson%]) Dieses Objekt steht nur zur Verfügung, wenn die aus der Einreichung stammenden Daten vom Typ JSON sind. Man kann mittels JSON-Path Notation innerhalb des Platzhalters auf einzelne Eigenschaften des Daten-Objektes zugreifen.
  
  
• Daten als Text-Objekt: ([%$Trigger.dataAsText%]) Dieses Objekt steht immer zur Verfügung. Es enthält die in der Einreichung übermittelten Daten als Text (Die Datenstruktur kann XML oder JSON sein). 
  
  
• ID des Zustellpunktes: ([%$Trigger.destinationId%]) ID des Zustellpunktes, an den die Einreichung übermittelt wurde.
  
  
• Metadaten der Einreichung: ([%$Trigger.metadata%]) Metadaten zur abgerufenen Einreichung. Wird als JSON-Objekt zur Verfügung gestellt. Man kann mittels JSON-Path Notation innerhalb des Platzhalters auf einzelne Eigenschaften des Metadaten-Objektes zugreifen.
  
  
• Einreichungs-ID: ([%$Trigger.submissionId%]) Die von FIT-Connect zurück gelieferte ID der Einreichung.

Bereitgestellte Dateien

Auf die bereitgestellten Dateien kann mittels "datei-verarbeitender" Workflow-Aktionen zugegriffen werden.

• Attachments (Optional): Enthält die an der Einreichung hinterlegten Datei-Anlagen als eine Liste von Dateien.
  
  
• Data: Enthält die übermittelten Einreichungsdaten als Datei-Objekt. Wird zusätzlich zu den Objekten Daten als JSON-Objekt und Daten als Text-Objekt zur Verfügung gestellt und ist im weitesten Sinne dafür gedacht, wenn die Daten der Einreichung ungefiltert an Drittsysteme (z.B. zur Ablage in einem angebundenen DMS, als E-Mail Anhang etc.) weiter gereicht werden sollen.