Using Configuration As Code (CasC) In XDM

Configuration as Code (CasC) allows you to manage XDM configuration in a Git repository instead of changing it only through the UI. Configuration objects are exported from an XDM environment as YAML-files and stored in Git. Other XDM environments then regularly pull from this repository and automatically import new or updated objects.

CasC integrates XDM into existing development processes and version control workflows. It makes all configuration changes transparent, reviewable and traceable in Git.

Concept And Use Cases

What Is Configuration As Code?

With CasC, most XDM configuration is treated like source code:

XDM objects are exported from one environment into files.
These files are committed to a central Git repository.
Other XDM environments periodically clone and pulls this repository.
XDM imports all commits that were done since the last import.

During import, XDM performs the following actions:

Objects that do not yet exist in the environment are created.
Existing objects are updated, but only if the version in Git is newer than the version in the environment.
Object identity is based on the object name.
The comparison is based on the lastChangedDate of each object: only if the Git version has a later lastChangedDate will the object be updated in the target environment.

When importing an object, all objects it references must already exist in the environment or be part of the same import. Otherwise the import of the referencing object will fail.

Typical XDM objects managed via CasC include:

connections
environments
tasks and task templates
workflows and workflow templates
application models and rules
modification methods and scripts

Objects that are created automatically at runtime (for example implicit tasks created from templates) are usually not managed via CasC.

Typical Deployment Scenarios

CasC is usually used with at least one development environment and one or more downstream environments.

Two‑Environment Setup (DEV → PROD)

In a minimal setup you use:

a development environment, for example XDM‑DEV
a production environment, for example XDM‑PROD

Workflow:

Configure and test changes on XDM‑DEV.
Export all relevant objects and commit them to Git.
XDM‑PROD regularly pulls from Git and imports new objects.

This setup is simple, but risky:

It is easy to forget parts of the configuration during export.
Import problems only appear directly on the production environment.
Differences between XDM-DEV and XDM-PROD (for example different connections) may cause errors during import or execution.

Three‑Environment Setup (DEV → TEST → PROD)

A more robust pattern uses a dedicated test environment:

XDM‑DEV – for developing and editing configuration.
XDM‑TEST – for validating configuration before production.
XDM‑PROD – productive XDM instance.

Typical Git branching model:

Branch xdm-test for configuration that should be deployed to XDM‑TEST.
Branch xdm-prod for configuration that should be deployed to XDM‑PROD.

Workflow:

Develop and test configuration changes on XDM‑DEV.
Export the relevant objects and copy them into the Git repository.
Commit the changes to branch xdm-test.
XDM‑TEST pulls from xdm-test and automatically imports new or updated objects.
On XDM‑TEST, verify:
- that all tasks and workflows still execute as expected,
- that all required objects were exported (no missing rules, methods, or connections),
- that environment‑specific differences (for example different connection URLs) are handled correctly.
Once the configuration is validated on XDM‑TEST, merge xdm-test into xdm-prod in Git.
XDM‑PROD pulls from xdm-prod and imports the merged changes.

This three‑stage approach significantly reduces the risk of deployment errors in production.

Preparing XDM Objects For CasC

CasC is based on the standard configuration export of XDM. You use the export action in the UI to produce files that are later stored in Git. More details are described in Export Options For CasC.

Selecting Objects For Export

When preparing a change set for CasC, always export all objects that logically belong together. A typical change may include:

modifications to an existing workflow template,
new or updated tasks referenced by that workflow,
new modification methods and rules,
additional connections or environments required by the workflow.

Exporting only parts of such a change will usually lead to missing references during import on downstream environments.

Before exporting, use the Usage and Uses views of relevant objects to find related objects that may also need to be exported.

Handling Referenced And Dependent Objects

XDM distinguishes between:

dependent objects – objects that belong exclusively to their parent, such as rules on a template or child objects of a version,
referenced objects – independent objects that are linked from others, such as connections and environments.

For CasC you typically want to include both:

Dependent objects so that templates, workflows and application models are exported with all their child rules.
Referenced objects (and optionally their dependents) so that the configuration can be recreated on another environment without manual steps.

Export Options For CasC

When you start the Export action on an object, XDM offers several options that control which related objects are included.

The relevant options are:

Include dependent objects
Include permissions
Include referenced objects
Include objects that depend on referenced objects
Include implicit created objects
format selection (for CasC: Export as Zip‑File)

Recommended Export Options

For CasC exports, the following settings are usually recommended:

Export as Zip-File Exports a ZIP archive that contains each XDM object as a separate YAML file. Script code (for example Groovy or JavaScript) is stored in separate files next to the YAML, with the same base name and an appropriate file extension such as .groovy or .js.
Include dependent objects – Enabled Ensures that all child objects of the exported objects are included, such as rules or task stage hook usages.
Include referenced objects – Usually enabled Includes independent objects that are referenced by the exported objects, such as connections or environments. If you disable this option, you must make sure to export these referenced objects separately.
Include objects that depend on referenced objects – Enabled when referenced objects are included Also includes the dependent objects of the referenced objects, for example:
rules of a modification set referenced by a task template,
rules of an application model version that is referenced.

This combination typically produces a self‑contained export suitable for CasC.

When To Exclude Permissions

The option Include permissions exports the permissions defined on each object, if the object type supports permissions.

For CasC it is often better to leave this option disabled:

Different XDM environments usually have different users and roles.
On XDM‑DEV users need permissions to create and edit objects.
On XDM‑TEST and XDM‑PROD most users should only be able to execute tasks and workflows, but not change configuration.

Instead of copying permissions via CasC, define default permissions on each target environment:

Default permissions assign appropriate rights when new objects are imported.
These default permission rules can themselves be exported and stored in Git, especially if you want to rebuild an empty environment from scratch.

Only if you explicitly want to replicate the permission model between environments should you enable Include permissions.

Implicitly Created Objects

The option Include implicit created objects controls whether objects that were automatically created by XDM for execution are included.

Examples:

tasks that were generated from task templates,
workflows that were generated from workflow templates.

For CasC these implicit runtime objects are usually not needed:

They will be created automatically in each environment during normal execution.
They are not part of the static configuration you want to distribute.

Explicitly created tasks and workflows that are part of your configuration are already covered when you export the corresponding objects with Include dependent objects.

If you do decide to export implicit objects, you must also enable Include dependent objects, otherwise their child objects will be missing.

Working With Git Repositories

After exporting objects as a ZIP file, you typically unpack it and copy its contents into a Git repository.

Repository Structure And Folder Layout

The folder structure inside the ZIP file is important:

It groups objects by type and sometimes by hierarchy.
It allows you to easily overwrite an older export with a newer one.
It keeps scripts next to their parent YAML files.

Do not manually rearrange the folder layout without a clear concept; otherwise later imports or diff‑based reviews become harder.

A simple example layout (illustrative only):

casc-repo/
  connections/
    XDM-Prod-DB-Oracle.yaml
  workflows/
    CustomerCopyWorkflow.yaml
    CustomerCopyWorkflow_main.groovy
  task-templates/
    CustomerCopyTemplate.yaml

Copying Exports Into The Repository

When copying new exports into the repository you have two basic strategies:

Copy everything from the export
Pro:
Simple process.

Git will always contain a consistent snapshot of the environment.
Contra:
Git may show many changes even when configuration did not meaningfully change (for example when only lastChangedDate changed).
Copy only selected files
Pro:
Git history stays focused on the objects that are actually part of your change.

Easier to review.
Contra:
Higher risk of forgetting dependent or referenced objects.

In both cases you should review the Git diff carefully:

XDM may export an object in a new format (for example due to a product upgrade).
Other users may have changed the same object in a way that is unrelated to your current change.
You may choose, line by line, which changes to keep and which to discard.

Reviewing And Committing Changes

Before committing:

Review YAML and script changes line by line.
Decide per change whether it should be part of the current deployment.
Ensure that all logically related objects are included.

When committing:

Use meaningful commit messages.
Optionally reference a ticket number (for example from Jira) to link the configuration change to a requirement or bug report.

Example commit message:

XDM-1234: Update customer anonymization workflow

- Adjusted CustomerCopyWorkflow
- Added new modification method for address anonymization
- Updated connection XDM-Prod-DB (URL and credentials via environment)

Handling Environment‑Specific Configuration

In practice some configuration is environment‑specific:

A connection that exists only on XDM‑PROD but not on XDM‑TEST.
Different database URLs, users or passwords per environment.
Scripts that should call different REST endpoints on DEV, TEST and PROD.

Importing a connection only on some environments can be problematic:

If the connection is missing on XDM‑TEST, but referenced by workflows or tasks, imports or executions may fail.

One common pattern is to maintain separate variants per environment in Git and control imports with a .casc-ignore file.

Example: Environment‑Specific Connections

Assume you have a connection XDM-Prod-DB that must exist in all environments, but with different technical details.

In Git you might store:

connections/
  XDM-Prod-DB-Oracle.yaml                # PROD version
  XDM-Prod-DB-Oracle-XDM-TEST.yaml       # TEST variant

On XDM‑PROD, the .casc-ignore file is configured so that:
XDM-Prod-DB-Oracle-XDM-TEST.yaml is ignored.
XDM-Prod-DB-Oracle.yaml is imported.
On XDM‑TEST, .casc-ignore ensures that:
XDM-Prod-DB-Oracle.yaml is ignored.
XDM-Prod-DB-Oracle-XDM-TEST.yaml is imported.

In both environments an object named XDM-Prod-DB is created, but with different internals (for example different JDBC URLs). The name must be identical so that workflows and tasks reference the correct connection without changes.

The exact syntax and location of .casc-ignore is environment‑specific and should be described in your internal operations documentation.

Example: Environment‑Specific Script Behavior

Scripts inside modification methods or workflows often need to behave differently per environment, for example:

call a different REST endpoint on DEV, TEST or PROD,
send notifications with a different email sender or to different messaging channels.

Where possible, keep a single script in Git and make it environment‑aware:

Define an environment name or identifier as an XDM parameter or environment setting.
In the script, read this value and branch the logic accordingly.

This example uses a different email address to send notification emails from depending on the current environment:

def envName = ctx.getEnvironmentName() // Example API, adapt to actual API

def emailSender
if (envName == 'XDM-DEV') {
    emailSender = "XDM-development@ubs-hainer.com"
} else if (envName == 'XDM-TEST') {
    emailSender = "XDM-test@ubs-hainer.com"
} else if (envName == 'XDM-PROD') {
    emailSender = "XDM-production@ubs-hainer.com"
}

// Send sucess message  to the current user
sendEmail(emailSender, user.email, "Execution finished successfully")

This keeps the script identical across environments while still supporting environment‑specific behavior.

CasC Import Process In XDM

CasC imports are executed by an internal scheduled job in XDM.

How The Scheduled CasC Job Works

On each environment that should consume configuration from Git:

XDM is configured with:

the URL of the Git repository,
credentials or deploy keys (if needed),
the branch to use (for example xdm-test or xdm-prod),
an execution interval (for example every few minutes or hourly).

An internal scheduled job (Configuration as Code Job) periodically:

clones the repository,
scans the configuration files,
compares them with the objects in the environment,
imports new or updated objects.

The job and its status can be monitored in:

System Settings → System Configuration → Internal scheduled jobs

There you can:

view the last run of the CasC job,
inspect the log of the last import,
manually start or stop the CasC job if needed.

Object Matching And Update Logic

When processing files from the repository, XDM:

identifies objects based on their name (not by internal IDs),
imports objects that do not yet exist,
compares lastChangedDate of repository objects with objects in the environment,
updates only those objects whose repository version is newer.

This prevents older configurations from overwriting newer changes made directly in the environment.

For a strict CasC process you should avoid manual changes on downstream environments (TEST and PROD). Instead, always change configuration on DEV and push it through Git.

Handling Missing References

If an object references another object that does not exist in the environment and is not part of the current import set, import will fail.

Typical examples:

A workflow that references a non‑existing connection.
A task that uses a modification method that was not exported.
An application model version that references missing rules.

To avoid this:

Always export and commit logically complete configuration sets.
Use Include referenced objects and Include objects that depend on referenced objects when exporting.
When deliberately omitting referenced objects (for example environment‑specific connections), use patterns like .casc-ignore and environment‑specific variants as described above.

When an object was missing during the export, you can export the missing files and then copy it into the Git repository. Use the amend commit process to add the missing objects to the existing commit. So there will only be one single and complete commit in Git.

Version Compatibility

XDM objects should only be imported from one XDM version into an environment that runs the same or a newer XDM version.

Newer XDM versions may add fields or change internal structures.
These changes may not be compatible with older XDM versions.

If you downgrade XDM or mix incompatible versions, CasC imports may fail or produce inconsistent configuration.

Recommended Deployment Workflow

Two‑Environment Setup (DEV → PROD)

Use this only in simple scenarios or where a dedicated test environment is not available.

Key recommendations:

Keep changes per deployment small and focused.
Test thoroughly on DEV before exporting.
Review Git diffs carefully before committing to the PROD branch.
Monitor the CasC job on XDM‑PROD closely and be ready to revert via Git if necessary.

Three‑Environment Setup (DEV → TEST → PROD)

This is the recommended approach for most installations.

Summary:

Develop and test on XDM‑DEV.
Export a coherent set of objects.
Commit to branch xdm-test.
Let XDM‑TEST import and validate the configuration.
Fix problems on DEV, re‑export and re‑deploy to TEST as needed.
Once stable, merge xdm-test into xdm-prod.
Let XDM‑PROD import from xdm-prod.

This workflow mirrors typical software development lifecycles and makes configuration changes auditable and reproducible.

Troubleshooting CasC

When issues occur with Configuration as Code (CasC), you typically need to analyze the CasC job log, identify the root cause, fix the configuration, and then restart the job.

Diagnosing CasC Import Problems

If errors occur during CasC import:

The CasC job stops and will not continue until it is manually restarted.
Open System Settings → System Configuration → Internal scheduled jobs.
Locate the Configuration as Code Job.
Open the log of the last run to see:

which objects were imported, which objects failed, error messages for missing references, permission issues or incompatible formats. Typical problems include:

Missing referenced objects (for example connections, credentials). Environment‑specific differences not handled by .casc-ignore. Objects exported by a newer XDM version that are imported into an older XDM instance. Permission issues when reading from or writing to the Git repository. After fixing the root cause (for example adding missing objects to Git, adjusting ignore rules, or aligning XDM versions), restart the CasC job from the same screen.

Common Pitfalls And How To Avoid Them

Forgotten dependent or referenced objects Always export all objects that belong together. Use Include dependent objects and usually also Include referenced objects (or export them separately if you deliberately exclude them).
Excessive Git diffs caused by lastChangedDate Perform focused exports and carefully review diffs in Git. Stage only the relevant changes and ignore pure timestamp or format updates that are unrelated to your change set.
Manual configuration changes on TEST or PROD Establish a process where configuration is changed only on DEV and then propagated to TEST and PROD via CasC and Git branches. Avoid editing configuration directly on TEST or PROD to prevent divergence.
Environment‑specific connections and credentials Use environment‑specific variants of the same logical object (same object name, different YAML files) and control which file is imported in which environment using .casc-ignore.
Scripts that must behave differently per environment Centralize behavior in a single script and switch based on an environment identifier (for example the environment name or xdm.core.environment-id). Avoid maintaining separate script copies per environment.

By following these guidelines, CasC becomes a stable and repeatable way to manage XDM configuration across multiple environments.