Metadaten.md

Antragsmetadaten

Die Antragsmetadaten beschreiben die Struktur des Antrags und dessen Inhalte, wie beispielsweise Anhänge oder die Fachdaten. Zustätzlich können weitere Informationen über den/die AntragsstellerInnen hinterlegt werden. Eine genaue Definition ist unter XYZ zu finden bzw. direkt im Schema zu finden.

Im Folgenden wird nun beschrieben, wie für das Versenden eines Antrags das Schema aufgebaut und befüllt wird, sowie beim Empfangen eines Antrags dieser entschlüsselt und gegen das Schema validiert wird.

Prozess: Versenden eines Antrages

Anlegen eines neuen Antrags

Das Anlegen eines neuen Antrags kann über die API getätigt werden. Dafür muss ein HTTP POST Nachricht versendet werden, die definiert, an welchen Zustellpunkt der Antrag versendet werden soll und welche Inhalte übermittelt werden sollen. Die Inhalte umfassen hierbei die Identifikatoren der Anhänge als UUIDs und die Information, ob Fachdaten mit versendet werden oder nicht.

curl --data '{ "destinationId": "<UUID>", "announcedContentStructure": {} }' -H 'Content-Type: application/json' -H 'X-AnwenderId: <Id>' -X POST <URL>/applications/

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

Definition der Antragsmetadaten

Das Minimum, was an Antragsmetadaten hinterlegt werden muss, ist eine Beschreibung der Struktur des Antrags, sowie die ID des Antrags selbst. In der Beschreibung der Struktur muss angegeben werden, ob Fachdaten mit versendet werden und in welchem Format diese sind. Des Weiteren können Anhänge mit ihren Metainformationen beschrieben werden, die dem Antrag beigefügt sind.

Ein Beispiel hierfür ist unten dargestellt:

{
  "contentStructure": {
    "data": {
      "schema": {
        "mimeType": "application/json",
        "schemaSource": "https://schema.fitko.de/fim/fim.S00000147.00000147001002.json"
      }
    },
    "docs": [
      {
        "docId": "1",
        "purpose": "form",
        "size": 13046,
        "mimeType": "application/pdf",
        "filename": "test.pdf",
        "description": "Das Antragsformular",
        "lang": {
          "lang": "de",
          "region": "DE"
        },
        "hash": {
          "algorithm": "SHA-256",
          "digest": "bf37d894fdf9aeade63975ed648d49c3e8a7a773923597d2418915f54cd7c3b9"
        }
      }
    ]
  },
  "applicationId": "ce75a6b8-d72f-4b94-b09e-af6be35bc2ae"
}

Abhängig von den Rahmenbedingungen können die weiteren Felder, die im Antragsmetadatenschema definiert sind, befüllt werden und mitversendet werden. Ob diese jedoch ausgewertet werden oder nicht hängt von dem entsprechenden Empfänger ab.

Verschlüsseln

Nun wird das JSON-Objekt aus dem vorherigen Schritt verschlüsselt und kann dann im nächsten Schritt mit dem Antrag abgesendet werden. Die Verschlüsselung eines Objektes mit Hilfe von JWE ist im Bereich "Verschlüsselte Übertragung" genauer beschrieben und kann dort nachgelesen werden.

Versenden des Antrags

Sobald alle Anhänge eines Antrags hochgeladen sind, kann der Antrag abgesendet werden. Hierfür müssen die verschlüsselten Metadaten und, falls angekündigt, die Fachdaten über eine HTTP POST Nachricht gesendet werden. Ein Beispiel hierfür ist im folgenden Ausschnitt aufgezeigt:

curl --data '{ "encryptedMetadata": "<jose-String>" }' -H 'Content-Type: application/json' -H 'X-AnwenderId: <Id>' -X POST <URL>/applications/<UUID>

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": "Antrag versendet durch sender",
      "timestamp": "2021-05-26T09:12:58.728397+02:00"
    }
  ],
  "announcedContentStructure": {
    "data": false,
    "attachments": []
  }
}

Prozess: Empfangen und verarbeiten eines Antrags

Abfragen des Antrags

Wenn ein neuer Antrag bereitsteht, kann dieser über mehrere Befehle heruntergeladen werden. Mehrere dahingehend, da erst alle allgemeinen Informationen zum Antrag heruntergeladen werden müssen und dann, falls notwendig alle mit ihm verbundenen Anhänge.

curl -H 'X-AnwenderId: <Id>' -X GET <URL>/applications/<UUID>

# Falls ein Antrag noch entsprechend Anhänge besitzt, können diese über folgenden Befehl heruntergeladen werden:
curl -H 'X-AnwenderId: <Id>' -X GET <URL>/applications/<UUID>/attachments/<UUID>

curl -H 'X-AnwenderId: subscriber' -X GET 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": "Antrag versendet durch sender",
      "timestamp": "2021-05-26T09:12:58.728397+02:00"
    }
  ],
  "announcedContentStructure": {
    "data": false,
    "attachments": []
  }
}

Entschlüsseln

Um den Antrag korrekt verarbeiten und überprüfen zu können müssen zuerst alle verschlüsselten Informationen entschlüsselt werden. Darunter fallen beispielsweise die Antragsmetadaten, die Fachdaten (falls vorhanden) oder Dokumente (falls vorhanden).

Die Entschlüsselung eines solchen Objektes mit Hilfe von JWE ist im Bereich "Verschlüsselte Übertragung" genauer beschrieben und kann dort nachgelesen werden.

Validierung der Antragsmetadaten

Das Minimum, was an Information vorhanden sein muss sind die Felder contentStructure und applicationId. Zustäzlich können je nach Anwendungsfall oder Notwendigkeit weitere Felder auf Existenz überprüft werden. Die gültigen Formate sind im Schema definiert und können mit Hilfe von Bibliotheken für die Validierung einer Instanz von Antragsmetadaten verwendet werden. Beispiele für die Definition von Formaten für Felder sind unten aufgeführt.

{
  ...
  "country": {
    "type": "string",
    "description": "Staat gemäß Codeliste [https://www.xrepository.de/details/urn:de:bund:destatis:bevoelkerungsstatistik:schluessel:staat](Codeliste Staat aus der Staats- und Gebietssystematik des Statistischen Bundesamtes)",
    "minLength": 3,
    "maxLength": 3,
    "pattern": "^[0-9]{3}$"
  },
  ...
  "postalCode": {
    "type": "string",
    "description": "Postleitzahl",
    "minLength": 5,
    "maxLength": 5,
    "pattern": "^([0]{1}[1-9]{1}|[1-9]{1}[0-9]{1})[0-9]{3}$"
  },
  ...
  "applicationId": {
    "type": "string",
    "format": "uuid",
    "pattern": "^[-_.A-Za-z0-9]+$",
    "description": "ID des Antrags"
  },
  ...
}

Verarbeiten des Antrags

Nachdem nun der Antrag vollständig heruntergeladen wurde und validiert wurde, sollte dieser entsprechend bestätigt werden. Dies muss über ein HTTP PUT, wie unten aufgezeigt, durchgeführt werden.

curl -H 'X-AnwenderId: <Id>' -X PUT <URL>/applications/<UUID>

curl -H 'X-AnwenderId: subscriber' -X PUT localhost:8080/applications/9d618546-0ff7-4e93-9f15-714e5dd1bf12
> {}