> ## Documentation Index
> Fetch the complete documentation index at: https://stedi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Mappings UI Builder
This functionality is available in a Stedi module. [Contact us](https://www.stedi.com/contact) for details.
[mappings-product]: https://stedi.com/app/mappings
[disconnect-a-guide]: #disconnect-a-guide
[pull-changes-from-a-guide]: #pull-changes-from-a-guide
You can create and edit mapping definitions with Stedi's visual mapping builder. Before you begin, we recommend reviewing the [Mapping Definitions Overview](/edi-platform/mappings/manage-mappings/mapping-definition).
## Create a mapping
Go to the [Mappings](https://portal.stedi.com/app/mappings) page in your Stedi account and click **Create mapping**. We recommend using the quickstart guide to create a mapping that matches your use case.
## Publish updates
You can edit a mapping at any time, unless it is [locked](#lock-a-mapping).
1. Go to the [Mappings](https://portal.stedi.com/app/mappings) page to review a list of existing mappings in your account. Stedi displays which mappings have unpublished changes.
2. Click a mapping's name to go to the Mappings builder and make updates. Stedi autosaves your changes as you work.
3. Click **Publish** to promote your changes to production.
It takes up to 15 seconds for Stedi to start applying changes you publish to your mappings.
## Lock a mapping
When you're finished editing, you can lock a mapping to prevent further updates. Locking helps prevent accidental changes or deletions to mappings in production.
Don't lock a mapping unless you're sure you don't need to make any additional
changes. Once you lock a mapping, only an account admin can unlock it.
To lock a mapping, open it, click the **...(elipses)** menu next to its name, and select **Lock settings**.
You can choose to lock the entire mapping, or just the mapping definition. When you lock the mapping definition only, you can still add or edit lookup tables, but you cannot edit the mapping source schema, target schema, or mapping expressions. This approach can be helpful when you expect to occasionally receive a new category of data for an existing field - for example, you need to update an existing lookup table with a new partner code or a new line of product SKUs.
No one can update or delete a locked mapping. However, you can duplicate locked mappings, if needed.
## Compare or roll back versions
You can compare the current version of a mapping with any previously published version to see what has changed. You can also roll back to a previous version of a mapping.
Open the **Actions** menu, and select **Version history** to review a list of every published version of the mapping. You can publish an older version or compare it with the current one. Comparing highlights every difference between the old version and the current version, similar to how GitHub displays changes on pull requests.
## Delete a mapping
Once you delete a mapping, you cannot recover its data.
To delete a mapping, click the ellipses (`...`) next to the mapping you want to delete, click **Delete**, and then confirm the deletion. The mapping is removed from your Stedi account.
## Define source and target JSON Schema
You must define a source and a target [JSON Schema](https://json-schema.org/). The source schema describes your incoming data. The target schema describes the shape of the Mappings API output.
For example, if you need to transform [Guide JSON](/edi-platform/operate/transform-json/guide-json) into a custom format for your internal systems, then the [Guide JSON](/edi-platform/operate/transform-json/guide-json) is the source, and the payload your software understands is the target.
You can define the source and target JSON Schemas by doing one of the following:
* [Connect a Stedi event](#connect-a-stedi-event) as the source schema. You must do this when creating a mapping to use with a destination webhook.
* [Connect a stedi guide](#connect-a-stedi-guide) to your mapping. We recommend this approach when you are using mappings with to read or write EDI data according to partner-specific requirements.
* Add a [JSON example file](#add-a-json-example-file).
* Provide a [JSON Schema](#provide-a-json-schema) adhering to [version 2020-12](https://json-schema.org/specification.html) that describes the shape of your data.
### Connect a Stedi event
Destinations are a legacy feature and have been superseded by
[Webhooks](/edi-platform/configure/webhooks/index). Please [contact
support](https://www.stedi.com/contact) with questions or for help migrating.
You can attach a mapping to a [destination webhook](/edi-platform/configure/destinations/configure-destinations#transform-data-with-mappings) event binding. Stedi uses the mapping to transform the JSON data payload into the required shape before sending it to the configured destination.
You must choose **Event** as the source type when creating a mapping to use with a destination webhook.
If you choose the `transaction.processed.v2` or `fragment.processed.v2` event types, you must also select a Stedi guide to connect to the mapping. Once you've connected your guide, mappings generates the source schema based on the event type you chose and the connected guide.
### Connect a Stedi guide
You can generate the **Source** or **Target** schema from a [Stedi guide](/edi-platform/guides/). After you connect a guide, the mappings UI autogenerates the schema and sample JSON document with fields from the guide.
#### Requirements
You must have at least one Stedi guide in your account. You can manually create a guide from PDF EDI specifications or import a pre-made guide from the [Stedi Network](https://www.stedi.com/edi/network).
#### Connect a guide to the mapping
You can connect a guide to both the mapping’s **Source** and **Target** schema. To connect a guide:
1. Navigate to your mapping and edit either the **Source** or the **Target** document.
2. Go to the **Guide** tab to view a list of guides in your Stedi account.
3. Click **Connect** next to the guide you want to use.
Once you've connected your guide, mappings generates the schema and example document based on the guide. The **Schema** and **Example** tabs will become read-only. Refer to [Pull changes from a guide][pull-changes-from-a-guide] on updating the document data based on a guide. To change the schema or example, you must first disconnect the guide – refer to [Disconnect a guide][disconnect-a-guide].
#### Use fragments
If the guide is set up to use [Fragments](/edi-platform/fragments/index), Stedi updates your options:
* **Inbound fragments:** You can choose whether to create a mapping for the `transaction.processed.v2` event type or the `fragment.processed.v2` event type. Visit [Inbound Fragments](/edi-platform/fragments/inbound-fragments) for details.
* **Outbound fragments:** You can choose whether to create a mapping for the full transaction (no fragments), the fragment wrapper, or the fragment shape. Typically for outbound fragments you need to create two mappings: one mapping for the fragment shape to use with the [Stage Fragment](/api-reference/edi-platform/core/post-fragments) endpoint and one mapping for the fragment wrapper to use with the [Create Outbound Transaction](/api-reference/edi-platform/post-transactions) endpoint. Visit [Outbound Fragments](/edi-platform/fragments/outbound-fragments) for details.
#### Pull changes from a guide
Pulling the changes from a guide allows you to update the schema with the latest published changes made to a guide.
To pull changes from a guide:
1. Navigate to your mapping and edit the **Source** or the **Target** document.
2. Go to the **Guide** tab to view the status of the connected guide.
3. Click **Edit** for a document that connects with a guide.
4. Click **Pull changes**. For **Target** schemas, the mappings UI alerts you when guide changes affect existing expressions in the mapping.
5. If there are breaking changes, review them and decide whether you want to continue with the update.
#### Disconnect a guide
Disconnecting a guide preserves the current **Source** and **Target** schemas. Still, you will no longer be able to automatically update them based on the published changes to a guide. You can re-connect a guide at any time if needed.
To disconnect a guide from a mapping document:
1. Edit the **Source** or **Target** and go to the **Guide** tab.
2. Click **Disconnect** and **Confirm**.
### Add a JSON example file
When you add a JSON example file, the Mappings builder autogenerates the JSON Schema based on the example structure.
If you edit the JSON example file, the Mappings builder validates the changes against the existing JSON Schema. If the JSON document does not conform to the JSON Schema, you can either regenerate JSON Schema or update it manually.
> JSON Schema regeneration might remove fields you defined in the JSON Schema
> and did not add to the example file.
### Provide a JSON Schema
When you add a JSON Schema, the Mappings builder autogenerates an example JSON file based on the schema.
Your JSON Schema must define a `default` property that contains an example of data that adheres to the schema. Refer to the JSON documentation for more about [the `default` keyword](https://json-schema.org/understanding-json-schema/reference/annotations).
When you upload a JSON Schema as either the source or target, Mappings builder uses the schema's `default` property to produce the mapping output. If the contents of the `default` property do not conform to the JSON Schema, you can manually amend the contents of the `default` property, amend the JSON Schema itself, or regenerate it automatically.
## Choose target keys
You can choose whether you want to include all or a subset of the incoming JSON fields in the output JSON file. By default, the Mappings builder uses all incoming target keys.
If you only need a subset of the fields that are in the sample select **Target keys**, to change which keys are included.
## Choose a mapping type
The mapping type specifies how the Mappings API generates the output field when the mapping expression doesn't produce a value.
You can select a mapping type from the dropdown menu in the **Output** section. You can choose between:
* Only mapped
* Merge with target
* Pass through
Refer to [Mapping Definition Overview](/edi-platform/mappings/manage-mappings/mapping-definition#mapping-types) for full details about each type and examples of how Mappings generates outputs based on your selection.
## Write mapping expressions
You must map each target key from the source JSON data to a property in the target JSON data. For example, you might map a `product ID` property from the source JSON to a `product number` property in the target JSON.
You do not need to do a one-to-one mapping of incoming properties to outgoing properties. You can create advanced expressions to map text properties to numbers, perform calculations, and more.
You can also use `omitField` to [exclude entire objects](/edi-platform/mappings/jsonata/common-mapping-expressions#conditionally-omitting-objects) or [exclude fields](/edi-platform/mappings/jsonata/common-mapping-expressions#omitting-output-fields) from the output based on a condition. For example, you might only want your output to include the input field `totalPrice` when the number of products is larger than 0.
Visit [Common Mapping Expressions](/edi-platform/mappings/jsonata) for details and examples for common mapping use cases.
### Handling floating-point arithmetic
It is not recommended to use JSONata for floating point arithmetic, such as
financial calculations. Floating-point arithmetic can introduce rounding
errors, which can accumulate and lead to incorrect results. Visit our [JSONata
Playground](https://stedi.link/UKXfsxe) for an example. We recommend
representing monetary values as integers (e.g. cents) and performing
calculations on those integers.
Instead of JSONata, we recommend representing monetary values as integers (e.g. cents) and performing calculations on those integers.
## Export and import mappings
You can export an existing mapping and import it into another Stedi account.
To export a mapping, navigate to the [Mappings dashboard][mappings-product], click the ellipses (`...`) for the Mapping you want to export, and click **Export**. A .zip archive of the mapping data is downloaded to your machine.
To import a mapping .zip archive into a Stedi account: 1. Sign into the account and go to [Mappings dashboard][mappings-product]. 1. Click **Import**. 1. Either click **Upload** to choose a .zip archive from your machine or drag and drop the .zip archive onto the page. 1. Choose a **Mapping name** and click **Proceed with import**. The new mapping is now available in the Stedi account.
## Duplicate and version mappings
You may want to duplicate a mapping to create an updated version or to use an existing mapping as a starting point for a new one.
Duplicated mappings have a unique ID from the original that you can use in [Mappings API](/edi-platform/mappings/manage-mappings/api-guide) calls. This approach lets you quickly roll back to the previous version if necessary.
To duplicate a mapping:
1. Go to your [Mappings dashboard][mappings-product], click the ellipses (`...`) next to the mapping you want to duplicate, and select **Duplicate**.
2. Choose a name for the duplicated mapping and click **Duplicate**. The duplicated mapping is now available in your Stedi account.