3.2. Domains

A domain is an independent storage target: its own template catalogue, its own on-disk area, and its own upstream storage server. One TOA server can host several domains side-by-side - for example one for production traffic and one for an isolated test environment.

Domains are declared as a YAML list under toa-server.domains. Each entry has the following sub-blocks, all documented on this page:

toa-server:
  domains:
    - code: production          # identification
      name: Production domain
      templates:                # template catalogue source
        url: https://cmserver.customer.cz/cmserver2.xml
        refresh: 24h
      docAttributes:            # per-domain attribute overrides (optional)
        - id: "Cislo Jednacie"
          serverGenerated: true
      storageServer:            # upstream storage server
        url: https://damis.customer.cz/damis/upload
        domain: b2

A complete example is at the end of this page. At least one domain must be configured for the server to accept any import calls.

3.2.1. Identification

- code: production
  name: Production domain

code

Stable identifier of the domain. It appears in every API path (/import/<code>/...) and is used as the subfolder name under dataRoot. Use a short lowercase ASCII string with no spaces.

The code is the contract between the running server and the existing on-disk data; never rename a code once imports have landed on disk - the server will look for the new subfolder and the old one becomes orphaned. To retire a domain, keep the entry until its data has been archived off the host, then remove it.

name

Human-readable label. Presented to users in the Outlook add-in domain picker when more than one domain is configured. May contain spaces and diacritics; quote the YAML value when it contains special characters.

3.2.2. Template catalogue

Each domain has a template catalogue - an XML file in the legacy cmserver format that lists the document types (<Template> entries) available in that domain. The server parses the catalogue at startup and re-reads it on a configurable schedule. The catalogue is declared under templates: with exactly one source set, either local or remote.

Local file

templates:
  path: /opt/toa-server/config/cmserver2.xml

Loaded once at startup. The file must be readable by the service account. Use this mode when the customer manages the catalogue by hand and redeploys the server after changes.

path may be absolute (recommended) or relative to the server’s working directory. Relative paths under the config/ folder survive an upgrade because the operator copies the config forward (see Upgrading an existing installation).

Remote URL

templates:
  url: https://cmserver.customer.cz/cmserver2.xml
  refresh: 24h

Fetched over HTTP(S) at startup and then again every refresh interval. refresh accepts the Spring Boot duration syntax (30m, 6h, 2d, …); the default when the key is omitted is 24 hours. The URL must be reachable from the server host (see Prerequisites).

Downloaded catalogues are cached on disk at <dataRoot>/<code>/cmserver2.xml. The cache serves two purposes:

Fallback on download failure. If a scheduled refresh fails, the previous cached copy stays in use and an error is logged. The server does not fall back to an empty catalogue.
Survival across restarts. When the server starts and the remote URL is unreachable but a cached copy exists, the cache is loaded and a background retry is scheduled.

On the very first start, if the remote URL is unreachable and no cache exists yet, the domain has no catalogue and its API calls return 404. The server retries the download every 5 minutes until it succeeds.

Exactly one of path and url must be set; configuring both or neither is a startup error.

3.2.3. Document attribute overrides

docAttributes:
  - id: "Cislo Jednacie"
    serverGenerated: true

docAttributes[] overrides the behaviour of attributes defined in the cmserver XML without modifying the catalogue itself. Each entry is matched by the attribute’s id (the value of the id XML attribute on <Attribute> elements) and applies across every template in the domain.

Currently the only supported flag is:

serverGenerated

When true, the attribute’s value is filled in by the storage server (or by the TOA server for the storage server’s benefit) at the moment of upload. The Outlook add-in’s per-document form hides this attribute, so the end user is never asked to enter a value that would be overwritten anyway.

Use this flag for fields whose value is conceptually chosen by the upstream system (case numbers, internal identifiers, …). Leaving the flag off makes the field editable in the client.

The section is optional. When omitted, every attribute defined in the catalogue is presented to the user as entered.

3.2.4. Upstream storage server

storageServer:
  url: https://damis.customer.cz/damis/upload
  domain: b2
  # debugDir: /var/lib/toa-server/data/debug-b2

The storageServer block configures where the TOA server forwards a completed import when the user clicks Submit in the add-in.

url

Base endpoint of the upstream system (typically a Damis instance) that accepts the submission request. The TOA server posts the manifest XML and the document ZIP to this URL. It must be reachable from the server host.

domain

Damis input domain name, sent as part of the submission protocol. Not to be confused with the TOA code above - this is the label by which the Damis side identifies the target drawer, and is provided by the customer’s Damis administrator.

debugDir (optional, troubleshooting only)

Writable directory. When set, the outgoing Damis payloads (the submission XML and the ZIP of documents) are written to this directory as files instead of being sent over HTTP. Server- generated attribute values are replaced with deterministic placeholder values derived from a timestamp.

Use it to capture the exact bytes the server would send to Damis when debugging an integration issue; clear it once the issue is resolved so real submissions resume. Nothing ever leaves the server host while this key is set.

3.2.5. Complete example

Two domains on a single host - a live production domain backed by a remote cmserver catalogue, and a parallel test domain backed by a static local XML file:

toa-server:
  dataRoot: /var/lib/toa-server/data
  domains:
    - code: production
      name: Production domain
      templates:
        url: https://cmserver.customer.cz/cmserver2.xml
        refresh: 24h
      docAttributes:
        - id: "Cislo Jednacie"
          serverGenerated: true
      storageServer:
        url: https://damis.customer.cz/damis/upload
        domain: b2

    - code: test
      name: Test domain
      templates:
        path: /opt/toa-server/config/cmserver2-test.xml
      storageServer:
        url: https://damis-test.customer.cz/damis/upload
        domain: b2-test
        debugDir: /var/lib/toa-server/data/test/debug