Konfiguration

Alle Optionen beider SDKs auf einer Seite. Was Sie nicht setzen, bekommt einen Default — mit Ausnahme der Pflichtfelder Credentials und Umgebung (und in .NET der eigenen DestinationId). Den Einstieg mit Beispielkonfiguration zeigt das Rezept Einrichten.

Datei oder Code — beides geht

Jede Option auf dieser Seite lässt sich auf zwei Wegen setzen. Die YAML-/JSON-Beispiele unten zeigen den Datei-Weg; der Code-Weg verwendet dieselben Namen.

Java

	Datei (YAML)	Code (Builder)
Einstieg	FitConnectSdk.fromConfigYaml(path)	FitConnectSdk.fromConfigBuilder() mit .credentials(), .environment(), .settings()
sdkSettings	Block in der YAML	SdkSettings.builder()
httpConfig	sdkSettings.httpConfig	HttpConfig.builder() mit .timeouts(), .proxyConfig(), .retryConfig()
attachmentChunkingConfig	sdkSettings.attachmentChunkingConfig	AttachmentChunkingConfig.builder()
validationConfig	sdkSettings.validationConfig	ValidationConfig.builder()
virusScannerConfig	sdkSettings.virusScannerConfig	VirusScannerConfig.daemonOnly(), processOnly(), icapOnly()
environment	TEST, STAGE, PROD oder Block	FitConnectEnvironment.TEST oder FitConnectEnvironment.builder()

Die YAML-Schlüssel heißen wie die Builder-Methoden — mit einer Ausnahme: der Block httpConfig.timeoutConfig wird im Code mit HttpConfig.builder().timeouts(TimeoutConfig) gesetzt. Was Sie im Builder nicht setzen, bekommt denselben Default wie ein fehlender YAML-Schlüssel. Beide Wege lassen sich mischen: Credentials und Umgebung aus der Datei, Settings im Code — oder umgekehrt Werte aus einem Vault in den Builder geben.

.NET (C#)

AddFitConnect() liest die Section FitConnect aus IConfiguration. Die appsettings.json-Beispiele unten sind nur eine Quelle davon — dieselben Schlüssel können aus Umgebungsvariablen, User Secrets, einem Vault-Provider oder direkt aus dem Code kommen:

var configuration = new ConfigurationBuilder()
    .AddInMemoryCollection(new Dictionary<string, string?>
    {
        ["FitConnect:EnvironmentTag"] = "TEST",
        ["FitConnect:Client:ClientId"] = clientId,          // z. B. aus dem Vault
        ["FitConnect:Client:ClientSecret"] = clientSecret,
        ["FitConnect:Client:DestinationId"] = destinationId.ToString(),
        ["FitConnect:Http:Retry:AllowRetries"] = "true",
    })
    .AddEnvironmentVariables()                              // FitConnect__Client__ClientId=…
    .Build();

services.AddSingleton<IConfiguration>(configuration).AddFitConnect();

Zusätzlich nimmt AddFitConnect(Action<FitConnectConfig>) einen Konfigurations-Callback; die Options-Klassen sind jedoch init-only, sodass dieser Weg in der aktuellen Version nur eingeschränkt nutzbar ist — die IConfiguration-Quelle ist der verlässliche.

Vollständige Beispielkonfiguration

Java

credentials:
  clientId: "your-client-id"
  clientSecret: "your-client-secret"

environment: "TEST"          # TEST | STAGE | PROD — oder ein Block für eine eigene Umgebung (siehe unten)

sdkSettings:
  httpConfig:
    timeoutConfig:
      readTimeout: 30
      writeTimeout: 30
      connectionTimeout: 30
      callTimeout: 30
    proxyConfig:
      host: ""               # leer = kein Proxy
      port: 0
      basicAuth:
        username: ""
        password: ""
    retryConfig:
      allowRetries: true
      retryableStatusCodes: [408, 429, 500, 502, 503, 504]
      maxRetryCount: 5
      initialDelayInMs: 500

  attachmentChunkingConfig:
    chunkAllAttachments: false
    chunkSizeInMB: 10
    attachmentStoragePath: "/tmp/fit-connect-attachments"

  validationConfig:
    validateMetadata: true
    validateData: true
    validateAttachments: true
    customSchemas: []          # eigene JSON-/XSD-Schemata, siehe Rezept „Custom Schemata“

  # virusScannerConfig: …      # optionales Modul, siehe Rezept „Virenscanner anbinden“
  concurrentAttachmentStreams: 3

Dieselbe Konfiguration programmatisch:

SdkSettings settings = SdkSettings.builder()
    .httpConfig(HttpConfig.builder()
        .timeouts(TimeoutConfig.builder()
            .readTimeout(30).writeTimeout(30).connectionTimeout(30).callTimeout(30).build())
        .proxyConfig(ProxyConfig.builder().build())                    // kein Proxy
        .retryConfig(RetryConfig.builder()
            .allowRetries(true)
            .retryableStatusCodes(List.of(408, 429, 500, 502, 503, 504))
            .maxRetryCount(5).initialDelayInMs(500).build())
        .build())
    .attachmentChunkingConfig(AttachmentChunkingConfig.builder()
        .chunkAllAttachments(false).chunkSizeInMB(10)
        .attachmentStoragePath(Path.of("/tmp/fit-connect-attachments")).build())
    .validationConfig(ValidationConfig.builder()
        .validateMetadata(true).validateData(true).validateAttachments(true)
        .customSchemas(List.of()).build())
    // .virusScannerConfig(VirusScannerConfig.daemonOnly("clamav", 3310))
    .concurrentAttachmentStreams(3)
    .build();

FitConnectSdk sdk = FitConnectSdk.fromConfigBuilder()
    .credentials("your-client-id", "your-client-secret")
    .environment(FitConnectEnvironment.TEST)
    .settings(settings)
    .build();

Die Schlüsselnamen entsprechen den Feldern von SdkSettings/HttpConfig (timeoutConfig, proxyConfig, retryConfig). Schlüsselmaterial (DestinationKeys, ReplyKeys) ist bewusst nicht Teil dieser Datei und auch kein Builder-Parameter — es wird beim Erzeugen von Organisation/OnlineService übergeben, siehe Schlüssel und Rollover.

.NET (C#)

{
  "FitConnect": {
    "EnvironmentTag": "TEST",
    "Client": {
      "ClientId": "your-client-id",
      "ClientSecret": "your-client-secret",
      "DestinationId": "<eigene destination-uuid>",
      "DecryptionKeys": [ "{ …RSA-Private-JWK… }" ],
      "SignatureKey": "{ …Signatur-JWK… }",
      "VerifyDestinationOnStartup": true
    },
    "Http": {
      "Timeouts": { "Read": 30, "Write": 30, "Connection": 10 },
      "Proxy": { "Host": "", "Port": 0 },
      "Retry": {
        "AllowRetries": true,
        "RetryableStatusCodes": [ 408, 429, 500, 502, 503, 504 ],
        "MaxRetryCount": 5,
        "InitialDelayInMs": 500
      }
    },
    "Attachments": {
      "BaseDirectory": "",
      "ChunkAllAttachments": false,
      "ChunkSizeInMb": 10
    },
    "Validation": { "Metadata": true, "Data": true, "Attachments": true }
  }
}

Die Section heißt standardmäßig FitConnect; ein anderer Name geht mit services.AddFitConnect("MeinAbschnitt"). Secrets und Schlüssel kommen aus User Secrets oder einem Vault-Provider von IConfiguration, nicht aus der eingecheckten Datei.

Eigene oder angepasste Umgebung

Java

In der YAML ersetzt ein Block den Namen der Umgebung:

environment:
  name: "LOCAL"
  authUrl: "https://my-auth/token"
  routingUrl: "https://my-routing"
  submissionApiUrl: "https://my-api/submission-api"
  portalUrl: "https://my-portal"
  destinationApiUrl: "https://my-api/destination-api"
  allowInsecureKeys: true

Programmatisch:

FitConnectEnvironment env = FitConnectEnvironment.builder()
    .name("LOCAL")
    .authUrl("https://my-auth/token")
    .routingUrl("https://my-routing")
    .submissionApiUrl("https://my-api/submission-api")
    .portalUrl("https://my-portal")
    .destinationApiUrl("https://my-api/destination-api")
    .allowInsecureKeys(true)
    .build();

FitConnectSdk sdk = FitConnectSdk.fromConfigBuilder()
    .credentials("client-id", "client-secret")
    .environment(env)
    .build();

.NET (C#)

{
  "FitConnect": {
    "EnvironmentTag": "CUSTOM",
    "CustomEnvironment": {
      "TokenUrl": "https://my-auth/token",
      "SubmissionUrls": [ "https://my-api/submission-api" ],
      "RoutingUrl": "https://my-routing",
      "SspUrl": "https://my-portal",
      "DestinationUrl": "https://my-api/destination-api"
    }
  }
}

HTTP-Konfiguration (Timeouts, Proxy, Retries)

Java

sdkSettings:
  httpConfig:
    timeoutConfig:
      readTimeout: 60
      writeTimeout: 60
      connectionTimeout: 60
      callTimeout: 120        # Gesamtdauer eines Aufrufs inkl. Retries
    proxyConfig:
      host: "proxy.example.net"
      port: 8080
      basicAuth:
        username: "user"
        password: "pass"
    retryConfig:
      allowRetries: true
      maxRetryCount: 5
      initialDelayInMs: 500
      retryableStatusCodes: [408, 429, 500, 502, 503, 504]

Programmatisch — Proxy-Zugangsdaten kommen so aus einem Vault statt aus der Datei:

HttpConfig http = HttpConfig.builder()
    .timeouts(TimeoutConfig.builder()
        .readTimeout(60).writeTimeout(60).connectionTimeout(60).callTimeout(120).build())
    .proxyConfig(ProxyConfig.builder()
        .host("proxy.example.net").port(8080)
        .basicAuth(new ProxyAuth(vault.user(), vault.password())).build())
    .retryConfig(RetryConfig.builder()
        .allowRetries(true).maxRetryCount(5).initialDelayInMs(500)
        .retryableStatusCodes(List.of(408, 429, 500, 502, 503, 504)).build())
    .build();

SdkSettings settings = SdkSettings.builder().httpConfig(http).build();

.NET (C#)

{
  "FitConnect": {
    "Http": {
      "Timeouts": {
        "Read": 60,
        "Write": 60,
        "Connection": 60
      },
      "Proxy": {
        "Host": "proxy.example.net",
        "Port": 8080,
        "Username": "user",
        "Password": "pass"
      },
      "Retry": {
        "AllowRetries": true,
        "MaxRetryCount": 5,
        "InitialDelayInMs": 500,
        "RetryableStatusCodes": [ 408, 429, 500, 502, 503, 504 ]
      }
    }
  }
}

Validierungsverhalten steuern

Java

sdkSettings:
  validationConfig:
    validateMetadata: true
    validateData: true
    validateAttachments: true

SdkSettings settings = SdkSettings.builder()
    .validationConfig(ValidationConfig.builder()
        .validateMetadata(true).validateData(true).validateAttachments(true).build())
    .build();

Ein enableAutoReject-Schalter existiert seit 4.0.0-rc.1 nicht mehr: receive(...) liefert immer einen Prüfbericht zurück, den Ihr Fachverfahren selbst auswertet — siehe Konzept: Der Prüfbericht.

.NET (C#)

{
  "FitConnect": {
    "Validation": {
      "Metadata": true,
      "Data": true,
      "Attachments": true
    }
  }
}

Alle drei stehen standardmäßig auf true. Funde werfen nicht, sondern landen im Report der empfangenen Nachricht — siehe Konzept: Der Prüfbericht. Ein AutoReject-Feld gibt es nicht mehr.

Für die Registrierung eigener Fachschemata (JSON Schema / XSD) außerhalb von FIM und XÖV siehe Custom Schemata.

Attachment-Chunking konfigurieren

Siehe das Rezept Große Anhänge senden und empfangen.

Property-Referenz Java

Alle Builder hängen an SdkSettings.builder() (.httpConfig(…), .validationConfig(…), .attachmentChunkingConfig(…), .virusScannerConfig(…)); … steht für den jeweils davor genannten Builder.

Property (YAML)	Builder	Typ	Beschreibung
validationConfig.validateMetadata	ValidationConfig.builder().validateMetadata()	bool	Metadaten-Schema-Prüfung aktivieren
validationConfig.validateData	….validateData()	bool	Fachdaten-Schema-Prüfung aktivieren
validationConfig.validateAttachments	….validateAttachments()	bool	Validatoren für Anhänge ausführen (z. B. Virenprüfung)
validationConfig.customSchemas[].identifier	….customSchemas(List.of(new CustomSchema(uri, path)))	URI	URN/URI, die mit der schemaUri im Metadatensatz übereinstimmt
validationConfig.customSchemas[].path	ebd.	string	Dateisystempfad zur lokalen JSON-Schema- oder XSD-Datei
httpConfig.timeoutConfig.{readTimeout,writeTimeout,connectionTimeout,callTimeout}	HttpConfig.builder().timeouts(TimeoutConfig.builder().readTimeout()…)	int (Sekunden)	Default 30 s je Phase
credentials.clientId / credentials.clientSecret	FitConnectSdk.fromConfigBuilder().credentials(id, secret)	string	Pflicht. OAuth-Credentials
environment	.environment(FitConnectEnvironment.TEST) / FitConnectEnvironment.builder()	string / object	Pflicht. TEST/STAGE/PROD oder Block mit eigenen URLs
httpConfig.retryConfig.allowRetries	RetryConfig.builder().allowRetries()	bool	Default true
httpConfig.retryConfig.maxRetryCount / initialDelayInMs	….maxRetryCount() / ….initialDelayInMs()	int	Default 5 / 500
httpConfig.proxyConfig.*	ProxyConfig.builder().host().port().basicAuth(new ProxyAuth(u, p))	—	Optionaler Proxy mit Basic Auth
httpConfig.retryConfig.retryableStatusCodes	….retryableStatusCodes(List.of(…))	List	Default [408, 429, 500, 502, 503, 504]
attachmentChunkingConfig.chunkSizeInMB	AttachmentChunkingConfig.builder().chunkSizeInMB()	int	Default 10
attachmentChunkingConfig.chunkAllAttachments	….chunkAllAttachments()	bool	Default false. Alle Anhänge chunken, auch In-Memory
attachmentChunkingConfig.attachmentStoragePath	….attachmentStoragePath(Path)	string	Lokaler Anhangspeicher, Default System-Temp
concurrentAttachmentStreams	SdkSettings.builder().concurrentAttachmentStreams()	int	Parallelität beim Hochladen von Anhängen

Property-Referenz .NET

Property	Typ	Beschreibung
EnvironmentTag	string	Pflicht. TEST/STAGE/PROD/LOCAL/CI/CUSTOM
CustomEnvironment.*	object	Bei CUSTOM Pflicht: TokenUrl, SubmissionUrls[], RoutingUrl, SspUrl, DestinationUrl
Client.ClientId / Client.ClientSecret	string	Pflicht. OAuth-Credentials, eine Paarung für Senden und Empfangen
Client.DestinationId	Guid	Pflicht. UUID des eigenen Zustellpunkts (fromDestinationId)
Client.DecryptionKeys	string[]	Private RSA-JWKs als JSON, geordnet (erster = aktiv). Leer für reine Sender
Client.SignatureKey	string	Privater Signatur-JWK als JSON. Nötig zum Annehmen/Ablehnen/Antworten
Client.VerifyDestinationOnStartup	bool	Default true. Zustellpunkt und Typ beim Host-Start prüfen (braucht Netz)
Http.Timeouts.{Read,Write,Connection}	int (Sekunden)	Default 30 / 30 / 10
Http.Proxy.{Host,Port,Username,Password}	—	Optionaler Proxy
Http.Retry.AllowRetries	bool	Default false — für Produktion aktivieren
Http.Retry.RetryableStatusCodes	int[]	Empfehlung [408, 429, 500, 502, 503, 504]
Http.Retry.MaxRetryCount	int	Empfehlung 5
Http.Retry.InitialDelayInMs	int	Empfehlung 500
Attachments.ChunkSizeInMb	int	Kein eingebauter Default (0, wenn nicht gesetzt) — muss bei aktiviertem Chunking explizit konfiguriert werden
Attachments.ChunkAllAttachments	bool	Default false
Attachments.BaseDirectory	string	Default Path.GetTempPath()
Validation.{Metadata,Data,Attachments}	bool	Default true. Validatoren ein-/ausschalten; Funde landen im Report

Übersicht der Default-Umgebungen

	PROD	STAGE	TEST
AuthBaseURL	https://auth-prod.fit-connect.fitko.net/token	https://auth-refz.fit-connect.fitko.net/token	https://auth-testing.fit-connect.fitko.dev/token
RoutingBaseURL	https://routing-api-prod.fit-connect.fitko.net	https://routing-api-prod.fit-connect.fitko.net¹	https://routing-api-testing.fit-connect.fitko.dev
SubmissionBaseURLs	https://prod.fit-connect.fitko.net/submission-api	https://stage.fit-connect.fitko.net/submission-api	https://test.fit-connect.fitko.dev/submission-api
SelfServicePortalBaseURL	https://portal.auth-prod.fit-connect.fitko.net	https://portal.auth-refz.fit-connect.fitko.net	https://portal.auth-testing.fit-connect.fitko.dev
DestinationBaseURL	https://prod.fit-connect.fitko.net/destination-api	https://stage.fit-connect.fitko.net/destination-api	https://test.fit-connect.fitko.dev/destination-api
allowInsecureKeys	false	false	true

¹ STAGE hat keine eigene Routing-API – die PROD-Routing-URL wird als Fallback verwendet.