Field Mapping

Map source fields to target entity fields, transform values, and publish versioned stream mappings.

Field mapping defines how source fields are written to the target entity in Emporix. From the stream actions, select Edit mapping to open the dedicated Field Mapping view.

Field Mapping with target schema version, source and target fields, transforms, origin, and publishing actions

1

Open Edit mapping

On the stream row, choose Edit mapping. You start with a blank mapping until you fetch a sample and map fields.

2

Review the target schema and source sample

Choose the Target schema version against which the mappings are checked. This schema version is recorded when you save.

Field Mapping pins the schema version you last saved. After you change a mixin schema in Management Dashboard, the mapping still opens on that pinned version, not the latest one. Switch Target schema to the new version, review any breaking changes the Import Tool shows, then test and Publish before real runs use it. A new schema version can break the import if you adopt it without checking the mappings.

Choose Fetch sample to retrieve source data and preview mappings. If the connection uses None — each stream samples its own endpoint, the sample comes from the stream HTTP endpoint.

To map into an existing custom entity, create that type and its mixin attributes first. Map from source can match only keys that already exist on the selected Target schema.

3

Map from source

Choose Map from source. When a source field name matches a target attribute Key on the selected mixin schema, the Import Tool adds that mapping automatically.

Map from source only matches keys. If the source field name and the mixin Key differ, choose + Add row and select Source Field and Target Field yourself. Primary-key style fields such as uuid or id often need a manual row even when other fields map automatically.

For custom entities, Target Field lists mixin schema attributes. It does not include the instance Name on the General tab. The Custom Instances list Id and Name come from the stream key.

Review each mapping's Source Field, Target Field, Target Type, Transform, and Origin. Use + Add row for another field or Map array for array fields.

• Auto-mapped rows reuse an existing mixin Key. They do not create new attributes.

• If you leave generated target names unchanged, the import can create new attributes on the entity as a new mixin schema. For example, a stream called Shirts can add a Shirts tab with the imported attributes, even if the entity already has another mixin.

• If you set each mapping target to existing entity or mixin fields, the import maps into those fields and does not create new ones.

• Creating new mixin attributes from generated targets is also valid when you want to preserve the imported structure.

Set the mapping target fields to the schemas you intend to use: existing schemas you want to reuse or generated targets that you accept as new.

4

Adjust values with Transform

Use Transform to shape values before target type conversion. Leave the transform blank for a direct passthrough.

Supported transforms include:

Transform	Description
trim	Removes leading and trailing whitespace
upper	Converts the value to upper case
lower	Converts the value to lower case
dateIso	Best-effort ISO date passthrough; DATE or DATE_TIME target types handle parsing
constant:<value>	Emits a fixed literal; the source field can be blank
default:<value>	Uses <value> when the source is null or blank
prefix:<text>	Prepends <text>
suffix:<text>	Appends <text>
substring:<start>[:<end>]	Extracts a substring by 0-based character index; <end> is exclusive and optional
replace:<search>:<replacement>	Literal replace-all; <search> cannot contain :
regexReplace:<pattern>:<replacement>	Regex replace-all using Java regex; <pattern> cannot contain :
padStart:<length>:<char>	Left-pads to <length> using <char>
split:<delimiter>	Splits into an array of trimmed, non-empty tokens
reference:<TYPE>	Builds a single reference to an imported instance of <TYPE>
references:<TYPE>	Splits comma- or semicolon-separated IDs into an array of references to <TYPE>
resourceId	Extracts the last path segment from a URL or file path

5

Preview mappings

After you choose Fetch sample, use Preview with to select a sample record, then use the record navigation to move through the sample set. Choose Preview to see how the current mappings and transforms apply to that record before you save. Review the sample values and transformed output for each row. Choose Clear preview to remove preview results from the grid without changing your mappings.

Mapping preview showing sample record selection and transformed values before save

6

Save and publish the mapping

Choose Save to store the mapping with the selected target schema version. Saving keeps a draft. Real runs and schedules use the last published version only.

When the mapping is ready for real imports, choose Publish. Publish again after every mapping change you want real runs to use.

Publish Mappings dialog that makes the draft live for real runs

Until you publish, the mapping stays a draft. Real runs use the last published version. If Field Mapping shows Never published, that stream is not imported on a real run. You can still preview the draft with Dry run and Draft selected. See Running and Monitoring Imports.

7

Review mapping versions

Use Version history to list published versions, newest first, and see where the current draft stands relative to them.

To roll back, open Version history, choose Restore on an earlier published version to load it into the draft, review the mapping, then choose Publish again. Restoring alone does not change what real runs use until you publish.

On the import details view, use Dry run with Draft or Published to confirm the mapping you intend before a real run. See Running and Monitoring Imports.

After you publish the mapping, continue with Running and Monitoring Imports.