Import/Export & Dry-Run

Common Contract

Most configuration domains implement:

  • POST /<domain>/import (multipart file upload) – validates and persists.

  • POST /<domain>/import/dry-run – validates and reports changes/errors without persisting.

  • GET /<domain>/export – exports DB state into a domain format.

  • Import mode query parameter: ImportMode (REPLACE or MERGE) (src/main/java/com/friendly/ftconfigsservice/utils/ImportMode.java).

Import Modes

MERGE

  • Upserts items found in the import payload.

  • Keeps existing DB rows not present in the payload.

REPLACE

  • Makes DB state match the payload.

  • For northbound configuration specifically, missing keys must be reset to defaults (not deleted).

Dry-run semantics

Dry-run is required as a pre-flight check:

  • If dry-run reports errors, import must be blocked by the caller (UI/backend integration).

  • Imports still perform validation and can fail even when dry-run is skipped.

Domain Example: Tabs JSON import

Implementation: TabImportService (src/main/java/com/friendly/ftconfigsservice/angular/tabs/service/TabImportService.java).

  • Input: JSON array of TabGroupDto objects containing group path and nested items.

  • Dry-run: compares incoming payload against DB state using business keys (group path, item path) and emits DryRunResult.

  • Import: recomputes the diff and applies create/update/delete operations depending on ImportMode.

Important note: the Hazelcast tabs map is not refreshed by this flow today (see Caching Strategy).

Domain Example: Northbound api.properties / Settings.xml

Implementation: NorthboundImportService (src/main/java/com/friendly/ftconfigsservice/northbound/importing/NorthboundImportService.java).

  • Accepts either:

    • api.properties (Java properties format)

    • legacy Settings.xml (auto-detected by filename or leading < bytes)

  • Resolves aliases (NorthboundAliasResolver) and normalizes values (NorthboundValueNormalizer).

  • Validates values against entry metadata (NorthboundConfigValidator) and produces a list of errors during dry-run.

  • In REPLACE mode: any entries missing from the upload are reset to their default_value (or blank).

Sequence: Dry-run import (northbound)

ft-configs-seq-import-dryrun

Sequence: Import (northbound)

ft-configs-seq-import-apply