1. Contents
  2. Guides
  3. Channels and tasks
  4. Scripts in the transfer plan

Scripts in the transfer plan

Most assignments get by with a field source or a fixed value. A script is the move for the rest: when a value has to be calculated, concatenated, reshaped or looked up before it may enter the target field. This guide shows when that pays off, how the script dialog works, and what a worked example looks like. Switching an assignment to As Script Assignment is covered under adjusting the transfer plan.

Prerequisites

  • An assignment that can be switched to a script. The row itself shows which ones can, through its toggles.
  • Basic JavaScript knowledge helps, but is not needed for the examples on this page.

When a script pays off

A script pays off when a rule stands between source and target:

  • Concatenating and splitting: joining two columns into one designation, or cutting a part out of an article number, ArtNr.substring(0, 4) for instance.
  • Deciding per row: return IsVariant == 0 ? Ean : null; for instance, which sets the EAN on the single article only and clears it otherwise.
  • Looking up: finding another record, FindProductWithMapping(GroupId) for a variant's parent product for instance.

And when not: if a field source delivers the same value, it is the better choice. Every script is configuration that has to be read and maintained, and the plan row does not show what it does. The filter and the condition from restricting the transfer scope are the same technique, by the way, only with yes or no as the result.

Step by step

  1. Open the dialog. Switch the assignment to As Script Assignment and click Edit. The dialog has three parts: at the top the list of variables and functions with sample values, below it the editor, and next to the editor the pane in which Simulate shows its result.

  2. Read the list before writing. It is at once the type reference of your record and the function reference of this target field: every source column is listed there with its type, and below it the functions exactly this assignment offers. What is not listed there does not exist here. The available functions differ per target field.

The script dialog of a filter assignment with the variable and function list at the top, the editor below it and the Simulate button

  1. Write and simulate. The script is JavaScript, and its return delivers the target field's value. Simulate runs it immediately with the sample values from the list. A typo shows up here rather than in the execution.

  2. Apply and save. The editor applies its content when you leave the field. So click out of the editor first and then close the dialog before saving the task.

Example: categories as tags in the shop

A case where a script can replace a whole task. On the Shopify product upload the Tags row takes the Product Categories as its script source: one object per category with Name, Parent, Root, the Path and the function FormatPath(separator). Two variants:

// the names of all the product's categories, separated by commas
return ProductCategories.map(c => c.Name).join(', ');

// or the full path of the first category
return ProductCategories.length ? ProductCategories[0].FormatPath(' > ') : '';

The gain shows in the shop: an automated collection in Shopify can assemble its products through a tag condition itself, and maintaining collections through a task of their own is no longer needed. The trade-off is discussed on the Shopify channel's Products Upload task page.

Checking the result

Simulate checks the logic, the execution checks reality: start the task and look at the transferred content in the traces. The target field appears there with the value your script delivered, on real records instead of sample values.

Frequent pitfalls

  • The editor applies its content when you leave the field. Typing in the editor and saving immediately saves the old state, and the interface still reports success. Click out first, then save as in step 4.
  • A script returning text cannot set a reference. Fields pointing at a settings object, an order status for instance, only accept an object. A returned text clears the reference. Instead of the script from step 3, for such fields the fixed value with its pick list is the way to go, one record set per value, see adjusting the transfer plan.
  • A variable of your own must not be named like a source column. var color = … next to a column color from the list in step 2 shadows the column, and the script quietly works on with an empty value.
  • Restore Default is the emergency exit. The button resets the script to the delivered preset. An experiment in step 3 therefore costs nothing permanent.

Further reading