Skip to content
Bauhaus

Configure Mutualized Code Lists

Mutualized code lists are the shared, read-only vocabularies offered in the “Reuse” selector of a coded variable. This guide declares which lists are mutualized, tunes how they are fetched, and refreshes them.

If nothing is configured, the module simply exposes no mutualized list — the application starts normally.

Pick a strategy

Section titled “Pick a strategy”

Two strategies produce the same result with different numbers of round-trips to Colectica.

package-walk (default)

Section titled “package-walk (default)”

Give the root package; Bauhaus walks its tree package → CodeListScheme → CodeListGroup → CodeList.

fr.insee.rmes.bauhaus.colectica:
  mutualized-codes-strategy: package-walk
  mutualized-codes-package:
    agency-id: fr.insee
    identifier: e129238f-485f-40b4-b52f-5702c05d5f40
    version: 1

Cost: 1 + N + M relationship queries, where N is the number of schemes and M the number of groups.

configured-groups

Section titled “configured-groups”

List the code list groups explicitly; Bauhaus queries each one’s children directly.

fr.insee.rmes.bauhaus.colectica:
  mutualized-codes-strategy: configured-groups
  mutualized-codes-groups:
    - agency-id: fr.insee
      identifier: 6755ebd7-82a4-4e8d-9b49-ba39a9ab3281
      version: 1

Cost: one relationship query per group. Prefer this when the tree is stable and you know the groups.

  • agency-id may be omitted or left blank — the instance’s defaultAgencyId is then used.
  • version is accepted for symmetry with mutualized-codes-package, but the relationship query is not versioned and ignores it.

Only one strategy is active at a time; mutualized-codes-package is read only by package-walk, and mutualized-codes-groups only by configured-groups.

Tune the cache

Section titled “Tune the cache”
fr.insee.rmes.bauhaus.colectica:
  mutualized-codes-cache-ttl: 24h      # Spring Duration; default 24h
  cache-warmup-enabled: true           # pre-load at startup; default true

Lower the TTL if the shared vocabulary changes often; disable the warm-up if you want a faster startup and accept that the first user pays for the walk.

See Caching Colectica Reads for what those settings actually govern.

Force a refresh

Section titled “Force a refresh”

Send the standard HTTP cache header on the listing endpoint:

Terminal window
curl -H "Authorization: Bearer $TOKEN" \
     -H "Cache-Control: no-cache" \
     http://localhost:8080/api/ddi/mutualized-codes-list

no-cache or no-store clears both mutualized cache regions, then recomputes the list from Colectica and re-caches it. Use this after publishing a new list in the mutualized package instead of restarting the backend.

Verify

Section titled “Verify”
Terminal window
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/ddi/mutualized-codes-list

Each entry carries agency, id, label, name and versionDate. In the interface, those lists appear under Mutualized code lists in the reuse selector, each with a padlock marking them read-only.

If the list is empty, check in order: the strategy actually set, the identifiers of the package or groups, and the backend log line emitted by the warm-up (Mutualized codes list cache warm-up finished: N entries loaded).