Skip to content

Scripted Source Templates

Use sourceScripted="true" when a versioned project file is a data template whose values must be evaluated in the current record context. Keep it disabled for ordinary source data: enabling it turns file values into executable expressions.

Two replacement forms have different contracts:

  • A complete value such as {40 + 2} is evaluated as an expression and retains its result type. The example therefore produces the integer 42, not the string "42".
  • A placeholder inside text, such as customer-__row_number__, performs string substitution. variablePrefix and variableSuffix can replace the default __ delimiters.
data/people.ent.csv
1
2
3
4
name|age|label
Ada|{40 + 2}|customer-__row_number__
Grace|{30 + 7}|customer-__row_number__
Linus|{20 + 9}|customer-__row_number__
scripted-source.xml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<setup defaultSeparator="|" numProcess="1">
    <generate name="scripted_people" count="3" target="LogExporter">
        <variable name="row_number" generator="IncrementGenerator"/>
        <variable name="person"
                  source="data/people.ent.csv"
                  sourceScripted="true"
                  distribution="ordered"/>
        <key name="name" script="person.name"/>
        <key name="age" script="person.age"/>
        <key name="label" script="person.label"/>
    </generate>
</setup>

The output ages are integers 42, 37, and 29; the labels are customer-1, customer-2, and customer-3.

Do not confuse the three mechanisms

  • sourceScripted evaluates values read from a supported project file.
  • script on a field computes that one field.
  • script as the execution basis of a nested generate owns the complete record or record-list value. A dictionary represents one record; a list of dictionaries represents several records.

Use the narrowest mechanism that expresses the requirement. A normal data file is easier to audit than an executable template, and a typed generator or field intent is easier for Authoring to validate than an arbitrary script.

Boundaries

  • Expressions run with the current DATAMIMIC evaluation namespace; they are not interpolated during descriptor parsing.
  • A brace expression must occupy the complete source value. Text around it prevents expression evaluation.
  • Embedded prefix/suffix replacement always produces text.
  • Source-column names and variables should not shadow one another; use distinct business names so the dependency is reviewable.
  • Keep the read bounded and select a distribution supported by the source family.

See sourceScripted, variablePrefix, and variableSuffix for the generated attribute contract and expression lifetime for descriptor expressions.