Zum Hauptinhalt springen

Einführung

Im Rahmen des MVP des EfA-Parameterisierungsportals (EPP) wurde das Self-Service-Portal von FIT-Connect erweitert. Das dort integrierte EPP-Modul ermöglicht die strukturierte Verwaltung von Parameterprofilen und Parameterprofil-Instanzen:

  • Profile: Vorlagen, die definieren, welche Parameter und Datenstrukturen zur Verfügung stehen
  • Parameter-Sets (Parameterprofil-Instanzen, im Sinne des EPP-Backends Anbindungen und deren Onlinedienstparameter): Konkrete Parameterwerte basierend auf einem Profil. Sie können zu einem FIT-Connect-Zustellpunkt oder auch unabhängig davon erstellt werden, wenn der betreffende Onlinedienst einen anderen Zustellweg als FIT-Connect verwendet.

Übersicht der Benutzerrollen​

Entsprechen der unterschiedlichen Rollen gibt es zwei unterschiedliche Benutzergruppen mit jeweils verschiedenen Berechtigungen:

EPP-Profile Gruppe​

Berechtigung:

  • Verwaltung von Profil-Templates
  • Erstellung und Bearbeitung der Anbieter-Information
  • Definition von Parameter-Strukturen und Schemas
  • Verwaltung des Profil-Lifecycle (Entwurf → Produktion)

EPP Gruppe​

Berechtigung:

  • Verwaltung von Parameter-Sets für Zustellpunkte
  • Auswahl und Verwendung vorhandener Profile
  • Befüllung konkreter Parameterwerte
  • Zuordnung zu bestimmten LeiKa-Services und Regionen

Berechtigung​

Voraussetzung ist das Login in der Testumgebung von FIT-Connect mit einem Mein Unternehmenskonto-Zertifikat.

  1. Loggen Sie sich mit einem produktiven Mein Unternehmenskonto-Zertifikat im Self-Service-Portal der Testumgebung ein: https://portal.auth-testing.fit-connect.fitko.dev/login
  2. Wechseln Sie dort in den Bereich "Personen-Verwaltung" bzw. "Nutzer:innen-Verwaltung" und erweitern Sie bei dem Benutzer die Ansicht, neben dem "Besitzer:in" zu sehen ist. Der "Username" wird Ihnen dort angezeigt.
  3. Kontaktieren Sie den technischen Support von FIT-Connect für die Freischaltung Ihres Kontos für die gewünschte(n) Rolle(n) und geben Sie dabei den Usernamen an. Sie erreichen den Support hier: https://docs.fitko.de/fit-connect/docs/contact/

Für EPP-Profile Benutzer​

Als EPP-Profile Benutzer können Vorlagen (Profile) erstellt werden, die später von EPP-Benutzern zur Parametrisierung ihrer Onlinedienste verwendet werden.

Profile erstellen und bearbeiten​

Neues Profil erstellen​

  1. Navigieren Sie zu /efa/epp-profiles
  2. Klicken Sie auf Profil erstellen
  3. Füllen Sie die Profil-Metadaten aus:
    • Name: Eindeutiger Name für das Profil (Pflichtfeld)
    • Version: Versionsnummer (optional)
    • Status: Wird standardmäßig auf "Entwurf" gesetzt
    • Anbieter: Wird automatisch aus Ihrer Anbieter-Information übernommen

Parameter definieren​

Profile können zwei Arten von Parametern enthalten:

1. Attribut-Parameter (einfache Werte)​

Attribute sind einzelne Werte wie Text, URLs, Telefonnummern oder E-Mail-Adressen.

Schritte:

  1. Klicken Sie unter "Top-Level Parameter" auf Attribut hinzufügen
  2. Konfigurieren Sie das Attribut:
    • Name: Technischer Parametername (z.B. efa_contact_url, das EPP-Backend akzepiert hier keine Sonderzeichen)
    • Kurzbezeichnung: Anzeigename für Benutzer
    • Beschreibung: Hilfetext für den Benutzer
    • Datentyp: String, Number, Boolean, etc.
    • Mehrfachauswahl: Durch die Angabe von minimaler und maximaler Anzahl geben Sie an, ob das Attribut optional (0:1), verpflichtend (1:1) oder mehrfach (0:n bzw. 1:n) angegeben werden kann. Bitte beachten Sie: Die Handhabung einer Unbegrenzten Multiplizität ist zwischen Frontend und EPP-Backend noch nicht optimal abgestimmt. Dies führt dazu, dass Parameter-Sets (Profilinstanzen) zu Profilen, in denen eine´unbegrenzte Multiplizität vorkommt nicht in den Status "Betrieb" versetzt werden können. Gegen Sie daher immer eine maximale Anzahl an!
    • Regex-Pattern: Validierungsregel (optional)

Vorlagen verwenden: Das System bietet vordefinierte Vorlagen für häufig verwendete Attribut-Typen:

  • URL: Automatische URL-Validierung
  • Telefonnummer: Telefonnummern-Format
  • Vorwahl: Vorwahl-Format
  • E-Mail: E-Mail-Validierung
2. Referenz-Parameter (komplexe Entitäten)​

Referenzen verweisen auf komplexe Datenstrukturen (Entitäten) wie Adressen oder Kontaktinformationen.

Schritte:

  1. Klicken Sie unter "Top-Level Parameter" auf Referenz hinzufügen
  2. Konfigurieren Sie die Referenz:
    • Name: Technischer Name
    • Kurzbezeichnung: Anzeigename
    • Beschreibung: Hilfetext
    • Ziel-Entität: Name der referenzierten Entität
    • Mehrfachauswahl: Ob mehrere Instanzen erlaubt sind Adress-Vorlage: Für Adressen steht eine vordefinierte Vorlage zur Verfügung, die automatisch alle relevanten Felder (Straße, PLZ, Ort, etc.) erstellt.

Entitäten definieren​

Entitäten sind wiederverwendbare Datenstrukturen, die über Referenzen eingebunden werden.

Schritte:

  1. Scrollen Sie zum Abschnitt "Entitäten"
  2. Klicken Sie auf Entität hinzufügen
  3. Geben Sie einen Namen und eine Beschreibung ein (z.B. "Adresse")
  4. Fügen Sie Parameter zur Entität hinzu (Attribute oder weitere Referenzen)

Profil speichern​

  1. Überprüfen Sie alle Eingaben
  2. Klicken Sie auf Profil speichern
  3. Das Profil wird im Status "Entwurf" gespeichert

Profil-Status und Lifecycle​

Profile durchlaufen verschiedene Status-Phasen:

Status: Entwurf​

  • Beschreibung: Das Profil befindet sich in Entwicklung
  • Bearbeitbar: Ja, vollständig editierbar
  • Verwendbar für Parameter-Sets: Nein
  • Aktionen:
    • Bearbeiten
    • Löschen
    • In Produktion versetzen

Status: Produktion​

  • Beschreibung: Das Profil ist freigegeben und produktiv
  • Bearbeitbar: Nein (schreibgeschützt)
  • Verwendbar für Parameter-Sets: Ja
  • Aktionen:
    • Ansehen (nur lesend)
    • Als gelöscht markieren Wichtig: Sobald ein Profil in Produktion versetzt wurde, kann es nicht mehr bearbeitet werden. Dies gewährleistet die Konsistenz bereits erstellter Parameter-Sets.

Status: Gelöscht​

  • Beschreibung: Das Profil ist als gelöscht markiert
  • Bearbeitbar: Nein
  • Verwendbar für Parameter-Sets: Nein (nur für bestehende)
  • Wiederherstellung: Nicht möglich

Für EPP Benutzer​

Als EPP-Benutzer können Sie Parameter-Sets für Ihre Zustellpunkte oder auch unabhängig von einem Zustellpunkt erstellen und verwalten.

Anbieter-Verwaltung​

Die Rolle des Onlinedienstanbieters ist am EPP-MVP nicht beteiligt. Die API des EPP-Backends (Parameter Registry) sieht jedoch vor, dass bei den Parametern (konkret beim Objekt "Anbindung") die ID eines Onlinedienstanbieters angegeben werden muss. Dies soll bei der Nutzung des Self-Service-Portals als EEP-Frontend möglichst einfach gehalten werden. Sie müssen daher lediglich einmal einen Onlinedienstanbieter erstellen, indem sie für ihn einen Namen vergeben. Das Self-Service-Portal wird dessen ID automatisch für alle von Ihnen bzw. den Mitgliedern Ihres Teams gepflegten Parameter-Sets verwenden. Bitte beachten Sie: Für den MVP wurde übergangsweise die Parameter-API von FIT-Conenct bereitgestellt, um die Pflege von Parametern zu Zustellpunkten per API analog zur Destination-API zu ermöglichen. Auch hierfür müssen Sie zunächst einen Onlinedienstanbieter im Self-Service-Portal erstellen, der dann bei der Nutzung der Parameter-API automatisch referenziert wird.

Erstmalige Einrichtung​

Beim ersten Zugriff auf die Parametersets muss zunächst ein Anbieter-Namen festgelegt werden:

  1. Navigatione zu EPP (URL: /efa/epp)
  2. Hier sehen Sie eine Karte "Onlinedienstanbieter Name festlegen"
  3. Geben Sie einen Namen für Ihren Anbieter ein
  4. Klicken Sie auf Speichern Nach der Einrichtung erhalten Sie eine eindeutige Anbieter-ID, die automatisch generiert wird.

Anbieter-Information bearbeiten​

Nach der Ersteinrichtung können Sie Ihren Anbieter-Namen jederzeit ändern:

  1. Klicken Sie auf das Bearbeiten-Symbol (Stift) in der Anbieter-Übersicht
  2. Ändern Sie den Namen im Textfeld
  3. Klicken Sie auf das Häkchen zum Speichern oder auf das X zum Abbrechen

Parameter-Sets verwalten​

Parameterprofilinstanzen werden hier Parameter-Sets genannt.

Übersicht aufrufen​

  1. Navigieren Sie zu EPP (URL: /efa/epp)
  2. Sie sehen eine Liste aller vorhandenen Parameter-Sets mit:
    • Bezeichnung: Name des Parameter-Sets
    • Status: Aktueller Status (Entwurf, In Betrieb, Inaktiv)

Parameter-Set bearbeiten​

  1. Klicken Sie auf das Bearbeiten-Symbol beim gewünschten Parameter-Set
  2. Nehmen Sie Ihre Änderungen vor
  3. Klicken Sie auf Speichern

Parameter-Set löschen​

  1. Klicken Sie auf das Löschen-Symbol (Papierkorb)
  2. Bestätigen Sie die Löschung
  3. Das Parameter-Set wird unwiderruflich gelöscht

Parameter-Set erstellen​

Der Erstellungsprozess erfolgt in drei Schritten:

Schritt 1: Set erstellen​

  1. Klicken Sie auf Parameter-Set anlegen
  2. Klicken Sie bei einen Ihrer bestehenden Zustellpunkte auf "Parameter-Set anlegen" oder
  3. Klicken Sie bei "Alternativ können Sie ohne Zustellpunkt fortfahren:" auf "Parameter-Set anlegen".

Schritt 2: Profil auswählen (Wizard)​

  1. Geben Sie die Profil-ID ein (diese erhalten Sie vom Profil-Administrator)
  2. Klicken Sie auf Laden
  3. Die Profil-Informationen werden angezeigt:
    • Profil-Name
    • Anbieter
    • Version
  4. Klicken Sie auf Weiter

Schritt 3: Parameter-Daten eingeben​

Jetzt befüllen Sie das dynamische Formular basierend auf dem gewählten Profil.

Abschnitt: Metadaten​
  • Zustellpunkt-ID: Wird automatisch befüllt (falls in Schritt 1 ausgewählt)
  • Zustellpunkt-Name: Name des Zustellpunkts
  • Anbieter-ID: Automatisch aus dem initial angelegten Onlinedienstanbieter übernommen
  • Profil-ID: Automatisch aus dem Profil übernommen
  • Status: Wählen Sie den Status (Entwurf, Rezension, Betrieb, Inaktiv)
Abschnitt: Sprachen​

Wählen Sie die unterstützten Sprachen für Ihr Parameter-Set:

  • Deutsch
  • Englisch Hinweis: Mehrsprachige Felder werden für jede ausgewählte Sprache angezeigt.
Abschnitt: LeiKa-Services​

Wurde das Parameter-Set zu einem Zustellpunkt angelegt, werden die Leistungen aus dem Zustellpunkt übernommen und müssen nicht eigens gepflegt werden. Ansonsten müssen Sie die Leistungen angeben, für die dieses Parameter-Set gilt:

  1. Klicken Sie auf Service hinzufügen (+)
  2. Geben Sie den Leistungs-Identifikator (URN) ein
    • Format: 14-stellige URN aus dem Leistungskatalog
    • Beispiel: 99-000000-00-00
  3. Die URN wird automatisch validiert
  4. Fügen Sie weitere Services hinzu, falls benötigt Bitte beachten: Das EEP-Backend lässt pro Kombination von Leistung und Region jeweils nur eine aktives Parameter-Set zu.
Abschnitt: Regionen​

Wurde das Parameter-Set zu einem Zustellpunkt angelegt, werden die Regionen aus dem Zustellpunkt übernommen und müssen nicht eigens gepflegt werden. Ansonsten müssen Sie die Regionen angeben, für die dieses Parameter-Set gilt:

  1. Klicken Sie auf Region hinzufügen (+)
  2. Geben Sie den Amtlichen Regionalschlüssel (ARS) ein
    • Format: Genau 12 Ziffern
    • Beispiel: 010510000000
  3. Das System validiert das Format automatisch
  4. Fügen Sie weitere Regionen hinzu, falls benötigt Bitte beachten: Das EEP-Backend lässt pro Kombination von Leistung und Region jeweils nur eine aktives Parameter-Set zu.
Abschnitt: Attribut-Parameter​

Hier werden alle im Profil definierten Attribut-Parameter angezeigt. Die Felder variieren je nach Profil-Definition. Mehrsprachige Felder: Wenn Sie mehrere Sprachen ausgewählt haben, erscheinen Tabs für jede Sprache. Mehrfachwerte: Bei Feldern mit Mehrfachauswahl können Sie durch Klick auf (+) weitere Werte hinzufügen. Bei Arrays (Mehrfachauswahl):

  1. Klicken Sie auf Hinzufügen (+), um eine neue Instanz zu erstellen
  2. Befüllen Sie alle Felder der Entität
  3. Löschen Sie Instanzen über das Papierkorb-Symbol

Speichern​

  1. Überprüfen Sie alle Eingaben
  2. Klicken Sie auf Speichern
  3. Das Parameter-Set wird erstellt und Sie werden zur Bearbeitungsansicht weitergeleitet

Parameter-Set bearbeiten​

  1. Öffnen Sie das Parameter-Set aus der Liste
  2. Alle Formulare sind mit den bestehenden Werten vorausgefüllt
  3. Bearbeiten Sie die gewünschten Felder
  4. Klicken Sie auf Speichern

Parameter-Pflege zu einem Zustellpunkt per API​

Über die API können Parameterprofilinstanzen zu Zustellpunkten gepflegt werden. Die Authentifizierung muss mit einem Client erfolgen, der bzgl. des gewünschten Zustellpunktes schreibberechtigt ist - analog zur Destination-API. Die API-Spezifikation finden Sie hier:

Anlegen eines Onlinedienstanbieters​

Wie oben beschrieben muss zunächst einmalig im Self-Service-Portal ein Onlinedienstanbieter angelegt werden. Dieser Onlinedienstanbieter ist Voraussetzung für das Anlegen einer Anbindung und damit auch manuelle Voraussetzung für alle API-Requests.

Anlegen bzw. Pflege der Anbindung​

  • POST /registry/v1/anbindungen
  • PUT /registry/v1/anbindungen/{id} Wie vom EPP-Backend (Parameter Registry) festgelegt, wird zunächst die Anbindung angelegt und anschließend zu der Anbindung die Parameter. Das Schema der Parameter basiert dabei immer auf dem Profil, das beim Anlegen der Anbindung angegeben wurde. Da diese API ausschließlich die Pflege von Parametern zu (aktiven) Zustellpunkten erlaubt, ist folgendes zu beachten:
  • Bei der Anbindung muss der Parameter destinationId angegeben werden und die ID einer eigenen, aktiven Destination enthalten.
  • Der Parameter destinationService darf hingegen nicht angegeben werden. Leistungen und Regionen werden direkt aus dem Zustellpunkt bezogen. Bitte beachten: Das EEP-Backend lässt pro Kombination von Leistung und Region jeweils nur eine aktive Anbindung zu.

Anmerkungen zu den übrigen Parametern:

  • erbtVomStandardtemplateId: wird nicht benötigt
  • onlinedienstparameterAktuell: wird nicht benötigt
  • profilId: die ID eines Profils aus der EPP-Instanz https://test-epp-backend.pvog.dataport.de
  • sprachen: verwenden Sie vorerst nur ["de"]

Pflege der Parameter​

  • PUT /registry/v1/anbindungen/{id}/onlinedienstparameter Das Schema ist abhängig von dem Profil, dessen ID bei der Anbindung angegeben wurde.

Setzen des Status der Anbindung​

  • PUT /registry/v1/anbindungen/{id}/status Mögliche Werte:
  • ENTWURF - Onlinedienstparameter können frei bearbeitet, aber von Onlinediensten nicht abgerufen werden. Nur in diesem Status besteht eine Möglichkeit die Anbindung endgültig zu löschen. Änderungen an Onlinedienstparametern werden validiert aber nicht abgelehnt. Statusübergang nur zu REZENSION möglich.
  • REZENSION - Onlinedienstparameter werden durch einen Gutachter fachlich geprüft. Parameter können von Onlinediensten nicht abgerufen werden. Statusübergang zu BETRIEB oder ENTWURF möglich.
  • BETRIEB - Onlinedienstparameter können von Onlinediensten abgerufen werden. Änderungen mit nicht validen Onlinedienstparametern werden abgelehnt. Statusübergang nur zu INAKTIV möglich.
  • INAKTIV - Onlinedienstparameter können von Onlinediensten nicht abgerufen werden. Statusübergang nur zu BETRIEB möglich.

Routing​

Der Routingdienst der FIT-Connect Testumgebung wird zu Zustellpunkten gepflegte Parameter auf der obersten Ebene im Array eppParameters jeweils mit Namen und Wert ausgeben. Um Implementierungsaufwand und - zeit gering zu halten gelten dabei folgende Beschränkungen:

  • Es werden nur einfache Attribute (also keine Referenzen oder deren Attribute) mit einer Multiplizität von 1 ausgegeben.
  • Von den Attributen wird nur der ersten Attributwert ausgegeben, entsprechend wird nur eine Sprache "de" unterstützt.

Unterstützung und Meldung von Problemen​

Da das EEP-Backend nicht in allen Fällen eine differenzierte Fehlermeldung zurückgibt, fehlt bei der Suche nach der Ursache für eine fehlgeschlagene Aktion oft ein Anhaltspunkt. Ein neuer leicht geänderter Versuch ist dann empfehlenswert. Bei größeren Problemen können Sie sich an den technischen Support von FIT-Connect wenden.

Feature Requests​

Feature Requests für die Weiterentwicklung des EPP-MVP zum MMP können als Issues zentral in folgendem openCode Repository erstellt werden:
https://gitlab.opencode.de/fitko/pvog/epp/-/issues

Den Zugang zum Repository erhalten Sie per E-Mail an efa-parametrisierung.de@capgemini.com. Geben Sie dabei Ihren openCode-Usernamen an, dieser beginnt in der Regel mit "OC".
Bitte registrieren Sie sich ggf. zuvor bei openCode und schalten Sie dabei die Nutzung der GitLab-Features für sich frei.