Introduction

The essence of process flows is to pull defined data from one Patchworks connector (i.e. a third-party system) and push it into at least one other connector (i.e. another third-party system). It’s unlikely that two third-party systems will have the same data structures, therefore we use the mapping shape to define where a data field from one connector should be placed in another.

When you build a connector using the connector builder, available field mappings are determined by the data schema specified for the endpoint. Field names used in data schemas can appear to be quite random and complex - this is fine if you know the schema and you're the only company ever likely to install the associated connector, but if you think that you might want to share your connector with other Patchworks customers in future, then field tagging is really important.

What is a field tag?

A field tag is a standard Patchworks tag that can be applied for a data field in the schema associated with a connector endpoint.

The Patchworks field tag taxonomy covers a wide range of entities across orders, products, fulfilments, and inventory. You'll see this if/when you come to apply field tags.

How do field tags help?

By standardising how fields are identified across all connectors, we can automate mappings between them.

So, if you add two connection shapes to a process flow - each with endpoints that have been fully tagged - you'll find that mappings are automatically created when you add a map shape between them. Without field tagging, you need to apply mappings manually.

Do I have to apply field tags?

Field tagging isn't mandatory if you're building a connector that will only ever be used within your own company.

However, if there's a chance that you'd like to share your connector in the Patchworks marketplace for other organisations to install, then you must apply standard Patchworks field tags - this will be a condition of verification.

Can I apply multiple field tags for a single field?

Yes - if a data field in your schema needs to be associated with more than one tag, you can apply as many as you need.

What are tracked fields?

When you choose to add a field tag, you'll see a tracked option. Typically, this should be set for fields that you might need to track if/how records have been processed.

For example, if you're configuring an endpoint to receive 'order' data, there will usually be some sort of order id field that uniquely identifies each order; if you're configuring an endpoint to receive 'customer' data, there will usually be some sort of customer id field that uniquely identifies each customer.

By marking these fields as 'tracked', they become for viewing/filtering/selecting wherever tracked data is shown in Patchworks.

Introduction

When you build a connector using the connector builder, available field mappings are determined by the data schema specified for the endpoint. The schema tab is split into two panels - for example:

Introduction

Schemas aren't mandatory but they make things much simpler when building process flows. If your flow includes endpoints associated with schemas, any field selector options in process flow shapes are populated with the schema structure - all you need to do is choose the required field.

For example, the filter shape below is picking up the schema associated with the Shopify endpoint, configured in the preceding connector shape:

If a process flow uses an endpoint without a schema, any field paths defined in shapes must be defined manually.

Adding a schema

To apply a schema for an endpoint, follow the steps below:

Step 1 Click the edit schema button:

Step 2 Paste in the required schema and save changes:

Setting a data path

Use the data path field to define the hierarchical level to be used for field tags and filters:

This is particularly important for JSON payloads, where the data structure is nested. Let's take an example below:

Here, all of our data is nested within one, top-level customers array object. If you scan down this example, you'll notice that there are two customer objects, each starting with an id for a customer record:

Now let's look at the data path field at the bottom of this page:

If we leave this set to empty, any subsequent field tags, mappings and filters will work on the basis that the top-level array object is our target. What we'd be saying in this scenario is 'don't treat the nested objects as separate records'.

So, for example, if we went on to apply a filter to match on first_name contains bob, we'd find a match in the second customer object but ALL objects would be returned because we're targeting the top-level array object. This isn't what we want - we need to treat each of the lower-level customer objects as separate records. To do this, we navigate the data path and select the parent object - in this case, its customers:

When you save your new data path, you won't see any changes to the schema - but the change will be applied in the field tagging tab. Here, the schema preview shows the structure that applies as per your selected data path in the schema tab.

When you come to use instances of this connector in process flows and apply a filter shape, you'll see confirmation of the selected data path in filter settings - for example:

Introduction

The Patchworks field tag taxonomy covers a range of entities across orders, products, fulfilments, and inventory. You'll see this if/when you come to . The current taxonomy is detailed in the following sections:

Customers

Introduction

To access field tags, edit an endpoint for your connector and select the schema/taxonomy tab - for example:

Adding a new field tag with/without tracking

Follow the steps below to add a new field tag for your schema:

Step 1 Click the add new tag button:

...the edit field tags modal is displayed:

Step 3 Move down to the select tags field and find a tag to apply from the Patchworks field tag taxonomy- for example:

Step 4 Click anywhere outside of the list of fields to confirm your selection.

Step 5 If you want to track this field, click the tracked checkbox to enable this option:

Step 6 Save the tag - for example:

...the new tag is added to your list:

Changing an existing field tag

Follow the steps below to update an existing field tag for your schema:

Step 1 Click on an existing tag that you want to change - for example:

...the edit field tags modal is displayed and any existing tags are shown - for example:

Step 2 To remove an existing tag to replace it with another, click the associated 'cross' icon - for example:

...then use the select tags field to find a replacement tag from the Patchworks field tag taxonomy- for example:

Step Save the tag.

Removing an existing field tag

Follow the steps below to remove an existing tag for your schema:

Step 1 Click on an existing tag that you want to remove - for example:

...the edit field tags modal is displayed and any existing tags are shown - for example:

Step 2 Remove all existing tags using the associated 'cross' icon - for example:

Step 3 Once all tags are removed, save the tag - for example:

What if there's no field tag for a field in my schema?

Don't worry! The point of field tagging is that we tag the most common fields that Patchworks has identified. If your data schema includes fields where none of our tags apply, there's no need to tag it.

Refunds

Refund line items

Refunds order adjustment

Refund line item discounts

Refund line item tax lines

Refund transactions

Fulfillments

Fulfillments line items

Products

Variant

Images

Inventory items

Inventory levels

Locations

Orders

Order lines

Order tax lines

Order line item discounts

Order line items tax lines

Discount details

Shipping address

Shipping line discounts

Shipping lines

Shipping line tax lines