From 032e24afdf3ad9a195bd29739f260cec5fa15ac8 Mon Sep 17 00:00:00 2001
From: David Schwarzmann <david.schwarzmann@codecentric.de>
Date: Mon, 21 Jun 2021 12:03:45 +0200
Subject: [PATCH] First rc/draft for sending submissions
---
docs/getting-started/authentication.mdx | 13 ++-
docs/getting-started/overview.md | 5 +-
docs/getting-started/sending/attachments.mdx | 77 +++++++++++++++++-
docs/getting-started/sending/data.mdx | 1 -
docs/getting-started/sending/overview.mdx | 34 ++++----
docs/getting-started/sending/submit.mdx | 83 ++++++++++----------
src/css/custom.css | 3 +-
7 files changed, 146 insertions(+), 70 deletions(-)
diff --git a/docs/getting-started/authentication.mdx b/docs/getting-started/authentication.mdx
index 85d05a65..934be0d8 100644
--- a/docs/getting-started/authentication.mdx
+++ b/docs/getting-started/authentication.mdx
@@ -29,21 +29,20 @@ Da ein Token **max. 24h** gültig ist, muss dieses rechtzeitig erneuert werden.
<TabItem value="curl">
- ```curl
+ ```bash
export OAUTH_URL=<URL>
export CLIENT_ID=<user>
export CLIENT_SECRET=<password>
- echo "{ \
- \"grant_type\": \"client_credentials\", \
- \"client_id\": \"$CLIENT_ID\", \
- \"client_secret\": \"$CLIENT_SECRET\" }" | \
- http -j --body --form post "$OAUTH_URL"
+ curl \
+ -H "Content-Type: application/json" \
+ --data "{ \"grant_type\": \"client_credentials\", \"client_id\": \"$CLIENT_ID\", \"client_secret\": \"$CLIENT_SECRET\"}" \
+ -X POST $OAUTH_URL
```
</TabItem>
</Tabs>
-:::caution :construction: Generierung eines User-Tokens für sendende Systeme
+:::caution Generierung eines User-Tokens für sendende Systeme
Für sendende Systeme reicht der OAuth-Access-Token nicht aus um Zugriff auf die API zu bekommen.
Sendende System müssen für den Zugriff auf die API ein User-Token generieren, welches Sie zusammen mit dem Access-Token an die API übermiteln müssen.
Dieser Access-Token ist als mit dem privaten Schlüssel des API Clients zu signieren, der dem öffentlichen Schlüssel des API-Clients entspricht (Siehe [Accountregistrierung](../account)).
diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md
index 434bd9ee..dcd429bc 100644
--- a/docs/getting-started/overview.md
+++ b/docs/getting-started/overview.md
@@ -1,11 +1,12 @@
# Ãœberblick
Im folgenden "Gettin Started"-Guide wird beschrieben, wie die ersten Interaktionen mit FIT-Connect ablaufen und FIT-Connect integriert werden kann.
+In den nächsten Abschnitten wird dann beschrieben, wie man sich gegenüber FIT-Connect authentifiziert, Daten für die Übertragung ver- und entschlüsselt werden, sowie welche Schritte für das einreichen bzw. empfangen von Einreichungen notwendig sind.
-:::info
+:::note Hinweis
Als Voraussetzungen hierfür ist es notwendig einen Account zu besitzen, wie in "[Registrierung und Account-Verwaltung](../account.md)" beschrieben ist.
:::
-In den nächsten Abschnitten wird dann beschrieben, wie
+
diff --git a/docs/getting-started/sending/attachments.mdx b/docs/getting-started/sending/attachments.mdx
index 70a69030..a5fa4cb0 100644
--- a/docs/getting-started/sending/attachments.mdx
+++ b/docs/getting-started/sending/attachments.mdx
@@ -1,8 +1,77 @@
---
-title: Anhänge
+title: 💬 Anlagen
sidebar_position: 3
---
-- Was ist ein Anhang?
-- Welche Typen von Anhängen sind unterstützt?
-- Wie werden Anhänge hochgeladen?
\ No newline at end of file
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
+
+Anlagen sind Bestandteil einer Einreichung, die nicht zwingend maschinenlesbar oder an Standards geknüpft sind. Sie können beim Anlegen einer Einreichung mit angekündigt und dann im weiteren Verlauf hochgeladen werden.
+
+In den untigen Ausschnitten wird dargestellt, wie eine bereits verschlüsselte Datei an eine Einreichung angehängt und hochgeladen werden kann.
+
+<Tabs
+ defaultValue="curl"
+ values={[
+ { label: 'curl', value: 'curl', },
+ { label: 'JavaScript', value: 'js', },
+ { label: 'Java (Spring)', value: 'java', },
+ { label: 'C#', value: 'csharp', },
+ ]
+}>
+<TabItem value="curl">
+
+ ```bash
+ $ export SERVICE_URL=<URL>
+ $ export JWT_TOKEN=eyJhbGciOiJIUzI1NiJ9.eyJJc3N1Z...NL-MKFrDGvn9TvkA
+ $ export SUBMISSION_ID=63f0c991-0635-4e18-8a4b-fb0c01de9f5c
+ $ export ATTACHMENT_ID=90ae8309-2102-4e81-a325-ceda480d0e9d
+ $ export ENC_FILE_CONTENT=6r4H2H_WIzCv8Pd-uetmcbK...iVBKF3ylHRUahmZ
+ $ curl \
+ -H "Authentication: Bearer $JWT_TOKEN" \
+ -H "Content-Type: application/jose" \
+ --data "$ENC_FILE_CONTENT" \
+ -X PUT $SERVICE_URL/submissions/$SUBMISSION_ID/attachments/$ATTACHMENT_ID
+ ```
+
+</TabItem>
+<TabItem value="js">
+
+ ```js
+ import axios from 'axios'
+
+ const baseUrl="<URL>"
+ const token="eyJhbGciOiJIUzI1NiJ9.eyJJc3N1Z...NL-MKFrDGvn9TvkA"
+ const submissionId="63f0c991-0635-4e18-8a4b-fb0c01de9f5c"
+ const attachmentId="90ae8309-2102-4e81-a325-ceda480d0e9d"
+ const data="6r4H2H_WIzCv8Pd-uetmcbK...iVBKF3ylHRUahmZ"
+
+ axios.put(
+ `/submissions/${submissionId}/attachments/${attachmentId}`,
+ data
+ {
+ baseURL,
+ timeout: 2000,
+ headers: {
+ 'Content-Type': 'application/jose',
+ 'Authentication': `Bearer ${token}`,
+ }
+ }
+ )
+ ```
+
+
+</TabItem>
+
+<TabItem value="java">
+ ```java
+ // TBD
+ ```
+</TabItem>
+
+<TabItem value="csharp">
+ ```java
+ // TBD
+ ```
+</TabItem>
+</Tabs>
\ No newline at end of file
diff --git a/docs/getting-started/sending/data.mdx b/docs/getting-started/sending/data.mdx
index 772fe093..c8438d64 100644
--- a/docs/getting-started/sending/data.mdx
+++ b/docs/getting-started/sending/data.mdx
@@ -5,4 +5,3 @@ sidebar_position: 4
- Wie werden Fachdaten erstellt?
- Wie werden Fachdaten genutzt?
--
\ No newline at end of file
diff --git a/docs/getting-started/sending/overview.mdx b/docs/getting-started/sending/overview.mdx
index 4acf650c..c3733050 100644
--- a/docs/getting-started/sending/overview.mdx
+++ b/docs/getting-started/sending/overview.mdx
@@ -7,15 +7,11 @@ import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
import Mermaid from '@site/src/components/Mermaid'
-Bei einer Einreichung eines Antrags reicht ein Onlineservice im Namen und Auftrag eines Endnutzers Fachdaten und/oder Anhänge bei einem Zustellpunkt ein.
+Bei einer Einreichung z. B. eines Antrags reicht ein Onlineservice im Namen und Auftrag eines Endnutzers Fachdaten und/oder Anhänge bei einem Zustellpunkt ein.
Hierfür benötigt der Onlinedienst die öffentlich verfügbaren Informationen eines Zustellpunktes, wie beispielsweise die Zustellpunkt-ID (`destinationId`) oder den JWK des Zustellpunktes. Wie man an diese Informationen gelangt ist im [folgenden](#get-destination-infos) genauer beschrieben.
FIT-Connect möchte einen sehr sicheren Übermittlungsweg bereitstellen, deswegen müssen alle Daten immer vom Browser des Users bis in die Behörde Ende-zu-Ende-Verschlüsselt übertragen werden. Das dafür benötigte Schlüsselmaterial wird auch über die FIT-Connect-API bereitgestellt und der Umgang damit im Weiteren erklärt.
-:::caution :speech_balloon: Nachfrage/Diskussionspunkt
- In Wieweit soll hier auch schon das berechtigungskonzept beinhaltet sein?
-:::
-
Nach Abgabe der Einreichung erhält man von dieser API einen "Application ID". Mithilfe dieser Application ID kann man den Event Log der Einreichung abrufen. Dieser Eventlog enthält eine Liste von Ereignes, ähnlich wie im Interface einer Paketverfolgung, mit denen der aktuelle Zustellungsstatus der Einreichung transparent wird. Also ob und wann ein Einreichung abgesendet, bei der Fachanwendung eingegangen bzw. bearbeitet wurde.
Außerdem gibt es die Möglichkeit beim Absenden eines Antrages einen Verschlüsselungschlüssel mitzugeben. Wenn dieser vorhanden ist, dann können durch die Behörden Antworten auf Anträge im FIT-Connect-System hinterlegt werden. Wenn eine Antwort hinterlegt wird, kann der User per Webhook, E-Mail oder Push-Notification darüber benachtichtigt werden und die verschlüsselte Antwort über die verwendete App oder Onlineservice abrufen.
@@ -29,21 +25,25 @@ sequenceDiagram;
C->>F: Einreichung anlegen & ankündigen;
C->>C: Anlagen verschlüsseln;
C->>F: Anlagen hochladen;
- C->>C: Antragsmetadaten befüllen & verschlüsseln;
+ C->>C: Metadaten befüllen & verschlüsseln;
C->>C: Fachdaten verschlüsseln;
- C->>F: Fachdaten & Antragsmetadaten hochladen und Einreichung absenden;
+ C->>F: Fachdaten & Metadaten hochladen und Einreichung absenden;
</Mermaid>
## Informationen des Zustellpunktes erhalten {#get-destination-infos}
-Ein Zustellpunkt
+:::danger Zustellpunkt
+
+Es ist bisher noch ungeklärt, wo die relevanten Informationen für einen Zustellpunkt abgefragt werden können. Dazu gehören:
- Schemata
- ID
- JWK
-TBD (aus Liste abfragen bzw. per E-Mail nachfragen)
+:speech_balloon: TBD: aus (de-)zentraler Excel-Liste abfragen bzw. per E-Mail nachfragen
+
+:::
## Eine neue Einreichung beginnen
@@ -60,12 +60,16 @@ Die Inhalte umfassen hierbei die Identifikatoren der Anhänge als UUIDs und die
}>
<TabItem value="curl">
-```text
-curl --data '{ "destinationId": "<UUID>", "announcedContentStructure": {} }' -H 'Content-Type: application/json' -H 'X-AnwenderId: <Id>' -X POST <URL>/applications/
-```
+```bash
+$ export SERVICE_URL=<URL>
+$ export JWT_TOKEN=eyJhbGciOiJIUzI1NiJ9.eyJJc3N1Z...NL-MKFrDGvn9TvkA
+$ export DESTINATION_ID=7a2668ad-3081-407c-9358-7ce4b6144b02
+$ curl \
+ -H "Authentication: Bearer $JWT_TOKEN" \
+ -H "Content-Type: application/json" \
+ --data "{ \"destinationId\": \"$DESTINATION_ID\", \"\" { \"data\": false, \"attachments\": [] } }" \
+ -X POST $SERVICE_URL/submissions
-```text
-curl --data '{ "destinationId": "7a2668ad-3081-407c-9358-7ce4b6144b02", "announcedContentStructure": {"data": "false", "attachments": []} }' -H 'Content-Type: application/json' -H 'X-AnwenderId: sender' -X POST localhost:8080/applications/
> {
"destinationId": "7a2668ad-3081-407c-9358-7ce4b6144b02",
"applicationId": "9d618546-0ff7-4e93-9f15-714e5dd1bf12"
@@ -85,7 +89,7 @@ curl --data '{ "destinationId": "7a2668ad-3081-407c-9358-7ce4b6144b02", "announc
```js
import axios from 'axios'
-const url = ''
+const url = '/submissions'
const data = {
destinationId: 'a1270669-ea36-4a0c-8f8f-c9d490e7f2bc',
announcedContentStructure: {
diff --git a/docs/getting-started/sending/submit.mdx b/docs/getting-started/sending/submit.mdx
index dba368ab..bbcee3eb 100644
--- a/docs/getting-started/sending/submit.mdx
+++ b/docs/getting-started/sending/submit.mdx
@@ -1,55 +1,33 @@
---
-title: Einreichung abschliessen
+title: 💬 Einreichung abschliessen
---
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
+import Mermaid from '@site/src/components/Mermaid'
-Abhängig von der angekündigten Struktur der Einreichung, kann diese abgeschlossen werden, wenn alle angekündigten Dokumente hochgeladen werden.
-Zusammen mit dem Abschluss können dann Fachdaten und müssen Metadaten mit übergeben werden. Ein Beispiel hierfür ist im folgenden Ausschnitt aufgezeigt:
+Abhängig von der angekündigten Struktur einer Einreichung, kann diese abgeschlossen werden, wenn alle angekündigten Dokumente hochgeladen wurden.
+Zusammen mit dem Abschluss können dann Fachdaten und müssen Metadaten mit hochgeladen werden. Ein Beispiel hierfür ist im folgenden Ausschnitt aufgezeigt:
<Tabs
defaultValue="curl"
values={[
{ label: 'curl', value: 'curl', },
- { label: 'Java', value: 'java', },
+ { label: 'Java (Spring)', value: 'java', },
{ label: 'JavaScript', value: 'js', },
]
}>
<TabItem value="curl">
-```text
-curl --data '{ "encryptedMetadata": "<jose-String>" }' -H 'Content-Type: application/json' -H 'X-AnwenderId: <Id>' -X POST <URL>/applications/<UUID>
-```
-
-```text
-curl --data '{ "encryptedMetadata": "eyJhbGciOiAiUlNBLU9BRVAiLCAiZW5jIjogIkExMjhDQkMtSFMyNTYifQ.SsLgP2bNKYDYGzHvLYY7rsVEBHSms6_jW-WfglHqD9giJhWwrOwqLZOaoOycsf_EBJCkHq9-vbxRb7WiNdy_C9J0_RnRRBGII6z_G4bVb18bkbJMeZMV6vpUut_iuRWoct_weg_VZ3iR2xMbl-yE8Hnc63pAGJcIwngfZ3sMX8rBeni_koxCc88LhioP8zRQxNkoNpvw-kTCz0xv6SU_zL8p79_-_2zilVyMt76Pc7WV46iI3EWIvP6SG04sguaTzrDXCLp6ykLGaXB7NRFJ5PJ9Lmh5yinAJzCdWQ-4XKKkNPorSiVmRiRSQ4z0S2eo2LtvqJhXCrghKpBNgbtnJQ.Awelp3ryBVpdFhRckQ-KKw.1MyZ-3nky1EFO4UgTB-9C2EHpYh1Z-ij0RbiuuMez70nIH7uqL9hlhskutO0oPjqdpmNc9glSmO9pheMH2DVag.Xccck85XZMvG-fAJ6oDnAw" }' -H 'Content-Type: application/json' -H 'X-AnwenderId: sender' -X POST localhost:8080/applications/9d618546-0ff7-4e93-9f15-714e5dd1bf12
-> {
- "destinationId": "7a2668ad-3081-407c-9358-7ce4b6144b02",
- "applicationId": "9d618546-0ff7-4e93-9f15-714e5dd1bf12",
- "attachments": [],
- "currentStatus": "forwarded",
- "encryptedMetadata": "eyJhbGciOiAiUlNBLU9BRVAiLCAiZW5jIjogIkExMjhDQkMtSFMyNTYifQ.SsLgP2bNKYDYGzHvLYY7rsVEBHSms6_jW-WfglHqD9giJhWwrOwqLZOaoOycsf_EBJCkHq9-vbxRb7WiNdy_C9J0_RnRRBGII6z_G4bVb18bkbJMeZMV6vpUut_iuRWoct_weg_VZ3iR2xMbl-yE8Hnc63pAGJcIwngfZ3sMX8rBeni_koxCc88LhioP8zRQxNkoNpvw-kTCz0xv6SU_zL8p79_-_2zilVyMt76Pc7WV46iI3EWIvP6SG04sguaTzrDXCLp6ykLGaXB7NRFJ5PJ9Lmh5yinAJzCdWQ-4XKKkNPorSiVmRiRSQ4z0S2eo2LtvqJhXCrghKpBNgbtnJQ.Awelp3ryBVpdFhRckQ-KKw.1MyZ-3nky1EFO4UgTB-9C2EHpYh1Z-ij0RbiuuMez70nIH7uqL9hlhskutO0oPjqdpmNc9glSmO9pheMH2DVag.Xccck85XZMvG-fAJ6oDnAw",
- "encryptedData": null,
- "statusHistory": [
- {
- "sourceState": "queued",
- "targetState": "forwarded",
- "details": "Callback von Destination 7a2668ad-3081-407c-9358-7ce4b6144b02 ausgelöst.",
- "timestamp": "2021-05-26T09:12:59.68968+02:00"
- },
- {
- "sourceState": "incomplete",
- "targetState": "queued",
- "details": "Einreichung versendet durch sender",
- "timestamp": "2021-05-26T09:12:58.728397+02:00"
- }
- ],
- "announcedContentStructure": {
- "data": false,
- "attachments": []
- }
-}
+```bash
+$ export SERVICE_URL=<URL>
+$ export JWT_TOKEN=eyJhbGciOiJIUzI1NiJ9.eyJJc3N1Z...NL-MKFrDGvn9TvkA
+$ export SUBMISSION_ID=63f0c991-0635-4e18-8a4b-fb0c01de9f5c
+$ curl \
+ -H "Authentication: Bearer $JWT_TOKEN" \
+ -H "Content-Type: application/json" \
+ --data '{ "encryptedMetadata": "6r4H2H_WIzCv8Pd-uetmcbK...iVBKF3ylHRUahmZ" }' \
+ -X POST $SERVICE_URL/submissions/$SUBMISSION_ID
```
</TabItem>
@@ -59,7 +37,6 @@ curl --data '{ "encryptedMetadata": "eyJhbGciOiAiUlNBLU9BRVAiLCAiZW5jIjogIkExMjh
```js
import axios from 'axios'
-const url = ''
const data = {
encryptedMetadata: 'mt2w8Pd-uetmcbKq0MqCw7zyBYj5HHDV1I7F0...',
encryptedData: 'eyJlbmMiOiJB...'
@@ -67,21 +44,47 @@ const data = {
const token = 'eyJhbGciOiJIUzI1NiJ9.eyJyYW5kb20iOiJyYW5kb20ifQ.lXckRWoWCUBG...w0HMEfE91jD1JPU'
axios.post(
- url,
+ '/submissions/63f0c991-0635-4e18-8a4b-fb0c01de9f5c',
data
{
baseURL,
timeout: 2000,
headers: {
- 'Authentication': `Bearer ${token}`
+ 'Content-Type': 'application/json',
+ 'Authentication': `Bearer ${token}`,
}
}
)
```
+</TabItem>
+<TabItem value="java">
+ ```java
+ TBD
+ ```
</TabItem>
</Tabs>
## Status abfragen
-Nachdem die Einreichung abgeschlossen wurde, kann der Status der Einreichung abgefragt werden. :construction:
+
+:::note Hinweis :construction:
+
+Die Abfrage des Status einer Einreichung ist noch unter Bearbeitung, da das Statusmodell gerade überarbeitet wird.
+
+:::
+
+Nachdem die Einreichung abgeschlossen wurde, kann der Status der Einreichung abgefragt werden.
+
+<Mermaid>
+stateDiagram-v2
+ [*] --> Incomplete
+ Incomplete --> Submitted
+ Submitted --> Forwarded
+ Forwarded --> Rejected
+ Forwarded --> Accepted
+ Submitted --> Accepted
+ Submitted --> Rejected
+ Accepted --> [*]
+ Rejected --> [*]
+</Mermaid>
\ No newline at end of file
diff --git a/src/css/custom.css b/src/css/custom.css
index 3c12a807..7fd63ea0 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -2,7 +2,8 @@ dl dt {
font-weight: bold;
}
-.alert.alert--warning * {
+.alert *,
+.alert a {
color: var(--ifm-font-color-base);
fill: var(--ifm-font-color-base);
stroke: var(--ifm-font-color-base);
--
GitLab