Zum Hauptinhalt springen

Java-SDK

FIT-Connect stellt Entwickler:innen ein Software-Development-Kit (SDK) für die Anbindung von Java-Anwendungen an FIT-Connect zur Verfügung und ermöglicht die einfache Nutzung der REST API von FIT-Connect.

Repositories​

Das SDK steht in verschiedenen Quellen zur Verfügung:

API-Dokumentation ​

Die API-Dokumentation im Format Javadoc ist auf der Seite FIT-Connect Java SDK - Client verfügbar.

Systemvoraussetzungen​

Das Java Development Kit (JDK) >= 11 ist erforderlich, um das SDK zu nutzen. Mit dem folgenden Befehl können Sie überprüfen, welche Version des JDKs installiert ist:

> java --version
openjdk 11.0.18 2023-01-17 LTS
OpenJDK Runtime Environment Microsoft-7208460 (build 11.0.18+10-LTS)
OpenJDK 64-Bit Server VM Microsoft-7208460 (build 11.0.18+10-LTS, mixed mode)

Integration​

Das SDK kann auf verschiedene Wege in bestehende Systeme integriert werden. Neben der Einbindung als Maven-Artefakt gibt es auch die Möglichkeit, den Quellcode des Projektes lokal zu bauen.

Einbindung als Maven-Artefakt​

Sie können den SDK-Client in ein Projekt einbinden, indem Sie es als Dependency der Datei pom.xml hinzufügen:

<dependency>
  <groupId>dev.fitko.fitconnect.sdk</groupId>
  <artifactId>client</artifactId>
  <version>[Latest Version]</version>
</dependency>

Mit [Latest Version] als aktuelles Release oder einer Snapshot-Version.

Wird eine Snapshot-Version genutzt, dann ist die Angabe des "Maven Snapshot Repositories" in der POM notwendig:

<repositories>
  <repository>
    <id>maven-snapshots</id>
    <url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
  </repository>
</repositories>

SDK lokal bauen​

Alternativ kann das SDK auch aus dem Quellcode heraus lokal gebaut werden. Mit git clone klonen Sie das Repository:

git clone https://git.fitko.de/fit-connect/sdk-java.git

Anschließend wird das Projekt gebaut:

./mvnw clean package -DskipTests

Das Client-Artefakt steht nach erfolgreichem Build unter {projekt.dir}/client/target zur Verfügung.

Einrichtung​

FIT-Connect verwendet die Credentials ClientId (Zugangs-Kennung) und ClientSecret (Zugangs-Geheimnis). Mit diesen Zugangsdaten wird beim OAuth-Server ein Token angefragt, der Zugriff auf die FIT-Connect-Schnittstellen erlaubt (Submission API, Routing API, Self-Service API).

Credentials erzeugen​

Im Self-Service-Portal (SSP) von FIT-Connect werden die Zugangsdaten für Sender-Clients und Subscriber-Clients eingerichtet. Beim Anlegen von Zugangsdaten für einen Sender oder Subscriber sind die Credentials unter Zugangsdaten einsehbar. Dazu finden Sie auf der Seite Accountregistrierung und Client-Verwaltung eine Beschreibung.

Client-Konfiguration​

Sie konfigurieren das SDK mithilfe der Datei config.yml oder in Java über den ApplicationConfig.builder. Eine Template für die YAML finden Sie im Repository. In dieser Konfigurationsdatei stellen Sie die folgenden Daten zur Verfügung:

Für das Konfigurieren eines Senders:​

  • clientId - Client-ID (Zugangs-Kennung), die Sie beim Anlegen eines Sender-Clients im Self-Service-Portal (SSP) erhalten haben
  • clientSecret - Das dazu gehörende Client-Secret (Zugangs-Geheimnis), das Sie beim Anlegen dieses Sender-Clients im Self-Service-Portal (SSP) erhalten haben
Beispiel einer Minimalkonfiguration für einen Sender als YAML​
senderConfig:
  clientId: "07564691-82bd-4b41-b464-4c39aaa0bc0c"
  clientSecret: "la4jl3enU-pS25BS3aFDDuJKmv0N27YIF1tz8AR-3ws"

activeEnvironment: TEST

Für das Konfigurieren eines Empfängers:​

  • clientId - Client-ID (Zugangs-Kennung), die Sie beim Anlegen eines Subscriber-Clients im Self-Service-Portal erhalten haben
  • clientSecret - Das dazu gehörende Client-Secret (Zugangs-Geheimnis), das Sie beim Anlegen dieses Subscriber-Clients im Self-Service-Portal erhalten haben
  • privateDecryptionKeyPaths - Pfad(e) zum JWK des privaten Entschlüsselungsschlüssels.
    Eine Beschreibung zum Ableiten von JWKs (JSON Web Keys) aus einem Zertifikat finden Sie auf der Seite Zertifikate
  • privateSigningKeyPath - Pfad zum JWK des privaten Signatur-Schlüssels
Beispiel einer Minimalkonfiguration für einen Subscriber als YAML​
subscriberConfig:
  clientId: "e5adf182-17d2-42fb-836d-f82f14c87410"
  clientSecret: "lf4jK5enU-pR27BS8aFLLuJYmv0N37YIF8tz8AR-1rw"

  privateDecryptionKeyPaths: ["C:/fit-connect/config/decryption_key.json"]
  privateSigningKeyPath: "C:/fit-connect/config/signing_key.json"

activeEnvironment: TEST

Betriebsumgebung (Environments):​

Unter dem Schlüssel activeEnvironment stehen die Umgebungen PROD, STAGE und TEST zur Verfügung. Diese sind bereits durch das SDK vorkonfiguriert, die Einstellungen können jedoch, wie im Beispiel zu sehen ist, überschrieben werden.

Erzeugung der Konfiguration in Java​

Die ApplicationConfig kann in Java programmatisch über einen Builder erzeugt werden. Das folgende Beispiel zeigt eine Konfiguration eine Übersicht aller Optionen:

var config = ApplicationConfig.builder()
   .senderConfig(sender)
   .subscriberConfig(subscriber)
   .httpConfig(httpConfig)
   .environments(Environments.getEnvironmentsAsMap())
   .activeEnvironment(Environments.TEST.getEnvironmentName())
   .submissionDataSchemas(submissionDataSchemas)
   .attachmentChunkingConfig(attachmentChunkingConfig)
   .build();

Verpflichtende Angaben zur Erzeugung eines Senders bzw. Subscribers sind jeweils das Sender- bzw. Subscriber-Objekt und die angabe der gewünschten Umgebung (activeEnvironment).

Erzeugung der Konfiguration als YAML​

Bei der Konfiguration über eine YAML-Datei kann die Konfiguration mittels ApplicationConfigLoader geladen und an die Clients für Sender, Empfänger und Router übergeben werden. Im folgenden Beispiel wird die Datei config.yml aus einem Pfad geladen:

final ApplicationConfig config = ApplicationConfigLoader.loadConfigFromPath(Path.of("path/to/config.yml"));

Sie können dem ApplicationConfigLoader die Konfiguration auch als String (im YAML-Format) übergeben. Zudem besteht die Möglichkeit, den Pfad zur Konfigurationsdatei über die Umgebungsvariable FIT_CONNECT_CONFIG bereitzustellen, wie das folgende Beispiel zeigt:

set FIT_CONNECT_CONFIG="C:/sdk/config/config.yaml"
final ApplicationConfig config = ApplicationConfigLoader.loadConfigFromEnvironment();

Erstellung konfigurierter Clients​

Mittels der ClientFactory und einer zuvor geladenen Konfiguration können Clients für Sender, Subscriber und Router erstellt werden.

final SenderClient senderClient = ClientFactory.createSenderClient(config);
final SubscriberClient subscriberClient = ClientFactory.createSubscriberClient(config);
final RouterClient routerClient = ClientFactory.createRouterClient(config);

Optionale Konfigurationsparameter​

Die Properties vordefinierter Umgebungen können wie im Beispiel für TEST überschrieben werden. Neben den vordefinierten Umgebungen lassen sich auch ohne Code-Änderung weitere benutzerdefinierte Umgebungen zur Konfiguration hinzufügen (siehe Beispiel CUSTOM_ENVIRONMENT):

# Aktivierung einer benutzerdefinierten Umgebung
activeEnvironment: MY_CUSTOM_ENVIRONMENT

environments:
  # Überschreiben der TEST-Environment und Deaktivieren des Auto-Rejects
  TEST:
    enableAutoReject: false

  # Anlegen einer weiteren benutzerdefinierten Umgebung
  MY_CUSTOM_ENVIRONMENT:
    authBaseUrl: "https://auth-url.test.net"
    routingBaseUrl: "https://routing-url.test.net"
    submissionBaseUrls: ["https://submission-url.test.net"]
    selfServicePortalBaseUrl: "https://portal-url.test.net"
    enableAutoReject: true
    allowInsecurePublicKey: true
    skipSubmissionDataValidation: false

# explizite Angabe lokal verfügbarer Schema-Pfade zur Validierung der Fachdaten
submissionDataSchemas:
  "urn:test:sample": "some/path/to/file"
  "https://xml.schema.sample.net": "some/path/to/file"
  "https://json.schema.sample.net": "some/path/to/file"

# Konfiguration des HTTP-Clients
httpConfig:
  timeouts:
    readTimeout: 60
    writeTimeout: 60
    connectionTimeout: 60
  proxyConfig:
    httpProxyHost: "https://proxy.test.net"
    httpProxyPort: 8080
    basicAuth:
      username: "username"
      password: "password"
  retryConfig:
    allowRetries: true
    maxRetryCount: 3
    initialDelayInMs: 1000
    retryableStatusCodes: [429, 500]

# Konfiguration des Attachment-Chunkings
attachmentChunkingConfig:
  chunkSizeInMB: 100
  chunkAllAttachments: true
  attachmentStoragePath: "/path/to/attachment/dir"

Übersicht optionaler Properties​

PropertyTypScopeBeschreibung
enableAutoRejecttrue/falseEnvironmentAutom. Abweisung von Submissions sobald beim Empfang eine Validierung fehlschlägt
allowInsecurePublicKeytrue/falseEnvironmentErlaubt die Nutzung von Self-Signed-Zertifikaten für Testzwecke
skipSubmissionDataValidationtrue/falseEnvironmentValidierung der Fachdaten gegen die in der Submission angegebene Schema-URI
submissionDataSchemasPfade (Strings) zu den lokalen Schemata für FachdatenConfigSchemata gegen die in der Submission angegebene Fachdaten validiert werden. Sind keine lokalen Schemata definiert, wird versucht, das Schema über HTTP zu laden.

Hinweis: URNs, die nicht über HTTP adressierbar sind, sollten hier als Datei hinterlegt werden.
attachmentChunkingConfigKonfiguration des Attachment ChunkingsConfigEinstellen der Chunk-Größe und die Angabe eines Verzeichnis zur Speicherung von Attachment-Daten.

Hinweis: Per default werden Attachments in Chunks übertragen, die nicht in den Hauptspeicher passen und als Attachment.fromLargeAttachment() erzeugt wuden. Mit chunkAllAttachments: true wird das Chunking auch für In-Memory Attachments aktiviert.
httpConfig.timeoutsTimeout Konfiguration des HTTP-ClientsHTTP-ConfigÜberschreiben der default timeouts (30s) des HTTP-Clients
httpConfig.proxyConfigProxy Konfiguration des HTTP-ClientsHTTP-ConfigSetzen eines HTTP-Proxies, inkl. optionaler BasicAuth Authentifizierung über Nutzername/Passwort
httpConfig.retryConfigRetry Konfiguration des HTTP-ClientsHTTP-ConfigSetzen der Anzahl der Versuche, der initialen Wartezeit und der Statuscodes die wiederholt werden sollen.

Alle Werte sind optional, per default werden fehlgeschlagene Requests mit 5 Versuchen für [408, 429, 500, 502, 503, 504] wiederholt.

Übersicht der Umgebungen​

Die folgenden Umgebungen stehen vorkonfiguriert über das SDK bereit:

PRODSTAGETEST
AuthBaseURLhttps://auth-prod.fit-connect.fitko.nethttps://auth-refz.fit-connect.fitko.nethttps://auth-testing.fit-connect.fitko.dev
RoutingBaseURLhttps://routing-api-prod.fit-connect.fitko.nethttps://routing-api-prod.fit-connect.fitko.nethttps://routing-api-testing.fit-connect.fitko.dev
SubmissonBaseURLs[https://submission-api-prod.fit-connect.niedersachsen.de][https://submission-api-refz.fit-connect.niedersachsen.de][https://submission-api-testing.fit-connect.fitko.dev]
SelfServicePortalBaseURLhttps://portal.auth-prod.fit-connect.fitko.nethttps://portal.auth-refz.fit-connect.fitko.nethttps://portal.auth-testing.fit-connect.fitko.dev
enableAutoRejecttruetruetrue
allowInsecurePublicKeyfalsefalsetrue
skipSubmissionDataValidationfalsefalsefalse