Getting started

Three steps take you from the Application Store to values on your orders: install the application, configure the macro, and create a Rules Engine rule that runs it.

1. Install the application

1. In Linnworks, go to Apps > Application Store.
2. Search for XmlExtractor and click Integrate.

The application adds one macro, XmlExtractor, to your account. It has no settings of its own; everything is set per configuration in the next step.

2. Configure the macro

1. Go to Apps > Macro Configuration and click Add New Configuration.
2. Select the XmlExtractor macro.
3. Give the configuration a name that says what it extracts, for example Shopify delivery instructions. You pick it by this name in the rule.
4. Fill in the parameters below and click Create Configuration.

Create one configuration per channel or per set of nodes, and point a separate rule at each one.

Parameters

Parameter	Required	Default	Description
NodesToBeExtracted	Yes		Comma-separated list of paths to extract. See Path syntax.
Target	No	ExtendedProperty	Where to write the values. One of ExtendedProperty, InternalNote, ProcessingInternalNote, Note, ProcessingNote.
Format	No	{{value}}	Template for the written text. {{value}} is the extracted value and {{key}} is the path as you typed it.
Troubleshoot	No	false	When true, writes the whole order XML to the macro's log, which RFP IT Solutions can read and you can't. Turn it on for one order when support asks, then off again.

Target is case-sensitive. Any other value logs a warning and writes nothing.

Targets

Target	What gets written	When a value is skipped
ExtendedProperty	One order extended property per path. The property name is the path and the value is the formatted text.	Never. An existing property with the same name is overwritten.
InternalNote	One internal order note per path.	An internal note with the same text already exists.
ProcessingInternalNote	One internal note flagged as a processing note.	An internal note with the same text already exists.
Note	One standard, non-internal order note per path.	A non-internal note with the same text already exists.
ProcessingNote	One standard note flagged as a processing note.	A non-internal processing note with the same text already exists.

Note comparisons ignore case.

A first path

A path names a node in the order XML. Separate levels with > and paths with ,:

Order>ShippingAddress>Phone, Order>Buyer>Email

Node names match exactly first, and ignoring case when nothing matches exactly. Each level after the first is searched at any depth below the previous match. For key/value lists, such as WooCommerce meta or Shopify checkout attributes, use a prefix instead of a path, for example WooMeta.gift_message or NoteAttribute.Delivery instructions. The full rules are in Path syntax, Examples has complete configurations per channel, and Limitations says what a path can't do, such as reading every order line.

If you don't know the node names your channel sends, Troubleshooting shows two ways to find them: the order's XML view in Linnworks, or support with Troubleshoot switched on.

3. Create the rule

1. Go to Orders > Rules Engine and create a new rule.
2. Set the conditions that identify the orders to process, for example Source equals Shopify. Any condition the Rules Engine offers works.
3. Add an action of type Execute a macro and choose the configuration you created in step 2.
4. Save the rule and enable it.

From now on the macro runs for every new order that matches the conditions, as the order downloads. Orders that were already in Linnworks when you created the rule aren't processed until something triggers the rule again.

What you'll see

• With Target set to ExtendedProperty, the values appear under the order's extended properties, named after each path as you typed it. The Rules Engine, order views, and templates can use them from there.
• With a note target, each value becomes a note on the order, formatted by Format.
• Every run writes a log that RFP IT Solutions can read in the Linnworks developer portal. It isn't visible from your Linnworks account, so when a value doesn't come through, start with Troubleshooting.