Skip to content

0005 — Descartes envelope settings resolve DB → appsettings → built-in defaults

Status: accepted

Context

The SMF envelope wrapped around every declaration carries routing and identity fields Descartes uses to decide what the message is and where it goes: wsa_to, wsa_action, country code, company, legal entity, user, and per-section system / module / identity / template / folder.

They are not really application configuration. They are agreed with Descartes, they change when Descartes says so, and a wrong one means declarations land in the wrong place or are rejected outright. Putting them only in appsettings.json means a value Descartes changes on a Tuesday needs a build, a deploy and a restart of a live system before anything can be filed again.

The folder is different again: it varies per customs team within one company, so it cannot be a single global setting at all.

Decision

DescartesSmfWrapperService resolves each field through three levels, first non-empty wins:

  1. AppSettings in the database — descartes:* and descartes:{section}:* keys, editable through the admin UI at runtime
  2. appsettings.json — Descartes:{Section}:Smf*
  3. SectionDefaults — hardcoded, so a fresh environment produces a valid envelope with no configuration at all

The folder takes a fourth level on top: SmfEnvelopeInput.FolderOverride, supplied per dossier from CustomsTeam.ImportFolder / ExportFolder / TransitFolder. A team's folder therefore beats every global setting.

Sections are Import, Export and Transit. Within Import, H1B and H2B share the folder and the recipient; what distinguishes them is SubIdentity — "H1" vs "H2B" — set by the generator.

Consequences

  • A wrong envelope value is fixed in the admin UI, without a deploy. That is the whole point, and it matters most exactly when things are broken.
  • The effective value is not visible in the repository. appsettings.json may say one thing while production sends another, and reading the file will mislead you. To know what is actually being sent, read the AppSettings rows or the generated envelope.
  • Three levels is more machinery than most settings deserve. It is justified here because the bottom level keeps a fresh environment working, the middle level version-controls the intended values, and the top level is the escape hatch during an incident.
  • Per-team folder routing means adding a customs team is a data change, not a configuration change — but also that a team created without folders silently falls back to the global folder.