AKDB: Bürgerkonto-Service-Plugin

Plugin-Download (erfordert Anmeldung)

Inhalt [ Verbergen ]

Einbindung des Bürgerkonto Logins im Designer
Einbindung des Bürgerkonto Logins als Externer Benutzer
Designer-Element: Bürgerkonto Daten Vorlage
- Darstellung des genutzten Authentifizierungsverfahren
AKDB Postkorbanbindung in der Statusverarbeitung
- Bedingte Ausführung der AKDB:Postkorbnachricht senden-Aktion

Achtung:
Bevor Sie die AKDB-Basisdienste in ihren Formular-Prozessen einbinden, stellen Sie bitte sicher, dass die konfigurative Anbindung der Dienste durch den Xima® Formcycle-Administrator erfolgt ist!

Formularvorlage AKDB Basisdienste

Über das AKDB Bürgerkonto Service Plugin werden Möglichkeiten zur Einbindung der AKDB Basisdienste Bürgerkonto und Postkorb in Xima® Formcycle bereitgestellt.

Um Formulare mit Bürgerkonto- und Postkorb-Anbindung schnell und einfach zu erstellen, gibt es eine Vorlage mit Namen AKDB Basisdienste. Diese ist über den Menüpunkt Meine Formulare und dann über die Kachel Neues Formular erstellen erreichbar. Wird die Vorlage genutzt, dann sind das Bürgerkonto und der Postkorb mit einer funktionierenden Default-Konfiguration eingebunden, die man sofort nutzen kann.

Einbindung des Bürgerkonto Logins im Designer

Formular-Element AKDB Bürgerkonto

Zur vereinfachten Einbindung des Bürgerkontos in Formulare gibt es das Formular-Element AKDB Bürgerkonto. Dieses kann per "Drag & Drop" in den Seitenbereich gezogen werden. Der dann vorhandene Absende-Button kann im Bereich Buergerkonto-Login Einstellungen konfiguriert werden. Die Einstellungen haben folgende Bedeutung:

Schaltflächen Text: Beschriftung des Login-Buttons
Login im Popup: Wenn aktiviert, wird die Login-Seite des Bürgerservice-Portals in einem Popup geöffnet, ansonst erfolgt die Anzeige in der gleichen Seite.
Formularseite nach Login: Hier wird die Formularseite festgelegt, welche angezeigt werden soll, wenn der Login erfolgreich war.
Formularseite nach abgebrochenen Login: Hier wird die Formularseite festgelegt, welche angezeigt werden soll, wenn der Login abgebrochen wurde.
Eingaben prüfen vor Login: Wenn aktiviert, werden die bisherigen Formulareingaben validiert. Der Start des Bürgerkonto Login-Prozesses ist dann erst möglich, wenn alle Nutzereingaben auf der Seite valide sind. Wenn deaktiviert, findet keine Überprüfung der bisherigen Formulareingaben statt und es wird sofort zum Bürgerservice-Portal weitergeleitet.
Art der Rückgabedaten: Hier besteht die Auswahl zwischen:

personenbezogenen Daten
organisationsbezogenen Daten
personen- oder organisationsbezogenen Daten

Mit dieser Einstellung lässt sich die Art der zu erwarteten Rückgabedaten steuern, je nach Anforderung.; Das heißt, wenn beispielsweise nur Daten einer natürlichen Person im Formularprozess zugelassen sind, ist hier die Auswahl auf personenbezogene Daten einzustellen.
Bürgerdaten Parameter-Suffix: Hier kann ein Suffix definiert werden, welches beim Vorbelegen von Formularelementen, mit den ermittelten Bürgerkonto-Daten, Anwendung findet.
Durch das Suffix wird es möglich mehrere Authentifizierungen und Formularelement-Vorbelegungen innerhalb eines Formulars zu realisieren.; Als Suffix sind Buchstaben, Zahlen und der Unterstrich erlaubt.; Beispiel:
Wenn als Suffix "_1" definiert wurde, muss das Formularfeld für die Adresse mit dem Namen "tfAntragstellerAdresse_1" benannt werden, damit eine Vorbelegung erfolgreich stattfinden kann.
gefordertes Authentifizierungsverfahren: Hier kann das dem Nutzer zur Verfügung stehende Authentifizierungsverfahren eingeschränkt werden.; Es gibt folgende Auswahlmöglichkeiten:

keine Einschränkung: Login mittels Passwort, Authega-Zertifikat oder Personalausweis steht zur Auswahl
Authega: Nur die Authentifizierung mittels Authega-Zertifikat steht zur Auswahl
Authega oder Personalausweis: Login mittels Authega-Zertifikat oder Personalausweis steht zur Auswahl (Achtung: Diese Auswahl wird momentan nicht mehr vom AKDB Portal unterstützt!)
Personalausweis: nur Authentifizierung mittels Personalausweis steht zur Auswahl

Einbindung des Bürgerkonto Logins als Externer Benutzer

6.4.0+ Die Option steht in der Xima® Formcycle - Version ab 6.4.0 mit der Plugin - Version ab 2.8.0 zur Verfügung.

Bürgerkonto-Login als Externer Benutzer einrichten. (Schritt 1)

Zur Einbindung des Bürgerkonto-Logins über einen Externen Benutzer, muss diese Login Möglichkeit zuvor konfiguriert werden.

Dazu muss im jeweiligen Mandaten in den Konfigurationsbereich Externe Benutzer gewechselt werden. Dort muss mittels der über das Plugin zur Verfügung gestellte AKDB Login ausgewählt werden.

Bürgerkonto-Login als Externer Benutzer einrichten. (Schritt 2)

Im nächsten Schritt muss über den Button "Konfiguration hinzufügen" eine Konfiguration hinzugefügt werden.

Bürgerkonto-Login als Externer Benutzer einrichten. (Schritt 3)

Im letzten Schritt besteht die Möglichkeit die Konfiguration individuell anzupassen.
Dazu können folgende Einstellungen getroffen werden:

LoginTyp: Mit dieser Einstellung lassen sich die Arten der zurück gelieferten Daten festlegen.; Ist als Wert Person definiert, so können nur personenbezogene Daten zurückgeliefert werden.; Ist Organisation definiert, so ist es nur möglich organisationsbezogene Daten zurückzuliefern. Das heißt ein Login als natürliche Person ist nicht möglich.; Ist dieser Parameter nicht konfiguriert, so kann der Nutzer selbst bestimmen, welche Datenart (personen- oder organisationsbezogen) er zurück liefern möchte.
AuthTyp: Über diese Einstellung kann das geforderte Authentisierungsverfahren festgelegt werden.; Entweder mit Authega-Zertifikat (Wert: Authega) oder Personalausweis (Wert: NPA).; Ist nichts gesetzt oder das Attribut nicht vorhanden, so werden dem Nutzer alle möglichen Authentisierungsverfahren zur Auswahl angeboten.

Designer-Element: Bürgerkonto Daten Vorlage

Formularvorlage AKDB Basisdienste

Um die Daten aus dem Bürgerservice-Portal im Formular anzuzeigen, existieren zwei Vorlagen Bürgerkonto personenbezogene Daten und Bürgerkonto organisationsbezogene Daten. Die Felder innerhalb dieser Vorlagen sind so konfiguriert, dass sie eine automatische Zuordnung und damit die Anzeige der zurückgelieferten Daten ermöglichen. Die jeweilige Vorlage ist je nach der eingestellten Art der Rückgabedaten am AKDB Bürgerkonto-Button zu wählen. Bei Nutzung der eingangs erwähnten Formular-Templates, sind beide Designer-Vorlagen bereits eingebunden und werden nach anzuzeigender Datenart ein- oder ausgeblendet.

Die vom Bürgerservice-Portal zurückgelieferten Daten können mittels JavaScript auch anderweitig weiterverarbeitet werden. Dafür werden sie in Form einer JSON-Struktur im Zielformular zur Verfügung gestellt. Die JSON Struktur kann über folgende JavaScript-Variable ausgelesen werden:

XFC_METADATA.pluginResults.AKDBLoginAnalyzer

Die nachfolgenden Tabelle listet alle Formularfeld-Namen auf, die in einem Formular genutzt werden können, um die Daten vom Bürgerservice-Portal in Formular-Elementen anzuzeigen. Einige Informationen sind über verschiedene Parameter-Namen abrufbar (einen englisch-sprachigen und einen deutsch-sprachigen Namen), in solchen Fällen können beide Benamungen gleichwertig genutzt werden.

Parameter, welche nur bei einer personenbezogenen Anmeldung vorhanden sind, sind mit (PBA) und die die nur bei einer organisationsbezogenen Anmeldung vorhanden sind, mit (OBA) gekennzeichnet.
Ist keine extra Kennzeichnung vorhanden, so ist der Parameter in beiden Bereichen vorhanden.

Parameter	Beschreibung
BPK	Bereichsspezifisches Personenkennzeichen (in verschlüsselter Form)
BPK_Decoded	Bereichsspezifisches Personenkennzeichen (in entschlüsselter Form)
PostboxId	Postkorb-ID des Nutzers. Muss bei Anbindung des Postkorbs verwendet werden.
Email (PBA) tfAntragstellerEmail (PBA)	Email-Adresse
Gender	Anrede als numerischer Wert nach ISO 5218:2004
GenderName	Lesbarer Text für Geschlechter-Code aus Attribut „gender“. Mögliche Werte: männlich, weiblich
Salutation tfAntragstellerAnrede (PBA) selAntragstellerAnrede (PBA)	Anrede, wird mit Hilfe des Geschlechter-Code aus Attribut „gender“ erzeugt. Mögliche Werte: Herr, Frau, Nicht bekannt
PersonalTitle (PBA) tfAntragstellerTitel (PBA)	Akademischer Titel
FirstName tfAntragstellerVorname (PBA)	Vorname
LastName tfAntragstellerName (PBA)	Nachname
ZipCode (PBA) tfAntragstellerPLZ (PBA)	Postleitzahl
Address (PBA) tfAntragstellerAdresse (PBA)	Adresse bestehend aus Strasse und Hausnummer
City (PBA) tfAntragstellerOrt (PBA)	Ort
BirthDate tfAntragstellerGeburtsdatum (PBA)	Geburtsdatum im Format: dd.MM.yyyy
PlaceOfBirth tfAntragstellerGeburtsort (PBA)	Geburtsort
TelephoneNumber tfAntragstellerTelefon (PBA)	Telefonnummer
tfOrgVertreterVorname (OBA)	Vorname der Person, welche der hinterlegten Organisation angehört und über deren Account die Anmeldung erfolgte.
tfOrgVertreterName (OBA)	Nachname der Person, welche der hinterlegten Organisation angehört und über deren Account die Anmeldung erfolgte.
tfOrgVertreterTitel (OBA)	Akademischer Titel der Person, welche der hinterlegten Organisation angehört und über deren Account die Anmeldung erfolgte.
tfOrgVertreterAnrede (OBA) selOrgVertreterAnrede (OBA)	Anrede für die Person, welche der hinterlegten Organisation angehört und über deren Account die Anmeldung erfolgte. Anrede, wird mit Hilfe des Geschlechter-Code aus Attribut „gender“ erzeugt. Mögliche Werte: Herr, Frau, Nicht bekannt
tfOrgVertreterGeburtsdatum (OBA)	Akademischer Titel der Person, welche der hinterlegten Organisation angehört und über deren Account die Anmeldung erfolgte.
tfOrgVertreterGeburtsort (OBA)	Geburtsort der Person, welche der hinterlegten Organisation angehört und über deren Account die Anmeldung erfolgte.
tfOrgEmail (OBA)	E-Mail Adresse der angemeldeten Person, welche diese im Unternehmen hat. (Kann von der E-Mail Adresse am personenbezogenen Account abweichen.)
tfOrgVertreterTelefon (OBA)	Telefonnummer der Person, welche der hinterlegten Organisation angehört und über deren Account die Anmeldung erfolgte.
tfOrgStrasse (OBA)	Strasse
tfOrgHausnummer (OBA)	Hausnummer
tfOrgHausnummerZusatz (OBA)	Hausnummern Zusatz
tfOrgAdressZusatz (OBA)	Adress-Zusatz
tfOrgPLZ (OBA)	PLZ
tfOrgOrt (OBA)	Ort
tfOrgName (OBA)	Name der Organisation (mit Rechtsform)
tfOrgID (OBA)	Organisations-ID
Rechtsform (OBA)	Rechtsform der Organisation
tfOrgRegisterOrt (OBA)	Register(gerichts)-Ort
tfOrgRegisterNummer (OBA)	Registernummer
TrustLevel	Vertrauensniveau, gibt Auskunft über gewählte Authentifizierungsmethode: STORK-QAA-Level-1: Authentifizierung mittels Benutzername / Passwort STORK-QAA-Level-3: Authentifizierung mittels Authega Zertifikat STORK-QAA-Level-4: Authentifizierung mittels nPA
NPA_Address (PBA)	Adresse, wie sie auf dem NPA vermerkt ist (alles in Großbuchstaben)
NPA_City (PBA)	Ort, wie er auf dem NPA vermerkt ist (alles in Großbuchstaben)
NPA_FirstName	Vorname, wie er auf dem NPA vermerkt ist (alles in Großbuchstaben)
NPA_LastName	Nachname, wie er auf dem NPA vermerkt ist (alles in Großbuchstaben)
NPA_PersonalTitle	Akademischer Titel, wie er auf dem NPA vermerkt ist (alles in Großbuchstaben)
IsIndividualPerson	Liefert den Wert true, wenn es sich bei den Daten aus dem Bürgerkonto um personenbezogene Daten handelt, sonst false.
IsOrganization	Liefert den Wert true, wenn es sich bei den Daten aus dem Bürgerkonto um organisationsbezogene Daten handelt, sonst false.

Hinweis:
Wenn am Formular-Element AKDB Bürgerkonto ein Bürgerdaten Parameter-Suffix vergeben wurde, so muss dieses an die jeweiligen Formular-Elementnamen angefügt werden, damit eine Vorbelegung erfolgreich durchgeführt werden kann.

Beispiel:
Wenn als Suffix "_Person2" definiert wurde, so ergibt sich beim Vornamen der Formular-Elementname "tfAntragstellerVorname_Person2".

Darstellung des genutzten Authentifizierungsverfahren

Darstellung des verwendeten Vertrauensniveaus an der Bürgerkonto Daten Vorlage

Bei Nutzung der Bürgerkonto Daten Vorlagen ist nach dem Absenden des Formulars, bei Wiederanzeige des Formular im Postfach, das durch den Nutzer verwendete Authentifizierungsverfahren anhand einer visuellen Markierung ersichtlich.

Für die einzelnen Vertrauensniveaus existieren folgende Beschriftungen:

Level 1 (Authentifizierung mittels Benutzername / Passwort): Standard
Level 3 (Authentifizierung mittels Authega Zertifikat): Authega
Level 4 (Authentifizierung mittels nPA): Personalausweis

Wenn keine visuelle Markierung gewünscht ist, so kann dies durch ein zusätzliches Attribut „noRibbon“ am Vorlagen-Fieldset unterbunden werden

AKDB Postkorbanbindung in der Statusverarbeitung

Für die Anbindung zum Versand von Postkorbnachrichten wird das Aktions-Plugin AKDB:Postkorbnachricht senden zur Verfügung gestellt.
Mittels dieser Plugin-Aktion, können ähnlich einer E-Mail Aktion, Nachrichten an den Postkorb der AKDB weitergeleitet werden.

Die Konfigurationsoberfläche des Aktions-Plugins ist in einzelne Bereiche unterteilt die nachfolgend kurz beschrieben werden.

Einstellungen für Absender und Empfänger

Dienst (Pflicht): Wird als Information in der Postkorb-Ansicht im Bürgerservice-Portal verwendet.
Mandant (Pflicht): Wird als Information in der Postkorb-Ansicht im Bürgerservice-Portal verwendet.
Absender-Link: Falls sich die Angabe im Feld Mandant auf einen Mandanten bezieht, der nicht im Bürgerservice-Portal registriert ist, kann über den Absender-Link ein Link mitgegeben werden, mit dem der Mandant bei der Anzeige im AKDB Postkorb verlinkt wird.
Postkorb ID aus den Vorgangsdaten ermitteln?: Diese Angabe dient zur Bestimmung der Postkorb-ID. Über die Postkorb-ID wird das genaue Ziel für den Nachrichtenversand bestimmt, also der Nachrichten-Empfänger. Bei einem AKDB Bürgerkonto-Login wird die Postkorb-ID immer mit übermittelt und standardmäßig am Formulareingang hinterlegt. Für den Fall, dass es mehrere konfigurierte Anmeldungen innerhalb eines Formulars gibt, kann hier die Auswahl über den Bürgerdaten Parameter-Suffix eingegrenzt werden. Darüber hinaus ist es möglich die Postkorb-ID fest oder über einen Platzhalter ([%$POSTKORB_ID%]) zu definieren. (Der Platzhalter wird über das Plugin zur Verfügung gestellt und kann in der Statusverarbeitung verwendet werden.)

Konfiguration des Nachrichteninhalts

Konfiguration von Betreff, Nachrichteninhalt und Anhängen

Betreff (Pflicht)

Nahrichtenbetreff, es werden Platzhalter unterstützt.

Inhalt (Pflicht)

Nachrichtentext, es werden Platzhalter unterstützt.

Anhänge

Hier können Dateien als Attachments an die Postkorb-Nachricht gehangen werden.

Zur Auswahl stehen dabei:

Upload: bezieht sich auf alle Dateianhänge, die über das Formular hochgeladen wurden
Workflow: bezieht sich auf alle Dateianhänge, die über den aktuellen FORMCYCLE Workflow hochgeladen wurden.
Posteingang: bezieht sich auf alle Dateianhänge, die über das Postfach hochgeladen wurden.; Unterstützte Dateiformate sind: PDF, HTML, Plaintext, MS Word, JPEG, GIF, PNG

Achtung:
Die Schnittstelle zum Postkorb der AKDB unterstützt dabei maximal 5 Anhänge pro Nachricht mit je 2 MB Maximalgröße.

Bedingte Ausführung der AKDB:Postkorbnachricht senden-Aktion

Konfiguration einer Bedingung für Ausführung der Aktion AKDB:Postkorbnachricht senden

Um eine Nachricht an den Postkorb-Schnittstelle der AKDB zu übermitteln ist eine so genannte "Postkorb-ID" notwendig. Ähnlich einer E-Mail-Adresse stellt sie ein Merkmal dar, womit das Postfach eines Nutzers eindeutig im System der AKDB identifiziert werden kann. Die Ermittlung der Postkorb-ID eines Benutzers erfolgt dabei automatisch beim Login am Bürgerservice-Portal der AKDB, wodurch dieser Identifikator dann im weiteren Formularprozess zur Verfügung steht.
Dies bedeutet aber auch, dass wenn in einem Formularprozess kein zwingender Bürgerkonto-Login erfolgt, die Postkorb-ID nicht in der Statusverarbeitung vorhanden ist.
Damit die Statusverarbeitung bei Verwendung der Aktion AKDB:Postkorbnachricht senden nicht in einem Fehler resultiert, ist deshalb die Konfiguration einer entsprechenden Ausführungs-Bedingung sinnvoll.

Das nachfolgende Quellcode-Beispiel zeigt das Abprüfen der Postkorb-ID auf das Vorhandensein eines Wertes, durch einen regulären Ausdruck. Die aktuelle Postkorb-ID wird dabei mittels eines System-Platzhalters im Prüfausdruck zur Verfügung gestellt.

REGEX([%$POSTKORB_ID%]=^.+$)

Erweitere Bedingungsprüfung bei Verwendung unterschiedlicher Login-Arten (personenbezogenes bzw. organisationsbezogenes Login)

Wenn in einem Formular beide Login-Arten (personenbezogenes und organisationsbezogenes Login) zugelassen sind und man unterschiedliche Nachrichten an den Postkorb senden möchte, so ist dies ebenfalls möglich.
Im Formular müssen dann versteckte Eingabefelder mit den Element-Namen IsIndividualPerson und IsOrganization vorhanden sein.
(Dies ist automatisch der Fall, wenn die entsprechenden Vorlagen Bürgerkonto personenbezogene Daten und Bürgerkonto organisationsbezogene Daten verwendet werden).

Die Konfiguration einer Ausführungs-Bedingung an einer Aktion AKDB:Postkorbnachricht senden für eine personenbezogene Anmeldung wäre dann folgendermaßen:

REGEX([%IsIndividualPerson%]=true) REGEX([%$POSTKORB_ID%]=^.+$)

Bei Nutzung einer organisationsbezogenen Anmeldung ist folgende Bedingung zu konfigurieren:

REGEX([%IsOrganization%]=true) REGEX([%$POSTKORB_ID%]=^.+$)

Bitte beachten Sie, dass Bedingungen vom Typ "Mehrere Bedinungen" werden immer UND-Verknüpft sind. Somit müssen alle REGEX-Bedingungen erfüllt sein, damit die Aktion ausgeführt wird.

Tags: