Transfer plan

The transfer plan is a task's mapping rule in TRADElube: it determines which value belongs where. Which column of a supplier file the article number comes from, which field in the shop takes the description, which record goes along at all.

That makes it the place where two systems of different shape become one shared set of data. A supplier file does not have to be reformatted first, and a target system does not have to name its fields the way the source system does. The transfer plan is thus where a general interface becomes your interface: whatever sits differently in your business than in the next one is mapped here, row by row, down to a script for the case no pick list covers.

Where the transfer plan lives

For most channels the transfer plan belongs to the task and is edited there in the Transfer Plan section. That is the place that matches the subject: a task transfers exactly one kind of object in exactly one direction, and that is all it needs a mapping for. Two tasks of the same channel therefore have two completely different plans.

For channels where the other side signs in to TRADElube there are no tasks. There the Transfer Plans section sits in the channel itself, and the tabs come in three levels: the object at the top, the action below it, the plan's sections below that. An example is the CAO-Faktura connector.

Two very different starting points

How much there is to do on a plan at all depends on the kind of channel you are dealing with. The difference is big enough to shape what you should expect:

On a standard channel the plan is largely preconfigured. We know the other side, say Shopware, WooCommerce or an ERP system, and the action brings a preset that already covers the normal case. As a rule you add individual rows, a fixed value perhaps, or a field that plays a particular part in your range. Such a plan is ready to run on day one.
On the custom channel you build the plan from the ground up. There the other side is a file or a data feed whose shape only you know. TRADElube cannot preset what it does not know, and in return you get possibilities at this point that a standard channel has no need for.

The sections below describe what applies to both first. What only the custom channel brings with it follows under a heading of its own.

The structure: plan, section, assignment

A transfer plan is nested, and you meet these three levels on every channel, including in error messages, which spell the path out in full.

Level	What it is
Plan	One complete mapping. A task can have several, and then a tab bar appears at the top. With only one plan there is none
Section	One part of the transferred object, as a tab bar: Common, Descriptions, Prices, Stocks, Categories, Media, Properties. Which ones exist depends on the action
Assignment	One row: a target field and the rule saying where its value comes from

The sections are the reason a plan stays readable even when it carries two hundred assignments: prices sit with the prices, images with the media, and anyone looking for a description opens exactly one tab.

An assignment: read from the target

An assignment is not thought of from the source but from the target: the row belongs to a field, and the question is where its value comes from. That is why the target field is on the left and not the source column.

Every target field carries two names above one another, the translated caption on top and the unchanging technical name in gray below it, for instance Product Number and ProductNumber. The second one is not an oversight: the field reappears under that name in scripts, and it stays the same whichever language you work in. Anyone who writes no scripts never needs it and can ignore the gray line.

An assignment starts out switched off. Only once you tick its checkbox does a rule exist at all, and before that the row stays empty, even though it looks as if an input field were missing. The reason for that default: what carries no rule is left untouched by TRADElube in the target system. Were every row active from the start, the first execution would overwrite every field nobody has picked a source for yet. Added to that are two restrictions that get used often: Only on Insert writes the value once, the first time, and leaves later changes in the target system alone afterwards. Only if filled skips the assignment when the source delivers nothing, instead of emptying the target field.

Three ways to determine a value

Where the value comes from is decided in one of three ways:

As Field Assignment takes the value unchanged from a column of the source. This is the normal case and covers most of a plan.
As Fixed Value writes the same value for every record, for instance a tax class or a flag the source does not supply at all.
As Script Assignment calculates the value. This is the route when two columns have to be combined, when a condition is involved, or when a reference to another record has to be looked up.

Five assignment rows with a field assignment, a script and the buttons for switching

Which ways a field allows at all can be read off the row without trying anything. The chosen way appears as the control that belongs to it: a pick list for a field assignment, an input for a fixed value, the script text with the Edit button for a script. Next to it, buttons offer only the ways this field can be switched to. Where there is no button, there is no choice.

If a column is missing from the pick list that demonstrably exists in the file, the explanation is almost always the same one, and it costs the most time the first time round: the list is filtered by data type. A text field only offers text columns, a number field only number columns. The place to look is then not the assignment but the channel's data format.

The Selection section: what gets transferred at all

The sections above answer how a value is transferred. One section answers something else, namely whether: Selection. On the tasks for products and orders it sits right at the front and is highlighted in color, because its four rows decide more than the whole rest of the plan.

Every row is a condition and only takes effect if its checkbox is ticked. If it is not, the corresponding step does not happen.

Selection section of a product task with the four rows Condition, Existing Item, New Item and Removed Item

Row	What it decides
Condition	Which records are eligible at all. Without it, everything the task covers goes along
Existing Item	What an already existing entry in the target system is recognized by. The choice is what the channel offers, on an online shop for instance With Product Number, With Manufacturer Product Number or With EAN
New Item	Whether TRADElube may create something in the target system that is not there yet
Removed Item	What happens to a record you have taken out of the channel: Delete or, where the target system can do it, Disable

The Existing Item row takes effect only the very first time. After that TRADElube knows the record's internal identifier in the target system and works with that alone, see channel mappings. That is why you may change a product number later without anything being duplicated.

Combining the rows gives the usual cases:

Maintain only, create nothing: untick New Item. Then only records already present in the target system are touched. That is the case when an ERP system owns the range and a supplier file merely adds images and properties.
Delete nothing: untick Removed Item. Whatever you take out of the channel stays in the target system.
Switch off instead of deleting: choose Disable where the channel offers it. The product stays in the shop but can no longer be ordered.

Each of the four rows can also be answered by a script where a fixed setting is not enough.

Connecting a shop that is already filled

The case where this one section makes the biggest difference: you connect a shop that already holds 3,000 articles, maintained over years. TRADElube knows none of them. What you set in the Selection section of the Products Upload task decides the first run:

Row	Your setting	What follows from it
Condition	limited to one product group to begin with	The first run covers 80 articles instead of 3,000, and the result tells you whether the mapping is right
Existing Item	With Product Number	TRADElube looks every article up in the shop by its number and takes over the entry that is there
New Item	ticked	Whatever is not in the shop yet gets created
Removed Item	unticked	Whatever you later take out of the channel stays in the shop

The second row is the one the whole day hangs on. With nothing there, the first execution finds no counterpart and creates the articles a second time. After that only tidying up in the shop helps, because TRADElube has remembered a channel mapping for every newly created article and goes on working consistently from there, even though the result is wrong.

The first row is the cheaper half of the same caution. An execution over eighty articles shows you the same mistakes as one over three thousand and can be checked by hand in ten minutes. Once the result is right, you take the condition out again and the next execution fetches the rest.

With an empty shop all that care falls away: there is nothing to pick up, Existing Item has nothing to find, and you can start with the full range straight away.

Several plans and their order

A task can have several plans, and they are applied one after another per row read, in the order of their tabs. That is more than cosmetics: if one plan creates a record a later plan refers to, it has to come first. In the reverse order the second plan does not find its counterpart on the first execution.

The usual case for this is products with variants. One plan builds the parent article, the second the variants that look for it.

Where the plans come from depends on the channel. On a standard channel the action brings them along, and their names say what they are about: an online shop's Products Upload task has the plans Product and Product Variant, and there is nothing else to set up there. On the custom channel you create the plans yourself, because only you know how many levels your file has. New ones are appended at the end and can then be moved forward.

What only the custom channel brings

On a standard channel the shape of the other side is known and fixed. On the custom channel it is not, because there the other side is a file or a data feed whose shape differs from case to case. That is why this channel has an additional section, Layout, in which you describe that shape first.

The unit within it is called a Record Set and stands for one level of the file, the rows of a CSV file for instance, or a node in an XML structure.

Transfer plan with the plan tabs, the section tabs and the record set Article list CSV

A record set then carries assignments that do not fill a field but steer the execution:

Assignment	What for
Mapping	What a record is recognized by, see channel mappings
Selection	Which entries are eligible at all
Filter	Which of those are passed over
Grouping	How several rows are combined into one object, variants under their parent article for instance
Replication	How one row becomes several objects, three image columns as three media for instance

Grouping and replication are the reason a supplier file can usually be read in without any preprocessing. Supplier files are rarely shaped the way a product data model looks: variants sit next to each other as separate rows, images in several columns of the same row. Both would otherwise only be solvable by reshaping the file up front.

More than one record set per section is the normal case where the same thing occurs several times. Three images per product do not come from three assignments in one record set but from three record sets.

How it fits together

The transfer plan hangs between the task and the individual record:

The task, through its action, determines which sections and which target fields exist at all. A plan without a task is not possible.
The channel, through its data format, supplies the source columns and their data types, and with them what the pick lists offer.
The channel mapping arises during the execution. What a record is recognized by is decided on the custom channel by the Mapping assignment on the record set, and on a standard channel by the task's Selection section.
What an execution made of all this is in the traces, per record and per field.

A change to the plan takes effect on the next execution, and on every record: TRADElube notices that the rule is a different one and also transfers what has not changed since last time.