Skip to content
Snippets Groups Projects
Commit 6dfadf73 authored by Marco Holz's avatar Marco Holz
Browse files

Restructure Event Log docs

parent 214fc608
No related branches found
No related tags found
No related merge requests found
......@@ -5,89 +5,63 @@ Das Format dieser Datei basiert auf [Keep a Changelog](https://keepachangelog.co
Das hier veröffentlichte Changelog bezieht sich auf die [Testinstanz von FIT-Connect](https://docs.fitko.de/fit-connect/docs/getting-started/get-started#testing).
## 2022-10-07
## 2022-10-10
### Dokumentation
- Dokumentation zum Abruf des Event Log überarbeitet: Die Informationen des bisherigen Artikels "Status abfragen" wurden aufgeteilt in einen generischen Artikel [Event Log abrufen](getting-started/event-log/get-events.mdx) im Abschnitt "Ereignisprotokoll" und den bestehenden Artikel [Empfangsbestätigung oder Zurückweisung](sending/accept-reject.mdx). Zudem wurde ein Hinweis zur Prüfung der Authentizität und Integrität des Event Log ergänzt.
## 2022-10-07
### Dokumentation
- Der Menüpunkt "Termine" wurde in die Hauptnavigation eingefügt. Dieser Menüpunkt führt zu einer Seite, die die Beschreibung der Online-Veranstaltungen der FITKO enthält.
## 2022-09-12
### Dokumentation
- Die Seite "Zustellpunkt ermitteln" befindet sich nun unter dem Menüpunkt "Infos für Entwickler:innen > Versand von Einreichungen".
- Die Seite "Konfiguration des Antragsroutings" ist nun in die Seite "Fachverfahren anbinden" integriert.
- Der Menüpunkt "Zuständigkeitsermittlung" ist entfallen.
## 2022-08-22
### Dokumentation
- Die Startseite wurde geändert.
- Inhalte, die bislang auf der Startseite zu finden waren, sind nun in den neuen Seiten "Anträge senden" und "Anträge empfangen" vorhanden, unterhalb des Menüpunkts "FIT-Connect nutzen".
- Der Menüpunkt "Infos für Verantwortliche" wurde eingeführt, mit den neuen Seiten "Fachverfahren anbinden", Onlinedienste/Softwareprogramme anbinden" und "Zertifikate beantragen".
## 2022-08-18
### Dokumentation
- Der Menüpunkt "Grundlagen" wurde umbenannt in "Infos für Entwickler:innen".
- Die Menüpunkte "Versand von Einreichung" und "Abruf von Einreichungen" befinden sich jetzt unterhalb des Menüpunkts "Grundlagen für Entwickler:innen".
## 2022-07-26
### Zustelldienst 1.8.1
- Fix: Eine erfolgreiche Prüfung der Signatur von Zustellpunkten ohne Antwortkanäle (`replyChannels`) war nicht möglich. Dies wurde behoben. Alle alten Signaturen wurden erneut berechnet und im DVDV aktualisiert. ([Story](https://git.fitko.de/fit-connect/planning/-/issues/487))
- Fix: Unter bestimmten Umständen war es möglich einen Anhang doppelt mit gleicher `attachmentId` zu hinterlegen.
### Zustelldienst 1.8.0
- Keine Exceptions in HTTP-Responses im Produktivbetrieb. ([Story](https://git.fitko.de/fit-connect/planning/-/issues/59))
- Fix: Header callback-timestamp wird bei Wiederholungen des Callbacks nicht aktualisiert ([Bug](https://git.fitko.de/fit-connect/planning/-/issues/500))
### Zustelldienst 1.7.0, 1.7.1
- Callback um Destination-ID ergänzen: Callbacks wurden um das Array 'submissions' ergänzt. ([Story](https://git.fitko.de/fit-connect/planning/-/issues/301))
- API-Version wurde auf `1.1.0` geändert.
- Prüfung der JWE Objekte durch den Zustelldienst. ([Story](https://git.fitko.de/fit-connect/planning/-/issues/338))
## 2022-06-29
### Zustelldienst 1.6.0, 1.6.1
- Anfertigen von Statistiken von Submissions (Fachdaten) und deren Anhängen. ([Story](https://git.fitko.de/fit-connect/planning/-/issues/272))
## 2022-06-14
### Zustelldienst 1.5.15
- Prüfung der in Zustellpunkten hinterlegten Zertifikate (JWK). ([Story](https://git.fitko.de/fit-connect/planning/-/issues/119))
Fehler in der Zertifikatskette werden vorerst nur geloggt.
## 2022-06-02
### Self Service Portal 1.3.7
- Fix: Es war möglich, sich über das Self-Service-Portal Zugriff auf fremde Destinations zu verschaffen
<!-- https://git.fitko.de/fit-connect/planning/-/issues/449 -->
### Zustelldienst 1.5.14
- Fix: SQL Fehler in DB Migration bzgl. Jobrunr
### Zustelldienst 1.5.13
- Benachrichtigung des technischen Ansprechpartners bei nicht-erfolgtem Abruf durch Subscriber - Szenario 1. ([Story](https://git.fitko.de/fit-connect/planning/-/issues/304))
- Benachrichtigung des technischen Ansprechpartners bei nicht-erfolgtem Abruf durch Subscriber - Szenario 2. ([Story](https://git.fitko.de/fit-connect/planning/-/issues/372))
- Umsetzung korrekter HTTP Header wie Content-Security-Policy ([Story](https://git.fitko.de/fit-connect/planning/-/issues/308)) sowie X-Frame-Options und X-XSS-Protection ([Story](https://git.fitko.de/fit-connect/planning/-/issues/309)).
......
......@@ -6,7 +6,7 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import ApiLink from '@site/src/components/ApiLink';
Der FIT-Connect Zustelldienst informiert sendende und empfangende Systeme (API-Clients) aktiv über [neue Einreichungen](../receiving/notification.mdx) oder [Statusupdates](../sending/query-status.mdx).
Der FIT-Connect Zustelldienst informiert sendende und empfangende Systeme (API-Clients) aktiv über [neue Einreichungen](../receiving/notification.mdx) oder [Statusupdates](../sending/accept-reject.mdx).
Hierzu werden HTTP-Callbacks genutzt, die auch als [Webhooks](https://de.wikipedia.org/wiki/WebHooks) bezeichnet werden.
Webhooks ermöglichen es, API-Clients aktiv über diese Ereignisse zu informieren, ohne dass eine regelmäßige Abfrage ([Polling](https://de.wikipedia.org/wiki/Polling_(Informatik))) nötig wäre.
Technisch werden Webhooks als HTTP-POST-Request realisiert.
......
---
title: Status abfragen
title: Event Log abrufen
---
import ApiLink from '@site/src/components/ApiLink'
Nachdem die Einreichung versendet worden ist, kann der Status dieser abgefragt werden.
Der Status ist für das sendende System relevant, da hierüber das empfangende System mitteilt, ob es die Einreichung technisch korrekt verarbeiten konnte.
Bis zu einer Bestätigung über den Status `accepted` sollte das System sämtliche Inhalte einer Einreichung vorhalten.
Dies sollte es tun, damit es im Falle eines Fehlers (aufgrund eines inkorrekten Schemas oder eines falschen Public Keys), den Fehler eventuell korrigieren kann und Informationen korrekt übermitteln kann, ohne den Nutzer (bspw. einen Antragssteller) zu einer erneuten Dateneingabe aufzufordern.
Zudem stellt der Status in Form des signierten Security-Event-Tokens einen sicheren Nachweis der Übermittlung und des Empfangs dar, der gegenüber Dritten genutzt werden kann.
Das Statusmodell einer Einreichung ist in der folgenden Grafik dargestellt und enthält fünf Zustände (in orange), die in der darunterliegenden Tabelle beschrieben sind.
Die in blau und grün dargestellten [Ereignisse](../getting-started/event-log/events.mdx) werden unter "Ereignisprotokoll" im Bereich "Grundlagen" beschreiben.
![Statusdiagramm](/images/status/status.svg)
| Status | Bedeutung |
|---------------|---------------------------------------------------------------------------------------------------------|
| `incomplete` | Das sendende System hat begonnen, die Einreichung zu übermitteln. Sie jedoch noch nicht abgesendet. |
| `submitted` | Das sendende System hat die Einreichung vollständig übermittelt und abgesendet. |
| `forwarded` | Ein vermittelndes System hat die Einreichung übernommen, sie aber noch nicht dem Zielsystem zugestellt. |
| `rejected` | Die Einreichung wurde durch den Empfänger zurückgewiesen. |
| `accepted` | Die Einreichung wurde durch den Empfänger akzeptiert. |
# Abruf von Ereignissen über das Event Log
Der Event Log einer Einreichung kann über den Endpunkt <ApiLink api="submission-api" to="/v1/cases/{caseId}/events" /> abgefragt werden.
Hierbei wird der Event Log aller Einreichungen eines Cases zurückgeliefert. Dieser Event Log beinhaltet die verschiedenen Statusübergänge bzw. abgelegten Ereignisse.
Es kann über die Queryparameter `offset` und `limit` das Gesamtergebnis in kleinere Teillisten der verfügbaren Events aufgeteilt werden.
:::tip Hinweis
Die Authentizität und Integrität der aus dem Event Log abgerufenen Ereignisse SOLLTE bei jedem Abruf geprüft werden. Die notwendigen Prüfungen sind im Artikel [Prüfung eines Security-Event-Token](set-validation.mdx) beschrieben.
:::
Über die Queryparameter `offset` und `limit` kann das Gesamtergebnis in kleinere Teillisten der verfügbaren Events aufgeteilt werden.
Die maximale Anzahl an Events in einer Teilliste (`limit`) sind 500 Events.
Das Ergebnis könnte wie folgt aussehen:
......@@ -81,4 +67,4 @@ In dem SET ist folgende Information abgelegt:
Aus dem Event des SET lässt sich ableiten, dass der aktuelle Status der Einreichung in diesem Case `accepted` ist und der Zeitpunkt des Übergangs der 04.06.2021 um 10:48:52 war.
Da alle SETs im Event Log signiert sind, kann diese Signatur auch noch überprüft werden.
Die Überprüfung ist im Artikel [Prüfung eines Security-Event-Token (SET)](../getting-started/event-log/set-validation.mdx) beschrieben.
Die Überprüfung ist im Artikel [Prüfung eines Security-Event-Token (SET)](set-validation.mdx) beschrieben.
......@@ -6,10 +6,6 @@ import ApiLink from '@site/src/components/ApiLink'
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'
# SET Prüfung
## Einleitung {#einleitung}
Um eine vollständige Prüfung eines Security-Event-Tokens durchzuführen, MUSS zwingend sowohl die Einhaltung der (kryptografischen) Vorgaben als auch die Signatur geprüft werden.
Die Prüfung der Signatur des SET ist abhängig vom ausstellenden System (Zustelldienst, Subscriber oder Sender).
Aus technischer Sicht sollte auch das unter `$schema` angegebene SET-Payload-Schema validiert werden.
......@@ -17,6 +13,7 @@ Dies wird z.B. auch schon vom zuständigen Zustelldienst gemacht.
Aktuell ist die Angabe eines SET-Payload-Schemas aber noch optional und kann nicht existieren.
Dies wird in unspezifizierter Zukunft `deprecated` und alle SETs müssen ein valides SET-Payload-Schema verwenden und angeben.
In dem Fall, dass das SET-Payload-Schema nicht angegeben ist, müssen trotzdem die kryptografischen Vorgaben bzw. die kryptografische Signatur validiert werden.
:::caution Warnung
Sowohl die Prüfung der kryptografischen Vorgaben, als auch die Prüfung der kryptografischen Signatur darf KEINESFALLS ausgelassen werden.
:::
......
......@@ -129,4 +129,4 @@ private static void validateTrueOrElseThrow(boolean expression, String msg) {
## Event Log abfragen
Auch empfangende Systeme können das Event Log abfragen.
Die Abfrage des Event Log erfolgt analog zur Abfrage für sendende Systeme und ist im Artikel [Status abfragen](../sending/query-status.mdx) beschrieben.
Die Abfrage des Event Log erfolgt analog zur Abfrage für sendende Systeme und ist im Artikel [Status abfragen](../getting-started/event-log/events.mdx) beschrieben.
......@@ -4,14 +4,39 @@ title: Empfangsbestätigung oder Zurückweisung
import ApiLink from '@site/src/components/ApiLink'
Eine Einreichung wird immer mit einer Empfangsbestätigung (`accept-submission`) akzeptiert oder mit einer Zurückweisung
(`reject-submission`) abgelehnt.
Eine Empfangsbestätigung kann, eine Zurückweisung muss eine Liste von Problemen (`problems`) enthalten.
Nachdem die Einreichung versendet worden ist, kann der Status dieser abgefragt werden.
Der Status ist für das sendende System relevant, da hierüber das empfangende System mitteilt, ob es die Einreichung technisch korrekt verarbeiten konnte.
Bis zu einer Bestätigung über den Status `accepted` sollte das System sämtliche Inhalte einer Einreichung vorhalten.
Dies sollte es tun, damit es im Falle eines Fehlers (aufgrund eines inkorrekten Schemas oder eines falschen Public Keys), den Fehler eventuell korrigieren kann und Informationen korrekt übermitteln kann, ohne den Nutzer (bspw. eine Antragssteller:in) zu einer erneuten Dateneingabe aufzufordern.
## Darstellung für Nutzer
Zudem stellt der Status in Form des signierten Security-Event-Tokens einen sicheren Nachweis der Übermittlung und des Empfangs dar, der gegenüber Dritten genutzt werden kann.
:::caution Hinweis
:::caution Wichtig
Die Authentizität und Integrität der [aus dem Event Log abgerufenen Ereignisse](../getting-started/event-log/get-events.mdx) SOLLTE bei jedem Abruf geprüft werden. Die notwendigen Prüfungen sind im Artikel [Prüfung eines Security-Event-Token](../getting-started/event-log/set-validation.mdx) beschrieben.
:::
:::tip Hinweis
Wie Ereignisse aus dem Ereignisprotokoll abgerufen werden können, ist im Artikel [Event Log abfragen](../getting-started/event-log/get-events.mdx) beschrieben.
:::
## Statusmodell
Das Statusmodell einer Einreichung ist in der folgenden Grafik dargestellt und enthält fünf Zustände (in orange), die in der darunterliegenden Tabelle beschrieben sind.
Die in blau und grün dargestellten [Ereignisse](../getting-started/event-log/events.mdx) im Abschnitt "Ereignisprotokoll" beschreiben.
Eine Einreichung wird immer mit einer Empfangsbestätigung (`accept-submission`) akzeptiert oder mit einer Zurückweisung (`reject-submission`) abgelehnt.
![Statusdiagramm](/images/status/status.svg)
| Status | Bedeutung |
|---------------|---------------------------------------------------------------------------------------------------------|
| `incomplete` | Das sendende System hat begonnen, die Einreichung zu übermitteln. Sie jedoch noch nicht abgesendet. |
| `submitted` | Das sendende System hat die Einreichung vollständig übermittelt und abgesendet. |
| `forwarded` | Ein vermittelndes System hat die Einreichung übernommen, sie aber noch nicht dem Zielsystem zugestellt. |
| `rejected` | Die Einreichung wurde durch den Empfänger zurückgewiesen. |
| `accepted` | Die Einreichung wurde durch den Empfänger akzeptiert. |
## Darstellung für Nutzer
:::caution Hinweis
Die Fehlermeldungen im Problem-Datensatz dürfen den Nutzern des Systems (z.B. Bürgern, die einen Online-Antrag nutzen)
nicht angezeigt werden!
......@@ -19,7 +44,6 @@ Die Anzeige für die Nutzer (Bürger) sollte sich daher auf drei Status beschrä
- Die Einreichung wurde abgeschickt/ist auf dem Zustellweg.
- Die Einreichung wurde empfangen.
- Die Einreichung konnte nicht verarbeitet werden.
:::
### Beim Versand der Einreichung
......@@ -47,9 +71,35 @@ Bei der Formulierung sollte darauf geachtet werden, dass der Nutzer darüber inf
dass eine Klärung der technischen Fehler erfolgt und ggf. ein neuer Antrag mit seiner Beteiligung versendet werden muss.
Ob der Nutzer den Antrag erneut eingeben muss, ergibt sich aus dem Fehler und wie/ob die Daten beim sendenden System noch vorgehalten werden.
## Aufbau einer Zurückweisung
## Verarbeitung einer Empfangsbestätigung
Nachdem das empfangende System den Empfang bestätigt hat (`accept-submission`), informiert FIT-Connect das sendende
System per Callback, sofern ein Callback hinterlegt wurde.
Sollte der Callback fehlschlagen, wiederholt FIT-Connect diesen, bis er erfolgreich zugestellt werden konnte.
Eine Rückweisung könnte wie folgt aussehen.
Auch eine Empfangsbestätigung kann Probleme enthalten.
In diesem Fall waren diese nicht so gravieren, dass das empfangende System die Verarbeitung abbrechen musste.
Sie sollten protokolliert und von einem Systemadministrator überprüft werden.
Hieraus können sich Anpassungsbedarfe in der Software ergeben, wenn bspw. Fehler bzgl. der Nutzung veralteter Schemata oder deren inkorrekten Umsetzung ergeben.
![Verarbeitung einer Empfangsbestätigung](/images/events/accept-submission.svg)
## Verarbeitung einer Zurückweisung
Nachdem das empfangende System die Einreichung zurückgewiesen hat (`reject-submission`), informiert FIT-Connect das
sendende System per Callback, sofern ein Callback hinterlegt wurde.
Sollte der Callback fehlschlagen, wiederholt FIT-Connect diesen, bis er erfolgreich zugestellt werden konnte.
Eine Zurückweisung erfolgt aufgrund von technischen Problemen, die im Normalfall das sendende System vor dem Versand
verhindern muss.
Die Probleme aus der Zurückweisung müssen protokolliert und zeitnah von einem Systemadministrator überprüft werden.
![Verarbeitung einer Zurückweisung](/images/events/reject-submission.svg)
### Aufbau einer Zurückweisung
Eine Zurückweisung enthält immer eine Liste von Problemen (`problems`).
Eine Rückweisung könnte wie folgt aussehen:
```json
{
......@@ -93,7 +143,7 @@ Das Problem-Objekt enthält drei Informationen:
Mögliche Werte sind: `submission`, `metadata`, `data`, `attachment:` + UUID des Attachments oder `other`
- `title`, `detail` und evtl. weitere vorhandene Werte geben Detailinformationen zum Fehler.
## Fehlercodes (`type`) {#type}
### Fehlercodes (`type`) {#type}
| Fehlercode (`type`) | Bedeutung | Fehlerbehebung |
|-----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------|
......@@ -116,36 +166,9 @@ Das Problem-Objekt enthält drei Informationen:
| `https://schema.fitko.de/fit-connect/events/problems/unsupported-schema` [↓](#unsupported-schema) | Das angegebene Schema wird nicht unterstützt. | [Aufbau einer Einreichung](#aufbau) |
| `https://schema.fitko.de/fit-connect/events/problems/unsupported-service` [↓](#unsupported-service) | Die angegebene Verwaltungsleistung wird nicht unterstützt. | [Aufbau einer Einreichung](#aufbau) |
## Verhalten des sendenden Systems
### Verarbeitung einer Empfangsbestätigung
Nachdem das empfangende System den Empfang bestätigt hat (`accept-submission`), informiert FIT-Connect das sendende
System per Callback, sofern ein Callback hinterlegt wurde.
Sollte der Callback fehlschlagen, wiederholt FIT-Connect diesen, bis er erfolgreich zugestellt werden konnte.
Auch eine Empfangsbestätigung kann Probleme enthalten.
In diesem Fall waren diese nicht so gravieren, dass das empfangende System die Verarbeitung abbrechen musste.
Sie sollten protokolliert und von einem Systemadministrator überprüft werden.
Hieraus können sich Anpassungsbedarfe in der Software ergeben, wenn bspw. Fehler bzgl. der Nutzung veralteter Schemata oder deren inkorrekten Umsetzung ergeben.
![Verarbeitung einer Empfangsbestätigung](/images/events/accept-submission.svg)
### Verarbeitung einer Zurückweisung
### Mögliche automatische Korrekturen
Nachdem das empfangende System die Einreichung zurückgewiesen hat (`reject-submission`), informiert FIT-Connect das
sendende System per Callback, sofern ein Callback hinterlegt wurde.
Sollte der Callback fehlschlagen, wiederholt FIT-Connect diesen, bis er erfolgreich zugestellt werden konnte.
Eine Zurückweisung erfolgt aufgrund von technischen Problemen, die im Normalfall das sendende System vor dem Versand
verhindern muss.
Die Probleme aus der Zurückweisung müssen protokolliert und zeitnah von einem Systemadministrator überprüft werden.
![Verarbeitung einer Zurückweisung](/images/events/reject-submission.svg)
## Mögliche automatische Korrekturen
### `https://schema.fitko.de/fit-connect/events/problems/encryption-issue`
#### `https://schema.fitko.de/fit-connect/events/problems/encryption-issue`
Im Falle, dass ein inkorrekter Key genutzt wurde und die Einreichung unverschlüsselt vorliegt, verschlüsseln Sie diese erneut mit dem korrekten Key der Destination:
1. Rufen Sie den betreffenden Zustellpunkt erneut ab: <ApiLink api="submission-api" to="/v1/destinations/{destinationId}" withMethod="get" />
......@@ -155,12 +178,8 @@ Im Falle, dass ein inkorrekter Key genutzt wurde und die Einreichung unverschlü
Sollte die Einreichung nur noch in verschlüsselter Form vorliegen, melden sie beim Service Desk, um eine Problemlösung zu erreichen.
## Klärungsmöglichkeiten
### Probleme mit den übersendeten Daten (Schemafehler, nicht nutzbare Datenformate, etc.)
Falls es Probleme mit den übersendeten Daten hinsichtlich der Verarbeitbarkeit gekommen ist, dass die empfangende Stelle eine Annahme der Daten verweigert,
besteht die Möglichkeit über das Service Desk von FIT-Connect mit der empfangenden Stelle in Kontakt zu treten, um eventuell das Problem bilateral zu klären und zu lösen.
### Klärungsmöglichkeiten bei Zurückweisung der Einreichung
Falls es Probleme mit den übersendeten Daten hinsichtlich der Verarbeitbarkeit gekommen ist, sodass die empfangende Stelle eine Annahme der Daten verweigert, besteht die Möglichkeit über das Service Desk von FIT-Connect mit der empfangenden Stelle in Kontakt zu treten, um eventuell das Problem bilateral zu klären und zu lösen.
Es besteht jedoch keine Garantie, dass die Daten auf Seite der empfangenden Stelle nach einem Reject aufbewahrt werden oder die auf der Seite des sendenden Systems eventuell noch verschlüsselt vorgehaltenen Daten sich für eine Korrektur eignen.
Es wird daher dazu geraten, sich präzise an die Vorgaben der Destination hinsichtlich der zu versendenden Fachdatenformate und -standards zu halten und die Nutzung dieser Standards ausreichend zu testen.
......@@ -643,4 +662,4 @@ Mögliche Gründe sind:
}
```
Bei der Verarbeitung im empfangenden System trat ein teschnischer Fehler auf.
Bei der Verarbeitung im empfangenden System trat ein technischer Fehler auf.
......@@ -54,7 +54,6 @@ module.exports = {
'sending/encrypt',
'sending/attachments',
'sending/submit',
'sending/query-status',
'sending/accept-reject',
]
},
......@@ -78,6 +77,7 @@ module.exports = {
items: [
'getting-started/event-log/overview',
'getting-started/event-log/events',
'getting-started/event-log/get-events',
'getting-started/event-log/set-creation',
'getting-started/event-log/set-validation',
]
......@@ -143,4 +143,4 @@ module.exports = {
'metadata/replyChannel',
'metadata/additionalReferenceInfo'
]
}
\ No newline at end of file
}
import React from 'react';
import {Redirect} from '@docusaurus/router';
export default function query_status() {
return (
<p>
<Redirect to="../../../docs/sending/accept-reject.mdx" />
</p>
);
}
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment