Mappings UI Builder

You can create and edit mapping definitions with Stedi’s visual mapping builder. Before you begin, we recommend reviewing the Mapping Definitions Overview.

​

Create a mapping

Go to the 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.

1. Go to the 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. 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

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. 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 into a custom format for your internal systems, then the 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 as the source schema. You must do this when creating a mapping to use with a destination webhook.
• 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.
• Provide a JSON Schema adhering to version 2020-12 that describes the shape of your data.

​

Connect a Stedi event

You can attach a mapping to a destination webhook 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. 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.

​

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

​

Use fragments

If the guide is set up to use Fragments, 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 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 endpoint and one mapping for the fragment wrapper to use with the Create Outbound Transaction endpoint. Visit 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.

​

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. 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 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 or exclude 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 for details and examples for common mapping use cases.

​

Handling floating-point arithmetic

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, 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. 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 calls. This approach lets you quickly roll back to the previous version if necessary. To duplicate a mapping:

1. Go to your Mappings dashboard, 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.