Channel Mappings

A channel mapping is the permanent link between a record in TRADElube and its counterpart in a connected system. TRADElube holds them on all six main objects: on products, manufacturers, categories, media, orders and customers.

The reason for them: a product sitting in an online shop is a record of its own there, with an identifier of its own that usually looks nothing like yours. So that the next execution finds this counterpart again and updates it instead of creating it a second time, TRADElube remembers the connection.

That note is inconspicuous and still carries half of the synchronization. Above all it is the thread the traces hang from: every record carries its own mapping, with its own state and its own log. When something goes wrong, what happened to that one product is therefore answered in a few clicks, field by field. That is the difference between a query taking minutes and one taking days in which nobody knows where the value came from at all.

And nearly every "the product is suddenly in the shop twice" goes back to a channel mapping that no longer matched.

What a channel mapping is

A channel mapping always belongs to one record and one channel. A product sitting in two shops therefore has two of them, and it may carry a completely different identifier in each shop.

They can be seen on the record itself, in the Channels section. It always sits at the very bottom of the detail page, and it is the same on all six objects: open a product, a manufacturer, a category, a medium, an order or a customer with the button Edit and go to the end of the page.

Channels section of a product with three channels and three differently built mappings

There each row holds a channel, the counterpart's identifier in the Mapping column, when it was last transferred, when something last changed, and the state. What these identifiers look like is decided solely by the connected system: a supplier file supplies a readable number, one shop system a long character string, another a composite identifier. You do not have to be able to read any of it. All that matters is that something is there.

Three similar words, three different things

At this point three terms sit close together and are easily confused. The interface keeps them cleanly apart, and lumping them together means looking in the wrong place later:

Word	What is meant	Where it lives
Assignment	One row in the transfer plan: where a value comes from and which field it is written to	on the task, in the Transfer Plan section
Mapping	A value pairing between the two sides for pick lists, for instance which shop order status corresponds to which status in TRADElube	on the channel, in the Mappings section
Channel mapping	The permanent link of one record to its counterpart, which is what this page is about	on the record, in the Channels section

The middle one applies to a whole list and is set up once. The last one applies to exactly one product, is created automatically, and grows with every record.

How it arises

You do not create a channel mapping, it arises during the execution. On import it carries the value the source brings along as an identifier, for instance the supplier's identifier for this article. On export it is the identifier the target system returns when creating the record.

Where you get to influence that depends on the kind of channel, and the three cases look different:

Channel	What a record is recognized by
Standard channel with tasks, an online shop for instance	The identifier is dictated by the connected system. All that is configurable is what an already existing entry is recognized by the very first time: the row Existing Item in the task's Selection section, see transfer plan
Custom channel	The Mapping assignment on the transfer plan's record set determines what becomes the identifier. It is the freest of the three settings and therefore the most consequential
Connector, where the other side signs in	Nothing to set. The connected system sends its own identifier along. Where TRADElube does not know it yet, it falls back to the product number

Where the structure has several levels, the identifier is put together across those levels. That is why a record's mapping occasionally looks like two identifiers with a separator between them, and that is exactly right: a variant is identified by its parent article and its own identifier.

What it hangs on, and when it breaks

The decisive point is which value you make the mapping, because that value has to stay the same for years. It is not a field maintained in passing, it is the record's identity with respect to this channel.

The obvious choice, and still the wrong one, is the article number. It is a label and it changes in everyday work: a supplier renumbers, a range is reorganized, a number gets corrected. What comes of that is in the next section.

The right choice is an identifier the source itself treats as unchanging and that has nothing to do with the label.

The question only arises where you have the choice, that is on the custom channel. On an online shop the target system issues the identifier itself, and there is nothing to decide.

Two further ways a channel mapping loses its reference:

The counterpart is deleted in the connected system. The mapping then points at something that no longer exists. The next execution creates the record afresh.
The channel is deleted. All of its channel mappings go with it. A later transfer through a new channel creates every record in the target system again, even if everything is still sitting there.

When the supplier renumbers

How much hangs on this one setting becomes clear on the most common occasion for it: at the turn of the year your supplier reorganizes their number ranges. 4700-1015 becomes LK-1015, across 1,200 articles at once. The following night the import runs as always, and what it does is decided by the Mapping assignment in this channel's transfer plan:

What is set as the mapping	What the next execution does
the article number	Not one of the 1,200 rows finds a channel mapping. TRADElube takes every one of them for a new article and creates it. You then keep 2,400 products, and the upload puts 1,200 of them into the shop on top of the others
an identifier the supplier never changes	Every row finds its article. The new number is written into the Product Number field, and nothing else changes. In the morning the shop holds the same number of articles as it did in the evening

The difference costs you nothing on the day you set it up, and afterwards it cannot be taken back. From that execution on, the 1,200 newly created products carry valid channel mappings of their own. TRADElube goes on working with them consistently and cannot know it is keeping the same articles twice. Tidying up then means deleting, in the shop and in the client.

So the question to put to the source is not "which column is unique" but "which column does your supplier never change". And if there is no such column, that is an answer and not an omission: then the article number is what there is, and a renumbering becomes an announced date we handle together, instead of a surprise in the night.

The route from the mapping into the traces

The state on the mapping says that something was transferred, and what its values mean is under traces. What exactly was transferred is one click further on, and that connection is the real point of the channel mapping: it is the only place where a single record and a single execution come together.

In the Channels section select the row of the channel you are interested in, and the button Show Traces becomes active. The dialog behind it is split into tabs, one per task, each tab carrying the task's name. So decide beforehand which operation you want to examine: products and stock run through two different tasks and therefore sit in two different tabs.

The top of the tab says what it is about, and these four entries answer most questions already: Object Info names the record, State its result, Executed At when the execution happened, and Changes At when something last actually changed. Where the two timestamps sit far apart, the last execution had nothing left to do.

Traces dialog with one tab per task, object info, state and the beginning of the transferred content

Below that sits the actual content of the transfer, as the other system delivered it or took it in. The format is technical, usually XML or JSON, but it can still be read: if it says <price>19.99</price> while you expect 24.99, the question is answered without you having to understand the format.

You see not only the latest state there but the previous ones as well. What is kept and how far the history reaches back is under traces.

It works the other way round as well: in the overall traces view the button Goto leads straight into the record concerned.

The detailed route with pictures is under Traces (guides).

How it fits together

The channel mapping is where the other terms come together:

The channel owns it. The mapping arises and disappears with the channel.
What a record is recognized by is decided on the custom channel by the Mapping assignment in the transfer plan, on a standard channel by the row Existing Item in the task's Selection section, and on a connector by the other side. Wherever you can set it, it is the single most consequential setting.
The task carries it forward, on every execution.
The traces hang from it: for every pair of channel mapping and task there is exactly one entry holding that record's transfers.
References between records run through it: a product finds its category in the shop because the category has a channel mapping there. That is why the category has to have been transferred first.