> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/import-tool/import-setup-and-jobs/imports/field-mapping.md).

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

<figure><img src="https://2637457592-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9VS91qn3Ylwd58YivX1A%2Fuploads%2Fgit-blob-ee6c2a425fe0309725d175d70164d1babbfeff4b%2Fit_stream_field_mapping.png?alt=media" alt="Field Mapping view with target schema, sample, mapping rows, and publishing actions"><figcaption><p>Field Mapping with target schema version, source and target fields, transforms, origin, and publishing actions</p></figcaption></figure>

{% stepper %}
{% step %}

#### Open Edit mapping

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

{% step %}

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

{% hint style="warning" %}
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.
{% endhint %}

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

{% hint style="info" %}
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**.
{% endhint %}
{% endstep %}

{% step %}

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

{% hint style="info" %}
**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.
{% endhint %}

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.
{% endstep %}

{% step %}

#### 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                              |
| {% endstep %}                          |                                                                                     |

{% step %}

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

<figure><img src="https://2637457592-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9VS91qn3Ylwd58YivX1A%2Fuploads%2Fgit-blob-91b3b494d6a25f22ceacdfe2d329926103b08315%2Fit_mapping_preview.png?alt=media" alt="Field Mapping preview with Preview with, record navigation, and mapped field output"><figcaption><p>Mapping preview showing sample record selection and transformed values before save</p></figcaption></figure>
{% endstep %}

{% step %}

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

<figure><img src="https://2637457592-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9VS91qn3Ylwd58YivX1A%2Fuploads%2Fgit-blob-de72404989421be12015d8763e1b4a79703f9741%2Fit_lp_publishing.png?alt=media" alt="Publish Mappings dialog"><figcaption><p>Publish Mappings dialog that makes the draft live for real runs</p></figcaption></figure>

{% hint style="warning" %}
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](/import-tool/import-setup-and-jobs/imports/running-imports.md).
{% endhint %}
{% endstep %}

{% step %}

#### 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](/import-tool/import-setup-and-jobs/imports/running-imports.md).
{% endstep %}
{% endstepper %}

{% hint style="success" %}
After you publish the mapping, continue with [Running and Monitoring Imports](/import-tool/import-setup-and-jobs/imports/running-imports.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.emporix.io/import-tool/import-setup-and-jobs/imports/field-mapping.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.