.. _configure-domains:

========
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:

.. code-block:: yaml

   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.

Identification
==============

.. code-block:: yaml

   - 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.

.. _configure-templates:

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
----------

.. code-block:: yaml

   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 :ref:`install-upgrade`).

Remote URL
----------

.. code-block:: yaml

   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 :ref:`install-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.

Document attribute overrides
============================

.. code-block:: yaml

   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.

Upstream storage server
=======================

.. code-block:: yaml

   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.

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:

.. code-block:: yaml

   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