Dynamic Includes and Fragment Parameters

Warning

The current page still doesn't have a translation for this language.

But you can help translating it: Contributing.

Use dynamic includes when one descriptor should compose different XML fragments or reuse the same fragment with different inputs. DATAMIMIC supports two separate mechanisms:

1. {expression} in include uri selects the file at setup time.
2. Child <property> elements pass scoped values into an XML fragment. The fragment may declare its expected inputs with <param>.

Both mechanisms are part of the Core DSL. Platform-specific per-run file injection is described separately in Inject runtime properties through the Platform API.

Select an included file through properties

Properties are loaded in document order. A placeholder must therefore be defined before the <include> that uses it. Later property files replace earlier values with the same name.

count=2
dynamic_model_path=models/load_performance.xml

<setup>
    <generate name="load_records" count="{count}" target="LogExporter">
        <key name="id" generator="IncrementGenerator"/>
    </generate>
</setup>

<setup>
    <include uri="conf/runtime.properties"/>
    <include uri="{dynamic_model_path}"/>
</setup>

This pattern is useful for CI variants, load-test volumes and feature-specific model fragments. Every resolved path must stay inside the descriptor workspace.

Declare a reusable fragment contract

An XML fragment uses <param> to state which values callers may supply. A parameter can be a string, int, enum or safe relative path; default makes it optional. Enum values are whitespace-separated.

<setup>
    <param name="entity_name" description="Result entity produced 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">
        <key name="scheme" script="scheme"/>
    </generate>
</setup>

The caller supplies values with child <property> elements. constant is a literal call-site value; exactly one of constant and script is allowed.

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

The first call produces three SEPA records. The second uses the declared default and produces two SWIFT records. Missing required parameters fail with I618; invalid types, enum values or unsafe paths fail with I619.

Compute fragment parameters per source row

script uses normal DATAMIMIC expression semantics without braces. Inside a <generate>, it is evaluated for every caller row and can read that row's fields and variables.

<setup>
    <param name="result_name"/>
    <param name="scheme"/>

    <generate name="{result_name}" count="1" target="LogExporter">
        <key name="scheme" script="scheme"/>
    </generate>
</setup>

<setup>
    <generate name="payments" count="3" target="LogExporter">
        <key name="idx" generator="IncrementGenerator"/>
        <include uri="fragments/payment.xml">
            <property name="result_name" script="idx"/>
            <property name="scheme" script="idx"/>
        </include>
    </generate>
</setup>

The fragment is executed three times with the direct caller's current idx. Writing script="{idx}" is invalid because braces belong to setup-attribute interpolation, not normal script= evaluation.

Scope and evaluation rules

• Include properties are visible while parsing and executing the included XML fragment.
• Nested includes inherit them.
• They never leak back into the parent descriptor.
• A literal .properties include cannot have child <property> elements.
• A dynamic URI that resolves to .properties rejects child properties at runtime with I208.
• A .properties include condition is decided at parse time from properties already loaded before it.
• An XML include condition is evaluated at runtime in the current execution context and must return a boolean.
• uri="{expression}" must resolve to a string and must remain inside the descriptor workspace.

Error handling

Code	Meaning
I201	Included file was not found.
I202	Included properties could not be parsed.
I203 / I204	File type is unsupported in setup/generate context.
I205	Include condition did not return a boolean.
I206	Include condition evaluation failed.
I207	Resolved path escapes the descriptor workspace.
I208	Child properties were combined with a properties-file include.
I618	A required fragment parameter is missing.
I619	A fragment parameter violates its declared contract.

Choosing the mechanism

• Use property files for run-wide configuration and dynamic fragment selection.
• Use <param> plus <include><property> for a reusable XML fragment with an explicit local interface.
• Use constant when the call site knows the value statically.
• Use script only when the value must come from the current runtime row or scope.

Related references: <include>, <property>, and <param>.