---
name: dataminer-automation-xml
description: 'Authoring the DMSScript XML definition of a DataMiner Automation script: root/metadata, script parameters, memory files, dummies (Protocols), options, interactivity, and the Script/Exe blocks. Load for any change to the <Name>.xml script definition.'
argument-hint: 'Describe the XML change: e.g. "add a string script parameter", "declare a dummy element", "set the script type to interactive", "reference the compiled project in the Exe block"'
license: LicenseRef-Skyline-Agent-Marketplace
metadata:
  updated: 2026-10-28
  version: 1.5
---

## Changelog

| Version | Date | Changes |
|---------|------|---------|
| 1.5 | 2026-10-28 | Added the provisional scaffold `<Exe id="1">` collision rule, `max + 1` `<Exe id>` allocation after parameter/dummy/memory IDs, and the bundled `scripts/validate-dmsscript-xml.ps1` validation check. |
| 1.4 | 2026-09-27 | Aligned packaged resource references and execution contracts. |
| 1.3 | 2026-09-14 | Clarified exact SDK linkage for greenfield work and the selected inline source/mirror contract for explicitly maintained legacy Cube-inline scripts. |
| 1.2 | 2026-09-14 | Replaced the partial guidance with the closed-world DMSScript 1.1.10 contract, document-wide ID allocation, exact SDK project linkage, and bidirectional numeric parameter parity. |
| 1.1 | 2026-09-15 | Added guidance to distinguish normal DMSScript XML from GQI library and other specialized contract project shapes, and made Interactivity target-gated and UX-based, with modern `Never` and legacy element-omission guidance. |
| 1.0 | 2026-06-27 | Initial release. Automation-script counterpart of `dataminer-xml-authoring` (DMSScript instead of protocol.xml). |

You are guided here for the **XML half** of a DataMiner Automation script: the `DMSScript` definition file (`<Name>.xml`). Load `dataminer-automation-core` first. The C# half is owned by `dataminer-automation-scripting`; its intended source is the linked SDK project in SDK mode or the selected C# `Exe` `<Value>` during explicitly targeted maintenance of an existing legacy Cube-inline artifact.

> **Single contract owner:** this skill owns DMSScript structure for the Automation ecosystem. `references/dmsscript-reference.md` is its complete closed-world grammar. Author, reviewer, investigator, scaffolder, and orchestrator guidance must refer here instead of reproducing or extending the XSD from memory. Use `dataminer-automation-core/references/version-compatibility.md` for target-version behavior and `dataminer-automation-core/references/invocation-and-entry-points.md` for runtime inputs/outputs; do not put runtime API assumptions into the XML grammar.

Before editing XML, classify the project. A normal `DMSScript` linked to a `Run(IEngine)` executable is not the
same contract as a GQI compiled ad hoc data-source library, an SRM role, a User-Defined API, or a Node Recovery
callback. Route those projects to their feature skill and use the XML/project shape generated by the selected
official template. Do not add normal script parameters, dummies, `Interactivity`, or exit assumptions to a
specialized project unless its template explicitly contains them.

For GQI, verify the generated project/library XML and class identity against the current Core GQI template; the
first implementation targets `Skyline.DataMiner.Core.GQI.Extensions`, not the legacy `SLAnalyticsTypes` track. For
SRM and Node Recovery, public documentation may not expose complete XML or callback details, so the version-matched
template/package/configuration is authoritative. For User-Defined APIs, keep route/definition/token provisioning
outside source-controlled XML unless a documented manifest requires it.

## Pinned schema authority

| Item | Pinned value |
|---|---|
| Package | `Skyline.DataMiner.XmlSchemas.Automation` 1.1.10 |
| Package SHA-256 | `c164064bdfe6a99c8f13fd9563106d30715c6496da9b137ac0176aeef387826f` |
| XSD path in package | `content/Skyline/XSD/automation.xsd` |
| Vendored XSD | `references/automation-1.1.10.xsd` (relative to this skill) |
| XSD SHA-256 | `b7c17c970dd5847ed9f4bd33e08c0e7c8acf546094a38a14a35fabaea2d461ea` |
| Source commit | `d7b5c9ac6865f3e56804bf95e536d460b5e50e36` |
| Contract reviewed | 2026-09-14 |

The vendored XSD is normative for structural validity. It requires the exact document namespace `http://www.skyline.be/automation` and declares `elementFormDefault="qualified"`, so every DMSScript element is namespace-qualified. Attributes remain unqualified. Do not add elements, attributes, or enum values outside the closed-world reference.

Use the bundled [Automation XSD](references/automation-1.1.10.xsd) and [DMSScript XML validator script](./scripts/validate-dmsscript-xml.ps1) for offline validation.
Its bytes and SHA-256 are unchanged in published packages. Repository eval tooling retains
a hash-verified compatibility copy; it is not a separately maintained schema authority.

## Root contract

`DMSScript` uses `xs:all`. **Top-level child order is unconstrained**; the order shown by a template or example is conventional only and must never be enforced or described as required.

Exactly one of each of these top-level children is required: `Name`, `Description`, `Type` (fixed to `Automation`), `Author`, `CheckSets` (`TRUE` or `FALSE`), `Folder`, `Protocols`, `Memory`, `Parameters`, and `Script`. `Interactivity` is optional with a maximum of one and permits only `Auto`, `Never`, `Optional`, or `Always`.

The root `options` attribute is required and has type `xs:positiveInteger`. The XSD documentation names flag values, but the XSD does not constrain flag combinations. Preserve the value generated by the selected official template/tool unless a behavior or target configuration requires a reviewed exact value. There is no universal `options` number.

## Schema-valid modern SDK skeleton

This example targets DataMiner 10.5.9/10.6.0 or later and a script that never presents UI. Its top-level order is illustrative, not a schema rule. The positive `options` value is an example generated value, not a prescribed default.

```xml
<?xml version="1.0" encoding="utf-8"?>
<DMSScript options="272" xmlns="http://www.skyline.be/automation">
  <Name>My-Script</Name>
  <Description></Description>
  <Type>Automation</Type>
  <Author></Author>
  <CheckSets>FALSE</CheckSets>
  <Folder></Folder>
  <Interactivity>Never</Interactivity>
  <Protocols></Protocols>
  <Memory></Memory>
  <Parameters></Parameters>
  <Script>
    <Exe id="1" type="csharp">
      <Value><![CDATA[[Project:My-Script]]]></Value>
      <Message></Message>
    </Exe>
  </Script>
</DMSScript>
```

> **Provisional `<Exe id="1">` warning:** `<Exe id="1">` in a freshly scaffolded template is only valid while no `<Protocol>`, `<File>`, or `<ScriptParameter>` uses `id="1"`. Because every descendant `@id` across the entire DMSScript document shares one document-wide namespace, if you add 1-based `<ScriptParameter>`, `<Protocol>` (dummy), or `<File>` (memory) entries (`id="1"`, `id="2"`, …), you **must** renumber `<Exe id>` to the next free document-wide ID after the highest used ID (`max + 1`, for example `<Exe id="3" type="csharp">`). Leaving `<Exe id="1">` when `id="1"` is used elsewhere causes the script to fail immediately in DataMiner.

For every greenfield/new Automation script, `<Value>` must contain the exact link `[Project:<intended-project-name>]`. Verify the spelling and case against the project that must compile into that action; do not silently normalize it or paste inline C#. In the standard one-project template, the script, file, project, and link normally share the same name. Never create a new inline script.

Inline C# remains a schema-valid legacy representation. Existing Cube-inline artifacts are supported for review and read-only investigation. Only when the user explicitly targets maintenance, a bugfix, or a feature on that existing artifact may authoring preserve and edit the selected C# `Exe` `<Value>`. Do not silently migrate it or introduce `[Project:<name>]` unless migration is approved; this exception is not permission for generic greenfield inline authoring. The selected `<Value>` is the intended C# source, and any existing build mirror must match it exactly. Document-wide descendant IDs, XML/C# parity, pinned-XSD validation, lifecycle/interactivity decisions, and runtime rules apply unchanged. Non-`csharp` `Exe` actions remain schema-valid legacy capabilities governed by the approved task; they are not an alternative C# source.

## Required containers

- `Protocols` contains zero or more `Protocol` children. Each has a required positive `id` and the exact child sequence `Description`, `Name`, `Version`, `DefaultElement`. The first three are nonempty strings. `DefaultElement` is either empty or ASCII digits, `/`, ASCII digits (for example `200/160`).
- `Memory` contains zero or more `File` children. Each contains exactly one nonempty `Description`; required `id` is positive, and required `volatile` is exactly lowercase `true` or `false`.
- `Parameters` contains zero or more `ScriptParameter` children. Each contains exactly one nonempty `Description`; required `id` is `xs:unsignedInt`; required `type` has the sole value `string`; required `values` is `xs:string`, so `values=""` is valid. No other script-parameter type exists in this XSD, and `values` is not optional.
- `Script` contains zero or more `Exe` children. Each `Exe` requires a positive `id` and one of the XSD's action-type enum values; `destvar` is optional. The complete repeating child-choice grammar, all child attributes, and every enum are in `references/dmsscript-reference.md`.

## One document-wide ID namespace

The root identity constraint `idUniqueInScript` uses selector `.//*` and field `@id`. Therefore **every descendant `@id` value shares one document-wide namespace**. In schema 1.1.10, the declared ID-bearing descendants are `Protocol`, `File`, `ScriptParameter`, and `Exe`; any other descendant carrying `@id` is governed by the same root selector.

Before adding or changing an ID:

1. Inventory every descendant `@id`, not only script parameters and executable blocks, and re-inventory after any edit.
2. Reject duplicates across all element kinds (`Protocol`, `File`, `ScriptParameter`, `Exe`, and any other descendant carrying `@id`).
3. Record the next available **document-wide ID** in the Script Map.
4. **Allocate `<Exe id>` after all parameter, dummy, and memory IDs (`max + 1`):** Unlike `ScriptParameter@id` (`engine.GetScriptParam(id)`), `Protocol@id` (`engine.GetDummy(id)`), and `File@id` (`engine.GetMemory(id)`), a C# `<Exe id>` is not referenced by C# code. Unless the caller explicitly specifies non-colliding IDs (for example parameters `10, 11` with `Exe id="1"`), assign `<Exe id>` values starting at `max(all Protocol, File, ScriptParameter, and other descendant @id values) + 1` (and consecutively `max + 1`, `max + 2`, … when multiple `<Exe>` blocks exist, such as `if`/`else`/`endif` actions).
5. **Always update the scaffold's provisional `<Exe id="1">` on collision:** `dotnet new dataminer-automation-project` emits `<Exe id="1">` while `<Protocols>`, `<Memory>`, and `<Parameters>` are empty. Because every descendant `@id` across the entire DMSScript document shares one document-wide namespace, if you add `<ScriptParameter id="1">`, `<Protocol id="1">`, or `<File id="1">`, you **must** move `<Exe id="1">` to the next free document-wide ID (`max + 1`). Keep existing non-colliding parameter, dummy, and memory IDs stable unless the approved change explicitly migrates every C# reference.

`Protocol`, `File`, and `Exe` require `xs:positiveInteger`; `ScriptParameter` permits the full `xs:unsignedInt` range, including zero. A positive allocation is preferred for a shared new-ID pool, but do not falsely report an existing script-parameter ID of zero as schema-invalid.

## XML/C# numeric parameter parity

For intended numeric parameter binding, compare exact sets in both directions:

- every XML `<ScriptParameter id="N">` has a numeric `engine.GetScriptParam(N)` use in the intended C#; and
- every numeric `engine.GetScriptParam(N)` use has an XML declaration with ID `N`.

A name-based `engine.GetScriptParam("name")` call does **not** establish numeric ID parity. Track such calls separately; do not count them as satisfying an XML numeric declaration. Preserve the XML's sole schema type (`string`) and required `values` attribute while checking runtime input handling in the scripting skill. Evaluate parity against the intended C# source: the linked SDK source or, for explicitly maintained legacy inline mode, the selected C# `Exe` `<Value>`. If an inline build mirror exists, verify exact source equality before using it for analysis or build validation.

## Interactivity decision matrix

Explicit interactivity is available from DataMiner feature release 10.5.9 and main release 10.6.0. Select it from actual UX behavior, not from a copied template value.

| Value | Author when |
|---|---|
| `Never` | The script presents no UI. Use this for current noninteractive scripts. |
| `Optional` | The workflow presents UI only when needed. |
| `Always` | The workflow always presents UI. Prefer it for operator-facing low-code IAS. |
| `Auto` | Compatibility with legacy string-based detection is specifically required. It is not a universal default. |

For earlier targets, omit `Interactivity` entirely and use legacy automatic detection. Do not add generic `NoKeyCaching` or timeout settings as a consequence of an interactivity choice; those remain evidence-based runtime decisions in the core/IAS guidance.

## Library and legacy action guidance

The XSD permits `Param` types including `preCompile`, `libraryName`, and `scriptRef`; their content is still only `xs:string`, so the XSD does not enforce boolean values, dots-free names, reference formats, action/child combinations, or library behavior. For a manually configured shared library, runtime/tooling guidance still requires `preCompile` set to `true` and a dots-free `libraryName`; a manual consumer uses `scriptRef` in `LibraryScriptName:LibraryName` form. Treat these as operational requirements, not additional schema facets. Prefer SDK project/library templates and generated project references for new work.

## Workflow

1. Record the project mode, target DataMiner version, and intended UX; apply the target-gated `Interactivity` rule. Greenfield/new mode is always SDK; legacy inline maintenance requires an explicit user target.
2. Read the whole XML and build the complete descendant-ID inventory before allocating anything.
3. Author only structures and values admitted by the pinned closed-world reference. Do not infer root ordering or action-specific constraints that the XSD does not express.
4. For SDK scripts, verify the exact `[Project:<intended-project-name>]` link. Never create inline C#. For explicitly maintained legacy inline mode, preserve and edit the selected C# `Exe` `<Value>` without adding a project marker or migrating unless approved.
5. Compare XML script-parameter IDs and numeric `engine.GetScriptParam(int)` calls in the intended C# source as exact sets in both directions; list name-based calls separately. If an inline build mirror exists, verify that it matches the selected `<Value>` exactly.
6. Validate the final XML against the pinned XSD and verify document-wide `@id` uniqueness before concluding. `dotnet build` compiles C# and runs Roslyn analyzers, but it **never** validates DMSScript XML or detects `@id` overlaps. While there is no standalone vendor DIS/CICD CLI for Automation scripts, you **must** run the bundled [`scripts/validate-dmsscript-xml.ps1`](./scripts/validate-dmsscript-xml.ps1) script (resolve its path relative to this loaded `dataminer-automation-xml` skill directory; use `pwsh`, or `powershell` on Windows PowerShell 5.1) against the target XML file or workspace:
   ```powershell
   pwsh -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "<path-to-dataminer-automation-xml-skill>/scripts/validate-dmsscript-xml.ps1" -Path "<Name>/<Name>.xml"
   ```
   Then build the SDK solution, or an existing matching inline build mirror, with `dotnet build` and its Skyline analyzers. Do not create a marker or mirror solely for validation; report when maintained inline code has no supported local compilation path.

## Reference Files

| File | Contents | Load When |
|---|---|---|
| `references/dmsscript-reference.md` | Authoritative closed-world DMSScript 1.1.10 grammar, enums, examples, identity constraint, and schema-versus-operational distinctions | Authoring, reviewing, investigating, scaffolding, or planning script XML |
| `scripts/validate-dmsscript-xml.ps1` | Bundled PowerShell validator for pinned-XSD compliance, document-wide normalized numeric `@id` uniqueness, and next-free `<Exe id>` calculation | Validating any authored, scaffolded, or reviewed DMSScript XML file |