Operating And Maintaining XDM

This chapter describes typical maintenance activities for an XDM installation. It covers monitoring, regular housekeeping, database maintenance, security and lifecycle aspects, and specific system checks such as rebuilding the configuration graph and checking the administration database.

Where helpful, examples are provided for both Docker and Kubernetes deployments.

Monitoring And Logging

Monitoring And Logging Overview

A production XDM installation should be monitored continuously. At minimum, you should watch the following aspects:

  • System resources of the XDM services

  • Throughput and health of task executions

  • Health of the administration database

  • Availability of the user interface and APIs

Key Metrics To Monitor

The following metrics are typically monitored:

  • CPU usage of the core, dataflow and UI containers or pods

  • Memory usage of these containers or pods

  • Disk space usage of:

    • XDM data volumes (task work directories, Icebox, logs)

    • Administration database volumes

    • Optional components such as ElasticSearch, Grafana or Prometheus

  • Task throughput:

    • Number of running, successful and failed task executions

    • Average runtime of tasks and workflows

  • Administration database health:

    • Connection errors or timeouts

    • Size and growth of the database and transaction logs

    • Latencies of common queries

You can use the internal Spring Boot metrics exposed by the core service and visualize them in dashboards.

  • Kubernetes

  • Docker

  • Define resource limits and requests for the core and dataflow pods.

  • Use the cluster monitoring stack (such as Prometheus and Grafana provided by the platform) to monitor pod resources and application metrics.

  • Configure alerts for:

    • Pod restarts

    • Failing readiness or liveness probes

    • Low free space on persistent volumes

  • Use your infrastructure monitoring solution (for example Checkmk or Nagios) to monitor:

    • CPU, memory and disk usage of the Docker host

    • Health of the core-server, dataflow-server, web-ui and database containers

  • Optionally use the provided Prometheus and Grafana containers to collect and visualize XDM metrics.

Optional Monitoring Components (Grafana And Prometheus)

XDM can be configured with Grafana and Prometheus containers for reporting and monitoring. These components are optional and only used for reporting and dashboarding; the core XDM functionality does not depend on them.

If you do not need reporting yet, you may disable these containers without affecting core operation. You can re‑enable these services later if you want to use the preconfigured dashboards.

  • Kubernetes

  • Docker

In a Helm‑based installation, the chart may expose flags to enable or disable Grafana and Prometheus, for example:

grafana:
  enabled: false

prometheus:
  enabled: false

In docker-compose.yml, the grafana and prometheus services can be disabled by commenting them out or removing them:

services:
  # grafana:
  #   image: grafana/grafana:...
  #   ...

  # prometheus:
  #   image: prom/prometheus:...
  #   ...

Log Levels And Typical Loggers

Use log levels carefully to balance diagnostic information and log volume.

  • Normal operation:

    • INFO for root and most application packages

  • Troubleshooting:

    • Temporarily use TRACE for selected loggers

Typical logger categories:

  • HTTP / REST requests:

    • org.springframework.web

    • org.springframework.web.client

  • Security and authentication:

    • org.springframework.security for login, SSO and role mapping analysis]]

  • JDBC and database access:

    • org.springframework.jdbc

    • org.hibernate.SQL (if applicable)

  • Configuration as Code or Git integration:

    • Package names used by your CasC implementation (for example casc or similar)

For login‑related issues with an external authentication provider, you can increase the Spring Security logger to TRACE to inspect token details and roles.

  • Kubernetes

  • Docker

In a Helm deployment, configure additional environment variables for the core pod, for example in values.yaml:

core:
  extraEnv:
    - name: logging.level.root
      value: INFO
    - name: logging.level.org.springframework.web
      value: INFO
    - name: logging.level.org.springframework.security
      value: INFO

Adjust the keys to match the chart’s configuration options.

In docker-compose.yml, set log levels for the core-server service:

logging.level.root=INFO
logging.level.org.springframework.web=INFO
logging.level.org.springframework.security=INFO
# For troubleshooting only:
# logging.level.org.springframework.security=TRACE

Restart the core-server container after changing these settings.

Integration With External Monitoring And Logging

XDM can be integrated into standard enterprise monitoring and logging solutions.

  • Monitoring:

    • Use the system metrics exported by the Docker host or Kubernetes nodes.

    • Use XDM’s internal metrics (Spring Boot actuator endpoints) as data sources.

  • Logging:

    • Forward container logs to a central logging system (for example Loki, ELK/Opensearch) via your container runtime or log agents.

  • Kubernetes

  • Docker

  • Use a cluster‑wide logging solution (for example FluentD/Fluent Bit + Loki).

  • Use liveness and readiness probes on the core and web UI deployments and include them in your monitoring dashboards.

  • Configure Docker to use a logging driver that forwards logs to your central logging stack (for example Loki).

  • Collect host metrics and basic container health with your existing monitoring tools.

Regular Housekeeping

Regular Housekeeping Overview

Over time, XDM accumulates task and workflow executions, work files, logs and Session data. Regular housekeeping helps to:

  • Keep disk usage under control

  • Maintain a clear overview in the UI

  • Avoid unnecessary growth of the administration database

XDM provides several mechanisms for automatic cleanup of executions and related data.

Automatic Cleanup Of Task Executions And Files

Overview

Using XDM over time creates many tasks, workflows and corresponding executions. These consume resources and make it harder to keep an overview.

XDM offers several methods to automatically delete obsolete executions, tasks and workflows:

  • Task properties

  • System‑wide retention properties

  • Hooks for deleting expired tasks and workflows

XDM supports both task‑level and system‑level cleanup.

Task Level Settings

Delete Working File On Success

The Delete working file on success property:

  • Clears the task working directory at the end of the copy if the copy is successful.

  • Leaves the task execution in the execution list for reporting and audit purposes.

When Delete Execution File on Success is set, the Task Execution Export does not contain the deleted files. As a consequence, it may be difficult or even impossible to analyze a task that ran successfully but did not produce the expected result.
Execution Retention Period

The Execution Retention Period property:

  • Deletes the task execution and all working directories from the list after a retention period configured on the task.

  • All expired objects will be automatically deleted by a cron job.

It is recommended to set a custom default value in System Settings → System Configuration → Configure property defaults for this parameter. All new task templates will use this Execution Retention Period.

System Level Settings

The core server can automatically delete executions and work files based on a global retention period:

  • Execution retention:

    • xdm.core.executionRetentionPeriod=<duration> – time after which files and other execution‑related data are cleaned up.

  • Cleanup retry wait time:

    • xdm.core.cleanupWaitTime=<seconds> – time between cleanup attempts when executions are still running.

  • Delete files when tasks are deleted:

    • xdm.core.cleanup-executions-on-task-delete=true – delete work files and logs when a task or task template is deleted.

  • Cleanup schedule:

    • xdm.execution.cleanup-cron=<cron-expression> – cron expression controlling when the cleanup process runs.

The duration uses the standard ISO‑8601 duration or period syntax such as P90D. More information about the properties can be found here.

  • Kubernetes

  • Docker

In a Helm deployment, add the properties as environment variables for the core pod:

core:
  extraEnv:
    - name: xdm.core.executionRetentionPeriod
      value: P90D
    - name: xdm.core.cleanupWaitTime
      value: "10"
    - name: xdm.core.cleanup-executions-on-task-delete
      value: "true"
    - name: xdm.execution.cleanup-cron
      value: "0 0 0 * * ?"

Apply the updated Helm values to roll out the changes.

In docker-compose.yml, under services→core-server→environment:

# Delete executions and work files after 90 days
xdm.core.executionRetentionPeriod=P90D

# Optional: wait 10 seconds between cleanup attempts
xdm.core.cleanupWaitTime=10

# Delete work files and logs when a task or template is deleted
xdm.core.cleanup-executions-on-task-delete=true

# Run the cleanup job daily at midnight
xdm.execution.cleanup-cron=0 0 0 * * ?

Restart the core-server container after changing these properties.

Hooks Delete Expired Workflows And Delete Expired Tasks

Over time, XDM may create many implicit tasks and workflows, for example via data shops or runTemplate calls. To keep the system clean, XDM provides hooks:

These hooks:

  • Delete implicitly created tasks and workflows. If implicitOnly is set to false, also explicitly created tasks and workflows are deleted during execution.

  • Also delete their associated executions.

  • Work retrospectively on existing objects. They remove existing objects, not only newly created ones.

  • Only work on tasks and workflows in which they are configured.

Recommended usage:

  • Configure the task hook as hook usage on the task template.

  • Verify that all relevant templates use this hook and that retention periods match your policies.

  • Call the workflow hook from within workflows using runHook().

These hooks are configured within XDM. They are particularly useful when using data shops and runTemplate calls in workflows, because many implicit objects can be created over time.

Manual Cleanup Of Temporary Data And Old Files

Even with automatic cleanup, you should regularly check for:

  • Large Icebox generations that are no longer needed

  • Old backups of configuration or lookup tables stored in XDM volumes

Depending on your policies, delete or archive these files outside XDM (for example using filesystem tools or storage snapshots).

Monitoring Disk Usage Of Data And Backup Volumes

Monitor disk usage for:

  • XDM data volumes (task work files, logs, Icebox, lookup tables)

  • Administration database volumes

  • Optional volumes for ElasticSearch or Grafana

  • Kubernetes

  • Docker

  • Monitor persistent volume claims (PVCs) with kubectl get pvc.

  • Use the cluster’s storage and volume metrics to create alerts for high usage.

  • If you use storage snapshots for backup, monitor snapshot counts and retention.

On the Docker host, monitor:

  • Disk usage using tools such as df -h and du -sh <path>

  • Sizes of directories bound into the containers, for example:

    • XDM data directory

    • PostgreSQL data directory

      Integrate these checks into your monitoring platform.

Database Maintenance

Administration Database Responsibilities

XDM uses a PostgreSQL administration database to store all configuration objects and their history.

This database holds:

  • All XDM configuration objects (tasks, workflows, connections, environments, etc.)

  • Object history data

  • Certain logs and session information

The database must be:

  • Regularly backed up

  • Monitored for size, performance and transaction log growth

  • Maintained according to your database best practices

Checking Configuration Object Consistency

In System Settings → System Configuration, the following actions are available:

  • Rebuild configuration objects graph

  • Check consistency of configuration objects

The Check consistency of configuration object option:

  • Verifies that all XDM configuration objects are in a valid state

  • Lists any defective objects, which can then be investigated and repaired or deleted

  • Helps resolve issues where some object lists do not display correctly

Run this action when you suspect configuration issues or periodically as part of regular maintenance, especially:

  • After major configuration changes

  • After migrations or updates

  • When object lists do not display correctly

Regular Database Health Checks

In addition to XDM‑specific checks, follow your DBMS best practices:

  • Monitor:

    • Table and index sizes

    • Growth of the main database and the transaction log

    • Slow queries

  • Schedule:

    • Regular statistics updates (ANALYZE)

    • Regular maintenance tasks (VACUUM or vendor‑equivalent)

    • Checks for corruption, if supported by your database tools

For environments using external PostgreSQL, coordinate maintenance with your database team.

  • Kubernetes

  • Docker

For PostgreSQL running inside the cluster:

  • Use Kubernetes Jobs or CronJobs with psql commands to run maintenance.

  • Use persistent volume snapshots where applicable.

    For managed PostgreSQL services:

  • Use the provider’s built‑in monitoring, backup and maintenance features.

With the bundled PostgreSQL container:

  • Access the database via docker exec and run standard PostgreSQL maintenance commands.

  • Use pg_dump or volume snapshots for backups. (see Backup and Restore for more details)

    With an external PostgreSQL instance:

  • Apply your organization’s regular backup and maintenance policies.

Security And Lifecycle

Security And Lifecycle Overview

Security maintenance should be part of regular operations:

  • Rotate technical credentials

  • Keep TLS certificates and trust stores up to date

  • Review user management and permissions

  • Adjust JWT and password encryption settings when policies change

  • Plan and test backup and restore procedures

Rotating Technical Credentials

Rotate the following credentials regularly:

  • Administration database user and password

  • Credentials for external databases and systems stored in XDM connections

  • API keys for services such as AI assistance (spring.ai.openai.api-key)

XDM stores technical connection passwords encrypted in the administration database using a password seed. The Section Password encryption seed describes, how the seed is configured.

  • Kubernetes

  • Docker

  • Change the credential in the PostgreSQL database to <new-password>. Afterwards, store database and API credentials in Kubernetes Secrets and reference them from the Helm values, for example:

    database:
extern: true
url: jdbc:postgresql://dbhost:5432/xdm
user: xdm_admin
password: <new-password>

    or:

    core:
extraEnv:
- name: SPRING_DATASOURCE_PASSWORD
valueFrom:
secretKeyRef:
name: xdm-db-secret
key: password

    Rotate the secrets and roll the affected deployments.

  • For the admin database:

    Change the credential in the PostgreSQL database to <new-password>. Afterwards, set in docker-compose.yml:

    SPRING_DATASOURCE_USERNAME=xdm_admin
SPRING_DATASOURCE_PASSWORD=<new-password>

    Restart the core-server container after changing credentials.

  • For AI assistance:

    ai-assistance:
  environment:
    - spring.ai.openai.api-key=<new-openai-api-key>

  • Update connection credentials through the XDM UI; XDM will re‑encrypt them automatically.

Managing TLS Certificates And Trust Stores

TLS can be used for:

  • Securing access to the XDM UI

  • Securing communication to external systems and databases

Certificates must be renewed before they expire.

  • Kubernetes

  • Docker

Use an Ingress with a Kubernetes TLS secret, for example:

ingress:
enabled: true
domain: xdm.example.com
tls:
- hosts:
- xdm.example.com
secretName: xdm-tls

Renew the certificate by updating the xdm-tls secret. The Ingress controller will start using the new certificate automatically.

For the XDM web UI, you can configure certificate files via mounted volumes:

services:
  web-ui:
    volumes:
     - ./certificates:/xdm/certificates
    environment:
     - https_key_file=/xdm/certificates/xdm.key
     - https_certificate_file=/xdm/certificates/xdm.crt
     - xdm_core_serverUri=http://core-server:8000/api/

To renew the certificate:

  • Replace xdm.key and xdm.crt in the local ./certificates directory.

  • Restart the web-ui container.

Reviewing User Management And Permissions

Regularly review:

  • User accounts and roles (both internal and from external identity providers such as LDAP or OpenID Connect)

  • Default permissions and list access permissions

  • Permission recipients and their object ownership

In System Settings → Permission Management and Permission recipient you can:

  • See all permission recipients

  • Adjust default permissions and list access

  • Transfer ownership of objects

  • Export and import permission recipients between environments

External user management:

  • For LDAP or OpenID Connect, ensure that role mappings and attributes (names, email addresses) are correctly received and used in XDM.

  • If needed, temporarily increase org.springframework.security logging to TRACE for deeper analysis.

JWT And Password Encryption Settings

XDM uses JSON Web Tokens (JWT) to authorize access to HTTP REST endpoints.

Configurable properties include:

  • Login token expiration time:

    xdm.core.jwt.token-expire-time=<minutes>

  • Execution token valid time:

    xdm.core.jwt.token-valid-time=<minutes>

  • JWT secret:

    xdm.core.jwt.secret=<your-secret> – must be at least 32 characters long.

After changing the secret:

  • Restart the core server

  • All new tokens will use the new secret

  • Already scheduled tasks may fail, because they use tokens created before the change; therefore, avoid changing the secret unless necessary.

XDM also encrypts stored passwords using a seed. More information about the seed settings can be found in the JWT settings.

Backup, Restore And Disaster Recovery

Backups are essential for disaster recovery:

  • All administrative and configuration data are stored in the PostgreSQL administration database and can be backed up using PostgreSQL or container tools.

  • Depending on your use of Icebox and other features, you may also need to back up XDM data volumes.

Plan and test:

  • Regular database backups (for example using pg_dump or volume snapshots)

  • Regular restore tests in a separate environment

  • Procedures to recreate an XDM instance from:

    • A database backup

    • The configuration (including any Configuration as Code repositories)

For more technical details of the backup and restore process refer to Backup and Restore process.

Rebuilding The Graph Database

Overview

XDM maintains a graph of configuration object dependencies.

The Rebuild Graph process:

  • Drops the existing configuration objects graph

  • Recreates it by reading all XDM objects from the administration database

  • Is used to restore internal consistency

  • Is not a system update and does not change the application version

Preparation

During the rebuild, no XDM objects must be modified.

Before starting the rebuild:

  • Make sure no users have access to XDM and cannot change objects.

  • Ensure that no tasks, workflows or data shop orders are running.

  • Ensure that no external scheduler triggers new tasks.

Otherwise, inconsistencies may arise that can make the system unstable. In the worst case, the entire XDM installation may need to be recreated.

Recommended steps:

  1. Plan a maintenance window.

  2. Block user access to the XDM UI (for example by disabling the Ingress in Kubernetes or the reverse proxy).

  3. Check that no task executions are running or queued.

Initiating The Rebuild

To start the rebuild:

  1. Log in as a user with the administrator role.

  2. Open System Settings.

  3. Go to the System Configuration tab.

  4. Click the Rebuild configuration objects graph action (labeled Rebuild Graph in the UI).

The rebuild can take some time depending on the amount of configuration data.

Technical Background

The configuration objects graph:

  • Stores dependencies between XDM configuration objects

  • Is used to resolve relationships efficiently at runtime

The Rebuild Graph function:

  • Completely drops the existing graph

  • Rebuilds it from the current state of the administration database

Therefore:

  • It is crucial that no changes are made to XDM objects during this process.

  • Ensure that no workflows, data shop orders or tasks are executed while the graph is being rebuilt.

Depending on your installation, you should also:

  • Kubernetes

  • Docker

  • Optionally disable the Ingress or apply a maintenance page to prevent user access during the rebuild.

  • Ensure that no external scheduler or REST client starts tasks while the maintenance window is active.

When using a premium XDM license, you can also use the Maintenance Mode to disable this actions.

The process itself does not modify business data in external systems; it only reconstructs XDM’s internal dependency graph.

Using XDM could accumulate created tasks or workflows and corresponding executions over time, which may use valuable resources and complicate one’s own overview. In order to facilitate your work with XDM, there are several methods to automatically delete obsolete executions.

Delete Execution File on Success

Clears the task working directory at the end of the copy, if the copy is successful. The task execution remains in the list. Refer to Delete working file on success for more information about the task property.

Execution Retention Period

Deletes the task execution from the list after a retention period that is set in the task. The retention period becomes only active, if it is set before executing the task. The property is not applied to existing task executions. Refer to Execution retention period for more information about this task property.

It is recommended, that this task parameter should be set globally for all task templates using a custom default value.

Hooks Delete expired workflows and Delete expired tasks

The hooks Delete expired tasks and Delete expired workflows delete the implicitly created tasks and workflows and the executions attached to them. Existing objects are also deleted. This option is of particular interest when using data shops and runTemplate calls in workflows.

In summary, we would recommend using the hooks for deletion, since they work retrospectively and also delete the task and workflow objects that arise over time. The task hook can be configured as hook usage on the template. This should be the case for most, but it should be checked again everywhere and the time periods should be adjusted accordingly. The workflow hook is invoked via a runHook() call in the workflow itself.