Mappings explained
Lesson 9 of 15 8 min read
Mappings are the routes between your Integrations. Learn what each field does, when to use filters, and the difference between Target Data and Document.
A Mapping tells Supply Lens where to send a Document once it has arrived from a source system. Without a Mapping, data arrives in Supply Lens but has nowhere to go. With the right Mappings in place, your systems stay in step automatically.
In this lesson you will learn how to think about Mappings, what each field controls, and the handful of patterns that cover most businesses.
Each arrow is one Mapping
Think of your Integrations as places on a map and Mappings as the one-way roads between them. A simple setup with a web shop and an ERP needs at least two Mappings:
Add a warehouse and you need more:
Each arrow in those diagrams is one Mapping record in Supply Lens. Mappings are one-way: to move orders one way and stock levels the other, you need two.
The core fields
Mappings live under Settings → Integration setup → Mappings.
| Map | The document type to route, for example Order, Inventory or Shipment. |
|---|---|
| From | The source Integration. Supply Lens listens for Documents of this type arriving on it. |
| As | Whether to send straight to another Integration (Target Data) or to produce an intermediate Document (Document). |
| To | The destination Integration. |
Read a Mapping as a sentence: Map Orders from Shopify as Target Data to Unleashed.
Behaviour switches
| Enabled | Whether the Mapping runs at all. Turn it off to pause a flow without deleting it. |
|---|---|
| Automatic | Whether the Mapping runs as soon as a matching Document arrives. When off, matching Documents wait with a Ready status until someone processes them by hand. |
Automatic off is a review step
Turning Automatic off is a deliberate way to check Documents before they are sent, for
example while you are going live or for a retailer whose orders need a human eye. Remember
to turn it back on, or Documents will pile up as Ready.
Filters: narrowing a Mapping
By default a Mapping applies to every Document of its type from its source. You can narrow it so it only applies to some. Leave a filter blank to match everything.
| Filter | Only route documents... |
|---|---|
| Customer | from this customer or buyer |
| Supplier | from this supplier |
| Ship to / Ship to location | addressed to this party or location |
| Ship from / Ship from location | coming from this party or location |
| Tags | that carry these tags (one per line) |
| Target tags | (not a filter) applies these tags to the outbound data at the target |
| Status update types | only when these status updates occur (one per line) |
Target Data or Document?
The As field has two options.
- Target Data is the usual choice. Supply Lens takes the incoming Document, produces the format the target Integration expects, and sends it. One step, one hop.
- Document makes Supply Lens produce a new, intermediate Supply Lens Document instead of sending anywhere directly. Use it when there is no direct translation between what comes in and what the target expects, or when you want to create one kind of Document from another, such as an Invoice from a Shipment. A second Mapping then sends the new Document on.
Common patterns
| Pattern | From | Map | To |
|---|---|---|---|
| Orders from storefront to ERP | Shopify | Order | Unleashed |
| Stock from ERP to storefront | Unleashed | Inventory | Shopify |
| Order to warehouse | ERP | Warehouse Order | 3PL Integration |
| Despatch back to storefront | 3PL Integration | Shipment | Shopify |
You can also send one document type to several targets by creating a Mapping for each. Supply Lens processes them independently, so if one fails the other is not affected.
A wholesale customer at Hilltop
Hilltop Coffee starts supplying a café chain, Bean There, through its Shopify B2B store. Bean There's orders need to go to Unleashed like everyone else's, but also to a specialist roasting planner. Priya keeps the existing Mapping (Orders, Shopify to Unleashed) and adds a second one (Orders, Shopify to the roasting planner) with Customer set to Bean There. Now every order reaches Unleashed, and only Bean There's orders also reach the planner.
Good to know
Once you have a few Mappings, Clone on the Mappings list opens a pre-filled copy you can adjust and save, and Bulk add creates the same Mapping for several Integrations at once, showing every pairing before anything is created.
Recap
- A Mapping is a one-way route: Map a document type From one Integration As Target Data or Document To another.
- Enabled pauses or resumes a route; Automatic off holds Documents as
Readyfor manual processing. - Filters such as Customer, Ship to and Tags narrow a Mapping; blank means everything.
- Use Target Data for a direct hop and Document when you need an intermediate Document and a second Mapping.
- Several Mappings can route the same document type to several targets, independently.
Quick guides for this topic
Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.