Portalintegration

## 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.

4

5

---

6

7

## Eingebetteter Modus, z.B. IFrame

8

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.

10

11

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

12

13

**Für Assistenten gilt**:

14

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.

**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

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

22

23

**Beispiele ohne Fehlermeldung auf Clientseite:**

24

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>

27

28

**Beispiele mit Fehlermeldung auf Clientseite:**

29

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}>

## 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|Main.03_Steuerungsprozess.02_Vorbefüllung.01_Postdata]] bzw. [[SecurePostData|doc:Main.03_Steuerungsprozess.02_Vorbefüllung.02_SecurePostdata.WebHome]] mitgegeben werden.

36

37

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.

39

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]].

### Parameter

* **successUrl**

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)

47

* **cancelUrl**

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)

49

* **errorUrl**

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.

52

* **notifyUrl**

53

Detailbeschreibung: siehe nachfolgende Abschnitte

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)

55

56

### Hashwert bei Rücksprung-URLs

57

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:

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

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.

70

71

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

72

73

```Javascript

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

```

81

82

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

83

84

```

85

Param1|Param2|Param3|Param4|...

86

```

87

88

## Übergabe von eID-Daten aus dem Portal

89

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:

```xml

</PlaceOfBirth>

</PlaceOfResidence>

</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

130

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.

---

## 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.

---

## Nutzung der eID-Integration im Portal (_experimentell_)

142

143

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

144

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.

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

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:

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)

> _**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

165

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.

167

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

172

## Steuerung der Einreichungsbestätigungsseite

173

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.

Wiki-Quellcode von Portalintegration