Configuration Files - Data Mapping

A data mapping definition defines rules how to map the data extracted from the ENOVIA/3DEXPERIENCE system. This is useful in cases where you transfer data from the ENOVIA/3DEXPERIENCE platform into another system, which uses slightly different names for certain values.

The data mapping is a separate configuration of type datamapping. The configuration itself is an XML file describing the rules, and this configuration file is stored inside a directory called "datamapping" below the "cfg" directory.

E.g.: ${TIF_ROOT_DIR}/modules/enovia/cfg/datamapping

Using a Data Mapping

The data mapping is used in the Payload configuration, within the <TableContent> element.

A data mapping operates upon "table data", e.g. a table where the rows are mapped to either of / or both a relationship and a business object and the cells are mapped to attributes or other types of selected fields.

<Payload>
	<TableContent outerElement="bill-of-materials">
		<DataSet ref="SingleLevelEBOM.xml" />
		<Table ref="PartBasic.xml" />
        <DataMapping ref="PartMapping.xml" /> (1)
    </TableContent>
</Payload>

1	Data mapping referenced

Format

The format of the configuration file is straight forward. The example below is used as a base for explaining the format.

<DataMapping>
    <Include name="BaseMapper.xml"/> (1)
    <Include name="tvc:datamapping/AnotherMapper.xml"/> (2)

    <Rules> (3)
        <When column-is="Name" use="name-mapper"/>
        <When column-is="Type" use="type-mapper" />

        <When attribute-is="attribute_UnitofMeasure" use="UoM"/>
        <When expression-is="current" use="Status" />
        <When expression-is="locked" use="Yes/No" />

        <When setting-is="Foo" use="FooMapper" />
    </Rules>

    <ValueMappings> (4)

        <ValueMapping name="name-mapper">
            <If matches="[ABCDE][WVXYZ]-(.*)" then="$1" mode="replace"/>
            <Fallback to="default"/>
        </ValueMapping>

        <ValueMapping name="Yes/No">
            <If eq="True" case-sensitive="false" then="Yes" />
            <Fallback value="No" />
        </ValueMapping>

        <ValueMapping name="Status">
            <If starts-with="Create" case-sensitive="true" then="New" />
            <If eq="peer review" case-sensitive="false" then="PR" />
        </ValueMapping>

        <ValueMapping name="UoM">
            <If eq="kg" then="KILOGRAMS"/>
            <If eq="g" then="GRAMS" />
            <If eq="mg" then="MILLIGRAMS" />
        </ValueMapping>

        <TypeMapping name="type-mapper">
            <If type-of="Hardware Part" then="HW_Item" />
            <If type-of="Software Part" then="SW_Item" />
            <If type-of="Part" then="Item" />
            <If type-of="DOCUMENTS" then="Documentation" />
            <Fallback to="null" />
        </TypeMapping>

    </ValueMappings>
</DataMapping>

1	Include another data mapping, using the simple naming reference
2	Include another data mapping using the longer naming reference, which is required when you use subdomains.
3	Here we declare when a rule is being used. See later for how the rules can be matched
4	This section contains all the value mappings made. See later for all details.

Rule Mappings

The different alternatives how to select a specific value mapping for a cell in the table are:

Match on the name of the column: Use the attribute column-is to specify the name of the column
Match on a specific attribute used in the column: Use the attribute attribute-is to specify the real name or the symbolic name of the attribute.
Match on the column expression: Use the attribute expression-is to declare the expression
Match on the presence of a column setting: Use the attribute setting-is and declare the name of the setting that should be present
Match on a column setting having a specific value: Use both the attributes setting-is and setting-value-is where the latter specifies what value to be matched with.

The first rule being matched defines what value-mapping to be used via the use attribute. If the use attribute points to a non-existing ValueMapping, then no mapping will be done rather than an exception being thrown.

The value mapping names are case-insensitive.

Value Mappings

The <ValueMapping> element is used in most cases to replace a value. This element uses nested <If> elements to declare the various conditions.

If the current value does not match any of the specified conditions, a fallback value can be configured to be returned using the <Fallback> element.

The fallback value is configured to be either null, the empty string, the input value, or a fallback string.

<ValueMapping name="the-name-of-the-mapping">
    <!-- Declare all IF conditions -->
    <If eq="..." then=",,,"/>
    <If eq=",,," then="..."/>

    <!-- Use ONE of the below -->
    <Fallback to="null" />
    <Fallback to="default" />
    <Fallback to="blank" />
    <Fallback value="Fixed value to be used" />
</ValueMapping>

An <If> element supports a couple of attributes described below.

Only the first condition being matched will be used.

The operator

Standard value mappings are used to test the value using the following operators:

Attribute Name Description Example

Attribute Name	Description	Example
eq	Equals	`<If eq="Test" />`
neq	Not equals	`<If neq="Test" />`
is	Same as equals	`<If is="Test" />`
is-not	Same as not equals (neq)	`<If is-not="Test" />`
starts-with	Start with	`<If starts-with="Test" />`
not-starts-with	Not starting with	`<If not-starts-with="Test" />`
ends-with	Ends with	`<If ends-with="ABC" />`
not-ends-with	Not ends with	`<If not-ends-with="ABC" />`
contains	Contains	`<If contains="string" />`
not-contains	Not contains	`<If not-contains="string" />`
matches	Regular expression matching	`<If matches="[ABC][DEF].*" >`
not-matches	Regular expression negative matching	`<If not-matches="[A].*" />`
null	Test if value is null	`<If null="true" />`
not-null	Test if value is not null	`<If not-null="true" />`
blank	Test if value is blank	`<If blank="true" />`
not-blank	Test if value not blank	`<If not-blank="true" />`

Equals

<If eq="Test" />

neq

Not equals

<If neq="Test" />

Same as equals

<If is="Test" />

is-not

Same as not equals (neq)

<If is-not="Test" />

starts-with

Start with

<If starts-with="Test" />

not-starts-with

Not starting with

<If not-starts-with="Test" />

ends-with

Ends with

<If ends-with="ABC" />

not-ends-with

Not ends with

<If not-ends-with="ABC" />

contains

Contains

<If contains="string" />

not-contains

Not contains

<If not-contains="string" />

matches

Regular expression matching

<If matches="[ABC][DEF].*" >

not-matches

Regular expression negative matching

<If not-matches="[A].*" />

null

Test if value is null

<If null="true" />

not-null

Test if value is not null

<If not-null="true" />

blank

Test if value is blank

<If blank="true" />

not-blank

Test if value not blank

<If not-blank="true" />

Case insensitive

To define if the matching should be done case sensitive (default) or case insensitive, use the attribute case-sensitive="true | false".

The replacement value

The attribute then is used to declare the value to be substituted with.

Example:

<If eq="KG" case-sensitive="false" then="kilogram" />

Mode

Per default, the value matched will be substituted with the value defined in the then attribute. However, you can also configure to either append or prepend the value to the original value.

This is done via the attribute mode. The default value is substitute, but alternative values are:

substitute
- Means substitute the matched value with the then value
replace
- Means replace the value with the then value. This is only useful when using ends-with or starts-with and case-sensitive is TRUE
- Note that this mode has a special meaning in case reg-exp matching is used.
prepend
- Prepends the then value with the original value
append
- Appends the then value with the original value

Resolve Macros

The replacement value may contain a macro, which value is resolved against values from the current job etc.

In such case, you must configure that the resolving should take place via the resolve-macros attribute. See example below:

<If eq="TestValue" then="${job.param.ABC}" mode="prepend" resolve-macros="true"/>

Regular Expressions

A special feature with regular expressions is to instead of substituting the value with something else, instead allow replacing the input string.

Example:

<ValueMapping name="name-mapper">
    <If matches="[ABCDE][XYZ]-(.*)" then="$1" mode="replace"/>
    <Fallback to="default"/>
</ValueMapping>

This name mapper would match on for example values starting with AX-00001 and since the mode attribute is set to replace we are allowed to use back-references in the then value.

Here we are back-referencing to the first group, hence in the example above where the input value was AX-00001 the final mapped value would become 00001.

Since the fallback value is declared as default, for any other non-matching conditions the default value is used.

Type Mapping

The type mapping can be used to match on a specific type including testing derivativity.

See example below:

    <TypeMapping name="type-mapper">
        <If type-of="Hardware Part" then="HW" />
        <If type-of="Software Part" then="SW" />
        <If type-of="Part" then="Item" />
        <Fallback to="null" />
    </TypeMapping>