Tags and tag maps

Lesson 5 of 30 8 min read

How connectors attach tags to Documents, how tag generation rules create your own, and how tag maps turn tags into values in another system.

Tags are how information travels between connectors that don't share a field for it. A marketplace knows the buyer chose "express"; the warehouse needs a ship method; the ERP has no idea either exists. Tags carry that fact across the hub, and tag maps turn it into a value the target understands. Many of the most useful settings in this course are tag settings, so it's worth getting comfortable with them now.

By the end of this lesson you'll be able to read a tag, write a tag generation rule, and build a tag map with a sensible default.

What a tag looks like

A tag is a small label on a Document made of colon-separated parts: the source that wrote it, a key, and a value. Some examples from the configuration guides:

Tag	Written by	Meaning
`b2b-wave:sales_person_email`	B2B Wave order import	The sales rep's email address
`b2b-wave:customer_discount_rate`	B2B Wave order import	The customer's discount as a rate, for example `0.2`
`magento:product_option:Rope Colour:Red`	Magento order import	A product custom option on a line
`unleashed:status:Deleted`	Unleashed import	The record's status in Unleashed

Some tags are written automatically by a connector. Others you create yourself with tag generation rules.

Creating tags: tag generation rules

Magento and eBay order Configurations (like Shopify's) offer two settings for making tags from fields on the incoming order:

documentLevelTagGeneration	Simple rules. Each has a key (the tag key to create), a path (a simple path to the field whose value becomes the tag value) and an optional source.
documentLevelAdvancedTagGeneration	The same idea for nested data. Each rule uses a JSON Path or JSON Pointer expression to pick the value out of deeply nested structures.

Use simple rules for top-level fields such as a shipping method name. Reach for the advanced version when the value sits inside a list or nested object.

Good to know

JSON Path and JSON Pointer are two standard ways of pointing at a value inside a JSON document. You'll need the channel's own API documentation (or a downloaded source data file from Supply Lens) to know what the field is called.

Using tags: tag maps

A tag map reads the tags on a Document and returns a value for a setting in the target connector. The rules are the same everywhere you meet one:

Entries are evaluated in order, and the first matching tag wins.
A default applies when no entry matches.
Each entry names the tag (source, key, and optionally value) and the value to use (data). An entry with no data takes the matched tag's own value instead.

Here is the example from the Pipedrive guide, which gives a deleted Unleashed record a different lost reason from a cancelled one:

{
  "default": "Unleashed Sales Quote / Sales Order cancelled",
  "items": [
    { "source": "unleashed", "key": "status", "value": "Deleted", "data": "Unleashed record deleted" }
  ]
}

Rendering diagram...

Tag maps in this course include Pipedrive's tagToPipelineIdMap, tagToStageIdMap and lostReasonTagMap, and Capacity's residentialFlagTagMap. On the Unleashed side, salesPersonEmailTagMap and customerDiscountRateTagMap read the tags B2B Wave writes.

Order matters

Because the first match wins, put your most specific entries first. A broad entry near the top will swallow orders meant for the entries below it.

Fern & Finch routes deals by channel

Fern & Finch sends orders into Pipedrive so the sales team can see them. Trade orders should land in the "Wholesale" pipeline; everything else in "Online".

The implementer adds a tag generation rule on the Magento order Configuration that writes a channel tag from a field on the order, then sets tagToPipelineIdMap with one entry matching channel = trade pointing at the Wholesale pipeline ID, and a default of the Online pipeline ID. Orders without the trade tag fall through to the default.

Recap

A tag is source, key and value, separated by colons, attached to a Document.
Connectors write some tags automatically; tag generation rules let you create more from order fields.
Tag maps turn tags into values for a target setting: in order, first match wins, with a default.
An entry without data passes the matched tag's own value through.
Put specific entries before broad ones.

Quick guides for this topic

How do I connect a marketplace, web shop or till system that doesn't have its own guide?

Complete and take the quiz

Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.

Customers, locations and totals Import Magento orders