Wiki-Quellcode von Portalintegration

Zuletzt geändert von MACH formsolutions am 08.10.2025

version	line-number	content
1.1	1	## Allgemeines
	2
8.1	3	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.
1.1	4
8.1	5	---
1.1	6
11.1	7	## Eingebetteter Modus, z.B. IFrame
1.1	8
12.1	9	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.
1.1	10
9.1	11	Für diese Fälle verfügt die Software über einen Einbettungsmodus, der im folgenden erklärt wird.
1.1	12
9.1	13	Für Assistenten gilt:
1.1	14
9.1	15	* 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.
1.1	16
9.1	17	Für PDF gilt:
1.1	18
9.1	19	* Das Logo und die Fußzeile mit Impressum, Datenschutzerklärung und Erklärung zur Barrierefreiheit müssen von der Rahmenseite bereitgestellt werden
11.1	20	* Die Veröffentlichung darf nicht mit der Option "Einwilligungserklärung anzeigen" erstellt werden
	21	* Die Veröffentlichung muss mit der Funktion "Parametrisierten Link generieren" abgeschlossen werden
9.1	22
	23	Beispiele ohne Fehlermeldung auf Clientseite:
	24
10.1	25	* Assistent: [https://{url}/metaform/FormSolutions/sid/assistant/{SID}?embedded=true](https://{url}/metaform/FormSolutions/sid/assistant/{SID}?embedded=true)
	26	* PDF: [https://{url}/servlet/de.formsolutions.FillServlet?param1...&consent_type=NONE&1=q.pdf](https://{url}/servlet/de.formsolutions.FillServlet?param1...&consent_type=NONE&1=q.pdf)<https://{url}/servlet/de.formsolutions.FillServlet?param1...&consent_type=NONE&1=q.pdf>
9.1	27
	28	Beispiele mit Fehlermeldung auf Clientseite:
	29
10.1	30	* Assistent: [https://{url}/metaform/FormSolutions/sid/assistant/{SID}](https://{url}/metaform/FormSolutions/sid/assistant/{SID})
	31	* PDF: [https://{url}/servlet/de.formsolutions.FillServlet?param1...&consent_type=DISPLAY&j=k.pdf](https://{url}/servlet/de.formsolutions.FillServlet?param1...&consent_type=DISPLAY&j=k.pdf)<https://{url}/metaform/FormSolutions/sid/assistant/{SID}>
9.1	32
1.1	33	## Rücksprung-URLs
	34
28.1	35	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 formsolutions bereitgestellten Schnittstellen [[Postdata\|Main.03_Steuerungsprozess.02_Vorbefüllung.01_Postdata]] bzw. [[SecurePostData\|doc:Main.03_Steuerungsprozess.02_Vorbefüllung.02_SecurePostdata.WebHome]] mitgegeben werden.
1.1	36
18.1	37	{{warning}}
24.1	38	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.
18.1	39
25.1	40	Sollte die Sperrung noch nicht aktiv sein, finden Sie die Anleitung bzw. den Patch in diesem [[Dokumentationsartikel\|doc:Main.01_Systemadministration.05_Anleitungen.Open Redirects.WebHome]].
18.1	41	{{/warning}}
	42
	43	### Parameter
	44
8.1	45	* successUrl
22.1	46	Nach erfolgreicher Einreichung wird auf diese URL weitergeleitet. Beispiel: [https://ofs.form-solutions.de:443/metaform/Form-Solutions/sid/assistant/5b9b53dad5de93019b42df8c?successUrl=https%3A%2F%2Fwww.testurl.de](https://ofs.form-solutions.de:443/metaform/Form-Solutions/sid/assistant/5b9b53dad5de93019b42df8c?successUrl=https%3A%2F%2Fwww.testurl.de)
8.1	47	* cancelUrl
22.1	48	Bricht der Anwender den Ausfüllvorgang mit einem Klick auf `Abbruch` ab, wird er anschließend auf diese URL weitergeleitet. Beispiel: [https://ofs.form-solutions.de:443/metaform/Form-Solutions/sid/assistant/5b9b53dad5de93019b42df8c?cancelUrl=https%3A%2F%2Fwww.testurl.de](https://ofs.form-solutions.de:443/metaform/Form-Solutions/sid/assistant/5b9b53dad5de93019b42df8c?cancelUrl=https%3A%2F%2Fwww.testurl.de)
8.1	49	* errorUrl
27.1	50	Tritt während des Ausfüllvorgangs oder beim Einreichen ein technischer Fehler auf, wird der Anwender auf diese URL weitergeleitet. Beispiel: [https://ofs.form-solutions.de:443/metaform/Form-Solutions/sid/assistant/5b9b53dad5de93019b42df8c?errorUrl=https%3A%2F%2Fwww.testurl.de](https://ofs.form-solutions.de:443/metaform/Form-Solutions/sid/assistant/5b9b53dad5de93019b42df8c?errorUrl=https%3A%2F%2Fwww.testurl.de)
	51	Für die genau Abfrage des aufgetretenen Fehlers kann auf die [[Error-API\|doc:Main.02_FSSchnittstellen.04_ErrorAPI.WebHome]] zugegriffen werden.
23.1	52	* notifyUrl
26.1	53	Detailbeschreibung: siehe nachfolgende Abschnitte
23.1	54	[solutions.de:443/metaform/Form-Solutions/sid/assistant/5b9b53dad5de93019b42df8c?notifyUrl=https%3A%2F%2Fwww.testurl.de](https://ofs.form-solutions.de:443/metaform/Form-Solutions/sid/assistant/5b9b53dad5de93019b42df8c?notifyUrl=https%3A%2F%2Fwww.testurl.de)
8.1	55
6.1	56	### Hashwert bei Rücksprung-URLs
	57
8.1	58	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:
6.1	59
	60	```
	61	- Es muss ein API-Key vorliegen, welcher eine der beiden folgenden Bedingungen erfüllt:
	62	- Der API-Key verfügt über das Recht "SecurePostData"
	63	- Der API-Key verfügt über das Recht "Unbegrenzt"
	64	- Für einen Mandanten liegt ein eindeutiger API-Key zur Nutzung der SecurePostData-Schnittstelle vor. Dies ist genau dann der Fall wenn:
	65	- Es ausschließlich einen API-Key mit dem Recht "SecurePostData" für einen Mandanten gibt
	66	- Es keinen API-Key mit dem Recht "SecurePostData" gibt, dafür ausschließlich einen API-Key mit dem Recht "Unbegrenzt"
	67	```
	68
9.1	69	Ist die Eindeutigkeit des API-Key's nicht gewährleistet, so wird kein Hashwert gebildet. Die [Pflege der API-Key's](https://wiki.form-solutions.de/wiki/docwiki/view/Main/07_Einstellungen-Fachadministration/04_Server-Administration/) obliegt dem jeweiligen Systemadministrator.
6.1	70
	71	Möchte man nun den Hashwert auf Seiten des konsumierenden Systems verifizieren, so kann folgender Verschlüsselungsmechanismus verwendet werden:
	72
8.1	73	```Javascript
6.1	74	SecretKeySpec keySpec = new SecretKeySpec(password.getBytes(StandardCharsets.UTF_8),
	75	"HmacSHA256");
	76	Mac mac = Mac.getInstance("HmacSHA256");
	77	mac.init(keySpec);
	78	byte[] rawHmac = mac.doFinal(hashObject.getBytes(StandardCharsets.UTF_8));
	79	return DatatypeConverter.printHexBinary(rawHmac).toLowerCase();
	80	```
8.1	81
6.1	82	Der Parameter "hashObject" bildet sich über alle in der Rücksprung-URL enthaltenen Parameter und ist wie folgt aufgebaut:
	83
8.1	84	```
6.1	85	Param1\|Param2\|Param3\|Param4\|...
	86	```
	87
1.1	88	## Übergabe von eID-Daten aus dem Portal
	89
8.1	90	Bei Verwendung der [[zweistufigen Vorbefüllung\|Main.03_Steuerungsprozess.02_Vorbefüllung.01_Postdata]] 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:
1.1	91
	92	```xml
	93	<EIDEntry>
	94	<AcademicTitle></AcademicTitle>
	95	<ArtisticName></ArtisticName>
	96	<AuthenticationType></AuthenticationType>
	97	<FamilyNames></FamilyNames>
	98	<GivenNames></GivenNames>
	99	<DateOfBirth></DateOfBirth>
	100	<PlaceOfBirth>
	101	<Street></Street>
	102	<StreetNumber></StreetNumber>
	103	<City></City>
	104	<Country></Country>
	105	<ZipCode></ZipCode>
	106	<FreetextPlace></FreetextPlace>
	107	</PlaceOfBirth>
	108	<PlaceOfResidence>
	109	<Street></Street>
	110	<StreetNumber></StreetNumber>
	111	<City></City>
	112	<Country></Country>
	113	<ZipCode></ZipCode>
	114	<FreetextPlace></FreetextPlace>
	115	</PlaceOfResidence>
	116	<DocumentValidityStatus></DocumentValidityStatus>
	117	<DocumentValidityReferenceDate></DocumentValidityReferenceDate>
	118	<IssuingState></IssuingState>
	119	<Pseudonym></Pseudonym>
	120	<DocumentType></DocumentType>
	121	<AgeCheck></AgeCheck>
	122	</EIDEntry>
	123	```
	124
	125	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.
	126
8.1	127	---
1.1	128
	129	## Zwischenspeichern bei eingebetteter Darstellung
	130
6.1	131	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.
1.1	132
8.1	133	---
1.1	134
	135	## Benachrichtigung bei Formulareinreichung
	136
	137	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.
	138
8.1	139	---
1.1	140
8.1	141	## Nutzung der eID-Integration im Portal (_experimentell_)
1.1	142
17.1	143	Die Integration der verschiedenen eID-Anbieter in ein Portal kann über eine vereinheitlichte Schnittstelle erfolgen.
1.1	144
8.1	145	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]
	146	Als Rückgabewert erhalten Sie eine cacheId, die Sie im Folgeschritt als Parameter `redirectID` mitgeben.
1.1	147
	148	Für den Aufruf der Cache-Schnittstelle ist eine Basic-Authentifizierung notwendig. Die entsprechenden Daten erhalten Sie nach Rücksprache.
	149
	150	Für den Start des EID-Prozesses wird der Anwender auf eine URL nach folgendem Muster weitergeleitet:
	151
	152	[https://vertrieb.form-solutions.de/administrationCenter/Form-Solutions/\<Kundennummer\>/eID/eIDMandatory?redirectID=\<redirectID\>](https://vertrieb.form-solutions.de/administrationCenter/Form-Solutions/XXXXXXXX-XXXX/eID/eIDMandatory?redirectID=12345)
	153
15.1	154	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:
1.1	155
	156	[https://vertrieb.form-solutions.de/administrationCenter/Form-Solutions/\<Kundennummer\>/eID/retrieve/\<eIDCacheID\>](https://vertrieb.form-solutions.de/administrationCenter/Form-Solutions/XXXXXXXXX-XXXX/eID/retrieve/12345678)
	157
8.1	158	> _Hinweis:_
	159	>
16.1	160	> Die eIDCacheID ist nur einmalig gültig. D.h. die Daten werden direkt nach dem Abruf auf dem MACH formsolutions System verworfen.
1.1	161
8.1	162	---
3.1	163
	164	## Einreichungssteuerung über ordnungsId
	165
16.1	166	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.
3.1	167
8.1	168	* Für die Portalanbieter ist es möglich die entsprechende OrdnungsId dann
	169	* Beim Abholen der Daten über die Submission-API kann man die entsprechende OrdnungsId unter den specialFieldValues einsehen.
	170	* Bei der Verwendung der OrdnungsId in Verbindung mit dem citkoPortal-Payment wird die OrdnungsId als Verwendungszweck verwendet.
	171
16.1	172	## Steuerung der Einreichungsbestätigungsseite
4.1	173
16.1	174	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\|Main.03_Steuerungsprozess.01_Einreichebestätigungsseite.]] eingesehen werden.