Skip to main content

Declarative system configuration

What is it for?​

The backend API of docuteam Context offers functionality to declaratively set up archives and their included configurations using versioned YAML files.

The typical use cases are:

  • preparing and reviewing configuration changes before applying them,
  • keeping a readable history of configuration changes,
  • reusing the same setup in another environment,
  • restoring a known configuration state.

The API uses unique global roles:

  • '@system-config:getConfig' for the get endpoints
  • '@system-config:applyConfig' for the apply endpoints

What can you configure?​

The configuration currently covers these archive-level settings:

  • attachment connection settings,
  • app configuration,
  • box connections,
  • concept schemes,
  • enumerations,
  • rules,
  • forms.

Structure of the configuration​

This is an example configuration which includes all configurable entities:

version: 1
archives:
  - name: myArchive
    attachment:
      connection:
        region: context
        endpoint: http://localhost:9000
        accessKey: admin
        secretKey: ENV(SECRET_KEY)
        bucketName: context-s3-mock
        downloadUrlMaxAgeInSeconds: 60
        maxFileSizeInBytes: 5368709120
        allowedMimeTypes:
          - application/pdf
          - image/jpeg
    appConfig:
      appTitle: Development server
      header:
        icon: <encoded_image>
        backgroundColor: "#FFFFFF"
        textColor: "#000000"
      menu:
        backgroundColor: "#FFFFFF"
        textColor: "#000000"
        textColorHover: "#222222"
    conceptSchemes:
      - name: Persons
    boxConnections:
      - name: public-box
        url: https://example.com/box
        namespace:
          - public
        token: ENV(SECRET_KEY)
    enumerations:
      - name: AgentRelators
        type: regularEnumeration
        data:
          processInfoArchivist:
            de: processInfoArchivist
            en: processInfoArchivist
            fr: processInfoArchivist
          staff:
            de: staff
            en: staff
            fr: staff
    rules:
      - name: Publication
        type: accessRestrictionRule
        data:
          label:
            de: Sichtbar für anonyme Besucher
            en: Visible to anonymous visitors
            fr: Visible pour les visiteurs anonymes
          description:
            de: Alle Benutzer sehen alles
            en: All users see everything
            fr: Tous les utilisateurs enregistrés voient tout
          permissions:
            - group: public
              policy: publishMetadataAndDigitalObjects
            - group: fullAccess
              policy: publishMetadataAndDigitalObjects
            - group: partialAccess
              policy: publishMetadataAndDigitalObjects
    forms:
      - name: "[Record] Agents with Relator Enumeration"
        type: recordResourceForm
        data:
          sections:
            - content:
                - property: refCodeAdmin
                  readonly: true
                - property: unitTitle
                  required: true
                - relation: hasAgent
                  relatorEnumeration: AgentRelators
                  repeat: true
                - relation: hasAgent
                  relator: origination
        active: true

version denotes the current version of the implementation

archives is a list of the existing archives. The name property denotes the unique identifier of each archive. If you want absolutely no configuration state, you can leave the value of archives empty. The minimal valid configuration is therefore:

version: 1
archives:

connection defines a connection point for attachments. It can be left empty to not include a connection but if you want to configure it, you must include all of region, endpoint, accessKey, secretKey, bucketName, downloadUrlMaxAgeInSeconds, maxFileSizeInBytes, allowedMimeTypes.

appConfig configures the appearance of the application. All its properties are optional, so it can either be left fully empty or include only the desired ones.

boxConnections is a list of box connections. It can be left empty to not include any connections. If a connection is added it must include all of name, url, namespace and token.

conceptSchemes is a list of the concept schemes. It can be left empty to not include any concept schemes. Note that the concept scheme 'locationManagement' is always created together with an archive and cannot be removed independently.

enumerations is a list of the enumerations. It can be left empty to not include any enumerations. If an enumeration is added it must include all of name, type and data.

rules is a list of the rules. It can be left empty to not include any rules. If a rule is added it must include all of name, type and data.

forms is a list of the forms. It can be left empty to not include any forms. If a form is added it must include all of name, type, data and active.

The minimal configuration for a single archive is therefore:

version: 1
archives:
  - name: myArchive
    attachment:
      connection:
    appConfig:
    conceptSchemes:
    boxConnections:
    enumerations:
    rules:
    forms:

Note: Under the data property of enumerations, rules and forms, the contents of the specific entity are defined. There is no further validation of the contents in the data property.

Environment variables​

Secret properties can reference environment variables by using ENV(<env_variable_key>) as the value.

After applying a configuration, a subsequent read operation will remember the applied environment variables names and export the secret values as ENV(<env_variable_key>).

If a secret's environment variable name was never recorded (e.g. it was set as a literal value instead of an ENV(...) reference), the exported value is masked as "****" with a comment indicating the usage of the ENV(...) function:

secretKey: "****" # use ENV(KEY_NAME) to reference a secret environment variable

Reapplying such a value unedited fails the request, since **** is not a valid secret value or environment variable reference.

Fetching the current configuration​

Use the GET /api/system-config/get endpoint to export the current system configuration as YAML.

The response content type is application/yaml.

The endpoint returns the configuration serialized as YAML text, i.e. the response body is a YAML string rather than a JSON object.

The endpoint GET /api/system-config/get/as-file returns the same YAML content as a downloadable file with the name system-config.yaml.

Flags​

The endpoint supports the following optional query flag:

  • includeInfo=true
    Adds an info section at the top of the exported YAML. This section contains metadata about the export:
    • date: the timestamp of the export in ISO format,
    • user: the username of the authenticated user if available.

If the flag is omitted, or set to any value other than true, the info section is not included.

Examples​

Fetch the current configuration without metadata:

curl \
  -H "Accept: application/yaml" \
  -H "Authorization: Bearer <access-token>" \
  "http://localhost:3333/api/system-config/get"

Fetch the current configuration including export metadata:

curl \
  -H "Accept: application/yaml" \
  -H "Authorization: Bearer <access-token>" \
  "http://localhost:3333/api/system-config/get?includeInfo=true"

Example response with includeInfo=true:

version: 1
archives:
  - name: myArchive
    attachment:
      connection:
    appConfig:
    conceptSchemes:
    boxConnections:
    enumerations:
    rules:
    forms:
info:
  date: 2026-06-10T12:00:00.000Z
  user: alice

The exported YAML can be reviewed, versioned and later submitted again to the apply endpoint. If an info section is present, it is ignored during import.

Applying a configuration​

Use the POST /api/system-config/apply endpoint to validate and apply a YAML configuration.

Send the YAML document itself as the raw request body with content type application/yaml.

The request body is parsed as plain text first and then interpreted as YAML. In other words, the endpoint expects a YAML string body.

The endpoint POST /api/system-config/apply/as-file accepts the same YAML content as a file upload.

Flags​

The endpoint requires the query parameter dryRun=true or dryRun=false to indicate whether the configuration should be applied or just validated (dry run). On dryRun=true the system validates the YAML, resolves environment-variable references, compares the desired state with the current state and returns the planned changes, but does not apply them.

Examples​

Validate a configuration without applying it:

curl \
  -X POST \
  -H "Content-Type: application/yaml" \
  -H "Authorization: Bearer <access-token>" \
  --data-binary @system-config.yaml \
  "http://localhost:3333/api/system-config/apply?dryRun=true"

Apply a configuration:

curl \
  -X POST \
  -H "Content-Type: application/yaml" \
  -H "Authorization: Bearer <access-token>" \
  --data-binary @system-config.yaml \
  "http://localhost:3333/api/system-config/apply?dryRun=false"

Response​

The endpoint returns a plain-text status report describing the result of the validation and apply process..

Typical responses are:

  • No changes
    The submitted configuration already matches the current system state.

  • A list of planned or executed changes, for example:

    update Archive myArchive
    - attachment.connection.endpoint: http://old.example -> http://new.example

  • If changes were actually applied successfully, the response ends with:

    Changes applied successfully.

Validation and environment variables​

During import, the YAML is parsed and validated strictly:

  • invalid YAML syntax,
  • missing required properties,
  • unknown properties,
  • duplicate archive names or duplicate box connection names within the same archive result in a 400 Bad Request.

Environment variable references in the form ENV(MY_KEY) are resolved during import. If a referenced environment variable is missing, the request fails.

An exported file with an info block can be sent back to the apply endpoint unchanged, because the info block is ignored during import.