Portalintegration

Zuletzt geändert von MACH ProForms GmbH am 24.10.2024

Allgemeines

Um einen Antragsassistenten in ein Portal, CMS, Eigene Internetseite oder ähnlichem einzubinden, stellt wir mehrere Möglichkeiten bereit. Hierbei werden unterschiedliche Konfigurationsmöglichkeiten angeboten, um den Bezug zum aufrufenden System aufrechtzuerhalten.

Eingebetteter Modus, z.B. IFrame

Grundsätzlich ist der Webserver mit der Option "X-Frame-Options=deny" eingestellt. Dies führt dazu, dass der Request vom Webserver (MACH formsolutions) abgelehnt wird und der Client die Fehlermeldung "Refused to display {url} in a frame because it set 'X-Frame-Options' to 'deny'." ausgibt.

Für diese Fälle verfügt die Software über einen Einbettungsmodus, der im folgenden erklärt wird.

Für Assistenten gilt:

  • Den URL Parameter embedded=true ergänzen. Dieser sorgt sowohl für die Freigabe des Request im eingebetteten Modus als auch für eine reduzierte Darstellung der Assistenten. Diese lassen sich dadurch optisch besser in eine Rahmenumgebung integrieren. Dabei entfallen die Darstellung der Logos, sowie der Fußzeile mit Impressum und der Datenschutzerklärung.

Für PDF gilt:

  • Das Logo und die Fußzeile mit Impressum, Datenschutzerklärung und Erklärung zur Barrierefreiheit müssen von der Rahmenseite bereitgestellt werden
  • Die Veröffentlichung darf nicht mit der Option "Einwilligungserklärung anzeigen" erstellt werden
  • Die Veröffentlichung muss mit der Funktion "Parametrisierten Link generieren" abgeschlossen werden

Beispiele ohne Fehlermeldung auf Clientseite:

Beispiele mit Fehlermeldung auf Clientseite:

Rücksprung-URLs

Soll nach dem Ausfüllen oder beim Abbruch eines Assistenten z.B. wieder direkt ins Portal gesprungen werden, können beim Aufruf Rücksprung-URLs über die von MACH ProForms bereitgestellten Schnittstellen Postdata bzw. SecurePostData mitgegeben werden.

MACH formsolutions kann derzeit auch über die Mitgabe der Rücksprungadressen als GET-Parameter angesteuert werden. Wir empfehlen Ihnen, abzuwägen, ob diese Möglichkeit serverseitig durch den Betreiber der Software pauschal unterbunden wird.

Sollte die Sperrung noch nicht aktiv sein, finden Sie die Anleitung bzw. den Patch in diesem Dokumentationsartikel.

Parameter

Hashwert bei Rücksprung-URLs

Wird an eine Rücksprung-URL weitergeleitet, so bildet der Formularserver automatisch einen Hashwert über die einzelnen Parameter der Rücksprung-URL und hängt diesen als GET-Parameter mit der Bezeichnung "hash" an. Dieser Hashwert dient dem Zwecke der Manipulationssicherheit und obliegt folgenden Voraussetzungen:

- Es muss ein API-Key vorliegen, welcher eine der beiden folgenden Bedingungen erfüllt:
   - Der API-Key verfügt über das Recht "SecurePostData"
   - Der API-Key verfügt über das Recht "Unbegrenzt"
- Für einen Mandanten liegt ein eindeutiger API-Key zur Nutzung der SecurePostData-Schnittstelle vor. Dies ist genau dann der Fall wenn:
   - Es ausschließlich einen API-Key mit dem Recht "SecurePostData" für einen Mandanten gibt
   - Es keinen API-Key mit dem Recht "SecurePostData" gibt, dafür ausschließlich einen API-Key mit dem Recht "Unbegrenzt"

Ist die Eindeutigkeit des API-Key's nicht gewährleistet, so wird kein Hashwert gebildet. Die Pflege der API-Key's obliegt dem jeweiligen Systemadministrator.

Möchte man nun den Hashwert auf Seiten des konsumierenden Systems verifizieren, so kann folgender Verschlüsselungsmechanismus verwendet werden:

SecretKeySpec keySpec = new SecretKeySpec(password.getBytes(StandardCharsets.UTF_8),
 "HmacSHA256");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(keySpec);
byte[] rawHmac = mac.doFinal(hashObject.getBytes(StandardCharsets.UTF_8));
return DatatypeConverter.printHexBinary(rawHmac).toLowerCase();

Der Parameter "hashObject" bildet sich über alle in der Rücksprung-URL enthaltenen Parameter und ist wie folgt aufgebaut:

Param1|Param2|Param3|Param4|...

Übergabe von eID-Daten aus dem Portal

Bei Verwendung der zweistufigen Vorbefüllung können eID-Daten des Portals für den Anwender unveränderbar an den Ausfüllassistenten übergeben werden. Dazu müssen die Daten in folgende XML-Struktur überführt werden:

<EIDEntry>
   <AcademicTitle></AcademicTitle>
   <ArtisticName></ArtisticName>
   <AuthenticationType></AuthenticationType>
   <FamilyNames></FamilyNames>
   <GivenNames></GivenNames>
   <DateOfBirth></DateOfBirth>
   <PlaceOfBirth>
       <Street></Street>
       <StreetNumber></StreetNumber>
       <City></City>
       <Country></Country>
       <ZipCode></ZipCode>
       <FreetextPlace></FreetextPlace>
   </PlaceOfBirth>
   <PlaceOfResidence>
       <Street></Street>
       <StreetNumber></StreetNumber>
       <City></City>
       <Country></Country>
       <ZipCode></ZipCode>
       <FreetextPlace></FreetextPlace>
   </PlaceOfResidence>
   <DocumentValidityStatus></DocumentValidityStatus>
   <DocumentValidityReferenceDate></DocumentValidityReferenceDate>
   <IssuingState></IssuingState>
   <Pseudonym></Pseudonym>
   <DocumentType></DocumentType>
   <AgeCheck></AgeCheck>
</EIDEntry>

Sollten nicht alle Daten vorliegen, können die leeren Elemente weggelassen werden. Anschließend wird das gesamte XML base64-kodiert und als Parameter externalEIDData übergeben. Dies hat zur Folge, dass die Daten zum Teil zur Vorbefüllung herangezogen werden und dass diese unmanipulierbar zur Einreichung durchgeschleust werden. Dies lässt sich nach der Einreichung direkt am befüllten/erzeugten PDF und am Inbox-Eintrag am NPA-Logo erkennen.

Zwischenspeichern bei eingebetteter Darstellung

Wird ein Assistent im iFrame dargestellt und zwischengespeichert, so wird der Assistent beim Fortsetzen des Ausfüllvorgangs nicht innerhalb eines iFrames, sondern eigenständig gestartet. Dieses Verhalten kann mit der Hilfe einer restartURL verhindert werden. Wird beim eingebetteten Start des Assistenten eine solche restartURL mitgegeben, so werden beim Fortsetzen zuerst die zwischengespeicherten Daten an unseren Cache übergeben und anschließend an die restartURL weitergeleitet. Zusätzlich wird die restartURL um einen Parameter contentURL ergänzt. Die einbettende Seite kann dann diese contentURL für den iFrame verwenden, um den Ausfüllvorgang fortzusetzen.

Benachrichtigung bei Formulareinreichung

Soll ein Portal bei einer Formulareinreichung informiert werden, um z.B. einen eigenen Posteingang zu aktualisieren, kann beim Start eines Assistenten eine notifyUrl übergeben werden. Bei einer erfolgreichen Einreichung wird an diese URL ein POST gesendet. Der Inhalt des POST entspricht einer URL der Rest-API, unter welcher die eingegangenen Daten u.a. abgerufen werden können. Zusätzlich wird an die notifyUrl ein Parameter transactionId mit der Vorgangsnummer angehängt.

Nutzung der eID-Integration im Portal (experimentell)

Die Integration der verschiedenen eID-Anbieter in ein Portal kann über eine vereinheitlichte Schnittstelle erfolgen.

Dazu wird in einem ersten Schritt die Redirect-URL als request-Body an die folgende URL übergeben: [https://pdf.form-solutions.net/administrationCenter/Form-Solutions/<Kundenummer>/api/cache]
Als Rückgabewert erhalten Sie eine cacheId, die Sie im Folgeschritt als Parameter redirectID mitgeben.

Für den Aufruf der Cache-Schnittstelle ist eine Basic-Authentifizierung notwendig. Die entsprechenden Daten erhalten Sie nach Rücksprache.

Für den Start des EID-Prozesses wird der Anwender auf eine URL nach folgendem Muster weitergeleitet:

https://vertrieb.form-solutions.de/administrationCenter/Form-Solutions/\<Kundennummer\>/eID/eIDMandatory?redirectID=\<redirectID\>

Für die gewählte Kundennnummer muss dabei im MACH formsolutions System eine eID-Konfiguration hinterlegt sein. Nach dem Erfragen der eID-Daten wird der Anwender an die übergebene URL weitergeleitet. Dabei wird diesr eIDCacheID erer um den zusätzlichen Parametegänzt. Mit dem Wert dieses Parameters können nun die eID-Daten im XML-Format (siehe "Übergabe von eID-Daten aus dem Portal") abgerufen werden. Die dazugehörige URL entspricht folgendem Muster:

https://vertrieb.form-solutions.de/administrationCenter/Form-Solutions/\<Kundennummer\>/eID/retrieve/\<eIDCacheID\>

Hinweis:
Die eIDCacheID ist nur einmalig gültig. D.h. die Daten werden direkt nach dem Abruf auf dem MACH formsolutions System verworfen.

Einreichungssteuerung über ordnungsId

Durch die Übergabe einer ordnungsId über die postData oder securePostData-Schnittstelle können doppelte Einreichungen unterbunden werden. Dem Bürger wird eine in solch einem Fall entsprechende Fehlermeldung angezeigt.

  • Für die Portalanbieter ist es möglich die entsprechende OrdnungsId dann
  • Beim Abholen der Daten über die Submission-API kann man die entsprechende OrdnungsId unter den specialFieldValues einsehen.
  • Bei der Verwendung der OrdnungsId in Verbindung mit dem citkoPortal-Payment wird die OrdnungsId als Verwendungszweck verwendet.

Steuerung der Einreichungsbestätigungsseite

Der Formularserver bietet die Möglichkeit die am Ende angezeigte Einreichungsbestätigungsseite über diverse Parameter konfigurierbar zu gestalten. Eine genaue Auflistung der Parameter sowie deren Funktionen können hier eingesehen werden.

Tags:

Navigation