Element <include>

Purpose: Compose another descriptor or properties resource into the current setup scope.

Why: Use it to compose reusable descriptors or properties instead of copying configuration.

Example

<include uri="path/to/file.xml"/>

Decision guide

Business value: Keeps shared model fragments and environment-specific properties reusable without copying them.

• Use when

  • Several descriptors share a fragment or a properties file.
  • The included URI or properties are selected dynamically.

• Choose another approach when

  • The content is untrusted or used only once and is clearer inline.

• Prerequisites

  • Keep the include path inside the descriptor workspace and declare referenced properties first.

• Alternatives

  • Keep a small one-off flow directly in the owning setup. (See: <setup>)

Complete examples

Call one typed descriptor fragment with scoped parameters

Use a param contract and include-local properties when several business products share one model shape but require different bounded values.

<setup>
    <param name="entity_name" description="Product emitted by this fragment."/>
    <param name="scheme" type="enum" values="SEPA SWIFT"/>
    <param name="count" type="int" default="2"/>
    <generate name="{entity_name}" count="{count}" target="LogExporter">
        <id name="id" generator="IncrementGenerator"/>
        <key name="scheme" constant="{scheme}"/>
    </generate>
</setup>

<setup>
    <include uri="fragments/payment.xml">
        <property name="entity_name" constant="sepa_payments"/>
        <property name="scheme" constant="SEPA"/>
        <property name="count" constant="3"/>
    </include>
    <include uri="fragments/payment.xml">
        <property name="entity_name" constant="swift_payments"/>
        <property name="scheme" constant="SWIFT"/>
    </include>
</setup>

Rules and invalid combinations

I201 — Include File Not Found

Include file '{uri}' not found in task workspace

Why: The referenced configuration could not be found for the include configuration.

Resolution: Ensure the referenced file exists and the identifier/path is correct.

Full rule

I202 — Include Properties Parse Failed

Failed to parse include properties file '{uri}': {error}

Why: The system failed to parse include properties file '{uri}': {error}.

Resolution: Fix the input format and retry.

Full rule

I203 — Include Unsupported File Type

Unsupported include file type '{uri}'. Only .properties and .xml are supported

Why: The configuration uses an unsupported include file type '{uri}'. Only .properties and .xml are supported.

Resolution: Use a supported file or adjust the configuration.

Full rule

I204 — Include Unsupported File Type Generate

Unsupported include file type '{uri}' inside . Only .xml is supported

Why: The configuration uses an unsupported include file type '{uri}' inside . Only .xml is supported.

Resolution: Use a supported file or adjust the configuration.

Full rule

I205 — Include Condition Not Boolean

Condition '{condition}' for include '{uri}' evaluated to a non-boolean value (not a valid boolean value): {value}

Why: A condition evaluated to a non-boolean value in the include configuration.

Resolution: Ensure the expression evaluates to true or false.

Full rule

I206 — Include Condition Eval Failed

Failed to evaluate condition '{condition}' for include '{uri}': {error}

Why: The system failed to evaluate condition '{condition}' for include '{uri}': {error}.

Resolution: Fix the expression or script and retry.

Full rule

I207 — Include Path Outside Descriptor

Include path '{uri}' is outside descriptor directory '{descriptor_dir}' or violates relative-path policy: {reason}

Why: The include path is outside the descriptor directory or does not follow relative-path requirements.

Resolution: Use a relative include path under descriptor_dir.

Full rule

I208 — Include Dynamic Properties With Overlay

Include '{uri}' resolved to a .properties file, but children are only supported for XML descriptor includes

Why: The include resolved to a .properties file even though the descriptor configured XML-only property overlays.

Resolution: Remove the children or resolve the include to an XML descriptor.

Full rule

I616 — Parser Include Property Duplicate

Duplicate in is not allowed

Why: The include configuration defines the same scoped property name more than once.

Resolution: Remove or rename the duplicate entry.

Full rule

I617 — Parser Include Property On Properties

Element cannot define children for .properties includes

Why: Scoped include properties are only supported when the include target is an XML descriptor.

Resolution: Remove the children or change the include target to an XML descriptor.

Full rule

I618 — Parser Include Param Missing

Fragment contract violation for

{contract_table}

{missing_summary}

Why: The included fragment declares required params that were not supplied by the caller.

Resolution: Supply the missing values or define defaults on the fragment declarations.

Full rule

I619 — Parser Include Param Invalid Value

Invalid value for param '{param_name}' in . Expected {expected_detail}; provided '{provided_value}'

Why: The include caller supplied a literal value that does not satisfy the fragment param contract.

Resolution: Update the value to match the declared param type or enum values.

Full rule

Allowed parents / Allowed children

Allowed parents: else, else-if, generate, if, iterate, setup, while

Allowed children:

property

Related concepts and use cases

• Dynamic Includes and Fragment Parameters — Explains URI interpolation, scoped include properties, typed fragment params, runtime caller context, nesting, conditions, and cataloged failures for reusable XML composition.
• First DATAMIMIC Model — Builds the smallest model and then composes preparation and generation stages.

Attributes

Show all 2 attributes

condition

Condition expression to evaluate whether to include this file.

optional; string; Default: null.

uri

URI of the file to include.

required; string.