Zum Inhalt springen

Wiki-Quellcode von Portalintegration

Version 1.1 von MACH ProForms GmbH am 08.10.2020
Zeige letzte Bearbeiter
1 ## Allgemeines
2
3 Um einen Antragsassistnten in ein Portal einzubinden, stellt Form-Solutions mehrere Möglichkeiten bereit. Hierbei werden unterschiedliche Konfigurationsmöglichkeiten angeboten, um den Bezug zum entsprechenden Portal aufrecht zu erhalten.
4
5 ___
6
7 ## Eingebetteter Modus
8
9 Ein beliebiger Vorschau- oder Veröffentlichungslink eines Assistenten kann um den URL-Parameter `embedded=true` ergänzt werden, um eine reduzierte Darstellung zu veranlassen. Diese lässt sich optisch besser per Iframe in eine Rahmenumgebung integrieren. Dabei entfallen die Darstellung der Logos, sowie der Fußzeile mit Impressum und Datenschutzerklärung.
10
11 > ***Hinweis:***<br/>
12 > Das Logo und die Fußzeile mit Impressum, Datenschutzerklärung und Erklärung zur Barrierefreiheit müssen von der Rahmenseite bereitgestellt werden.
13
14 **Beispiele:**
15
16 <https://vertrieb.form-solutions.de/metaform/Form-Solutions/?oID=22222222-2222&assistant=AS_940000&version=26&userId=77777777-0000-0001&releaseOrganizationID=77777777-0000&embedded=true>
17
18 [https://vertrieb.form-solutions.de/metaform/FormSolutions/sid/assistant/\<SID\>?embedded=true](https://vertrieb.form-solutions.de/metaform/FormSolutions/sid/assistant/SID?embedded=true)
19
20 ## Rücksprung-URLs
21
22 Soll nach dem Ausfüllen oder beim Abbruch eines Assistenten wieder direkt ins Portal gesprungen werden, können beim Aufruf verschiedene Rücksprung-URLs über die von Form-Solutions bereitgestellten Schnittstellen z.B. [[Postdata|Main.02_FSSchnittstellen.03_Steuerungsprozess.02_Vorbefüllung.01_Postdata]] mitgegeben werden.
23
24 - **successUrl**<br/>
25 Nach erfolgreicher Einreichung wird auf diese URL weitergeleitet.
26 Beispiel: https://ofs.form-solutions.de:443/metaform/Form-Solutions/sid/assistant/5b9b53dad5de93019b42df8c?successrUrl=https://www.testurl.de
27 > ***Achtung:***<br/>
28 > Dieser Parameter kann auch über die Postdata Schnittstelle mitgegeben werden.
29
30 - **cancelUrl**<br/>
31 Bricht der Anwender den Ausfüllvorgang mit einem Klick auf `Abbruch` ab, wird er anschließend auf diese URL weitergeleitet.
32 Beispiel: https://ofs.form-solutions.de:443/metaform/Form-Solutions/sid/assistant/5b9b53dad5de93019b42df8c?cancelUrl=https://www.testurl.de
33 > ***Achtung:***<br/>
34 > Dieser Parameter kann auch über die Postdata Schnittstelle mitgegeben werden.
35
36 - **errorUrl**<br/>
37 Tritt während des Ausfüllvorgangs oder beim Einreichen ein technischer Fehler auf, wird der Anwender auf diese URL weitergeleitet.
38 Beispiel: https://ofs.form-solutions.de:443/metaform/Form-Solutions/sid/assistant/5b9b53dad5de93019b42df8c?errorUrl=https://www.testurl.de
39 > ***Achtung:***<br/>
40 > Dieser Parameter kann auch über die Postdata Schnittstelle mitgegeben werden.
41
42 ___
43
44 ## Übergabe von eID-Daten aus dem Portal
45
46 Bei Verwendung der [[zweistufigen Vorbefüllung|Main.02_FSSchnittstellen.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:
47
48 ```xml
49 <EIDEntry>
50 <AcademicTitle></AcademicTitle>
51 <ArtisticName></ArtisticName>
52 <AuthenticationType></AuthenticationType>
53 <FamilyNames></FamilyNames>
54 <GivenNames></GivenNames>
55 <DateOfBirth></DateOfBirth>
56 <PlaceOfBirth>
57 <Street></Street>
58 <StreetNumber></StreetNumber>
59 <City></City>
60 <Country></Country>
61 <ZipCode></ZipCode>
62 <FreetextPlace></FreetextPlace>
63 </PlaceOfBirth>
64 <PlaceOfResidence>
65 <Street></Street>
66 <StreetNumber></StreetNumber>
67 <City></City>
68 <Country></Country>
69 <ZipCode></ZipCode>
70 <FreetextPlace></FreetextPlace>
71 </PlaceOfResidence>
72 <DocumentValidityStatus></DocumentValidityStatus>
73 <DocumentValidityReferenceDate></DocumentValidityReferenceDate>
74 <IssuingState></IssuingState>
75 <Pseudonym></Pseudonym>
76 <DocumentType></DocumentType>
77 <AgeCheck></AgeCheck>
78 </EIDEntry>
79 ```
80
81 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.
82
83 ___
84
85 ## Zwischenspeichern bei eingebetteter Darstellung
86
87 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.
88
89 ___
90
91 ## Benachrichtigung bei Formulareinreichung
92
93 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.
94
95 ___
96
97 ## Nutzung der eID-Integration im Portal (*experimentell*)
98
99 Die Integration der verschiedenen eID-Anbieter in ein Portal kann über eine vereinheitlichte Form-Solutions-Schnittstelle erfolgen.
100
101 Dazu wird in einem ersten Schritt die Redirect-URL als request-Body an die folgende URL übergeben:
102 [https://pdf.form-solutions.net/administrationCenter/Form-Solutions/\<Kundenummer\>/api/cache]
103 Als Rückgabewert erhalten Sie eine cacheId, die Sie im Folgeschritt als Parameter `redirectID` mitgeben.
104
105 Für den Aufruf der Cache-Schnittstelle ist eine Basic-Authentifizierung notwendig. Die entsprechenden Daten erhalten Sie nach Rücksprache.
106
107 Für den Start des EID-Prozesses wird der Anwender auf eine URL nach folgendem Muster weitergeleitet:
108
109 [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)
110
111 Für die gewählte Kundennnummer muss dabei im Form-Solutions-System eine eID-Konfiguration hinterlegt sein. Nach dem Erfragen der eID-Daten wird der Anwender an die übergebene URL weitergeleitet. Dabei wird dieser um den zusätzlichen Parameter `eIDCacheID` ergä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.
112 Die dazugehörige URL entspricht folgendem Muster:
113
114 [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)
115
116 > ***Hinweis:***<br/>
117 > Die eIDCacheID ist nur einmalig gültig. D.h. die Daten werden direkt nach dem Abruf auf dem Form-Solutions-System verworfen.