Working with field mappings

Introduction

This page provides guidance on using the map shape to configure field mappings between two connections.

Configuring a new map shape

Show me

Step 1 Click the source endpoint option:

...source and target selection fields are displayed:

Step 2 Use source and target selection fields to choose the required connector instance and associated endpoints to be mapped - for example:

Any instances defined for your company profile are available to select as the source or target. If you aren't using a connector to retrieve data (for example, you are sending in data via the Inbound API or a webhook), you won't select a source endpoint - instead, use the override source format dropdown field to select the format of your incoming data:

Step 3 Click the generate automatic mapping button:

...when prompted to confirm this operation, click generate mapping:

If you need to access the generate automatic option for an existing mapping shape, you need to click into the source and target details first.

Show me

Step 4 Patchworks attempts to apply mappings between your given source and target automatically. A mapping rule is added for each source data field and, where possible, a matched target field - for example:

From here you can refine mappings as needed. You can:

Step 5

Toggle wrap input payload and wrap output payload options ON/OFF as required.

Where:

  • wrap input payload ON. Wraps the incoming payload in an array [ ] ONLY for processing within the map shape.

  • wrap output payload ON. Wraps the outgoing payload in an array [ ] ONLY for onward processing.

Click options below for payload examples showing how these options work in practice:

Wrap input payload: ON / Wrap output payload ON

Incoming payload

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

Payload used for map shape processing

[{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}]

Output payload for onward processing

[{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}]
Wrap input payload: ON / Wrap output payload OFF

Incoming payload

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

Payload used for map shape processing

[{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}]

Output payload for onward processing

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}
Wrap input payload: OFF / Wrap output payload ON

Incoming payload

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

Payload used for map shape processing

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

Output payload for onward processing

[{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}]
Wrap input payload: OFF / Wrap output payload OFF

Incoming payload

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

Payload used for map shape processing

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

Output payload for onward processing

{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}

Step 6 Save changes.

Adding a new mapping rule

You can add as many new mapping rules as required to map data between source and target connections.

The steps

Step 1 Click the add mapping rule button:

...a new mapping rule is added:

Step 2 Click the source element of the new mapping rule:

...source details are opened in edit mode:

Step 3 Move down and select the required field from the payload associated with your source connection - for example:

Step 4 Set the display name as required - for example:

Step 5 Accept your changes:

...the mapping rule is updated with a source field:

Step 6 Click the target element of the new mapping rule:

...target details are opened in edit mode:

Step 7 Move down and select the required field from the payload associated with your target connection - for example:

Step 8 Set the display name as required - for example:

Step 9 If your target system will not accept null and/or empty values received for this field, move down to the remove field conditions field and select the required condition(s):

You can apply one or both conditions.

Step 10 Accept your changes. The mapping rule is updated with a target field:

Step 11 You can now add more rows as required, but it's a good idea to save changes frequently:

If you exit from the mapping editor without saving changes, any updates made to mapping rules since the last save will be lost.

Show me

Specifying a mapping field manually

There may be times where you don't want to (or can't) use the payload fields dropdown select a field from your source/target data schema. In this case, you simply select the manual input field and enter the full schema path for the required field.

The steps

Step 1 Click the source or target element of the mapping rule that you want to update:

Step 2 Once the rule is opened in edit mode, select the manual input checkbox - for example:

Step 3 Click the accept button to confirm your change:

Step 4 Accept changes.

Show me

Changing display names or fields in an existing rule

You can change the display name and/or the field associated with the source or target for any mapping rule.

The steps

Step 1 Click either the source or target element of the mapping rule (it doesn't matter which - both sides of the mapping will be available to edit):

Step 2 Update the existing display name as required.

Step 3 Click the accept button to confirm your change:

Show me

Adding a target mapping for a partial mapping rule

If you've used the automatically generate map option to generate an initial set of mappings, you may find that some source fields could not be auto-mapped. In these cases, a mapping rule is added for each un-mapped source field, so you can either add the required destination or delete the rule.

The steps

Step 1 Click the source element of the mapping rule to open the rule in edit mode - for example:

Step 2 Click the add destination field button:

Step 3 Move down and select the required field from the payload associated with your source connection - for example:

Step 4 Set the display name as required - for example:

Step 5 If your target system will not accept null and/or empty values received for this field, move down to the remove field conditions field and select the required condition(s):

You can apply one or both conditions.

Step 6 Accept your changes.

Show me

Mapping a source field to multiple targets

If required, you can map a source field to multiple target fields - for example, you might need to send a customer order number into two (or more) target fields.

The steps

Step 1 Click the target element of the mapping rule that you wish to update with an additional target field - for example:

...the mapping rule opens with the current target field in edit mode - for example:

Step 2 Click the add destination field button:

...a new target field placeholder is added beneath the existing one - for example:

Step 3 Click in this field to activate settings fields below - for example:

Step 4 Move down and select the required field from the payload associated with your target connection - for example:

Step 5 Set the display name as required - for example:

Step 6 If your target system will not accept null and/or empty values received for this field, move down to the remove field conditions field and select the required condition(s):

You can apply one or both conditions.

Step 7 Accept your changes.

Show me

Mapping multiple source fields to a single target

Sometimes it can be useful to map multiple source fields to a single target field. For example, you might have a target connection which expects a single field for 'full name', but a source connection with one field for 'first name' and another field for 'surname'.

In this case, you would define mappings for the required source and target fields, then add a transform function to concatenate the two source fields.

The steps

Step 1 Click the source element of the mapping rule that you wish to update with an additional source field - for example:

...the mapping rule opens with the current source field in edit mode - for example:

Step 2 Click the add source field button:

...a new source field placeholder is added beneath the existing one - for example:

Step 3 Click in this field to activate settings fields below - for example:

Step 4 Move down and select the required field from the payload associated with your source connection - for example:

Step 5 Set the display name as required - for example:

Step 6 Accept your changes. The mapping rule is now displayed with two source fields - for example:

Show me

Deleting a mapping rule

When you choose to delete a mapping rule, it's removed from the list immediately. However, the deletion is not permanent until you choose to save the mapping shape.

The steps

Step 1 Click the source or target element associated with the rule that you want to delete - for example:

...the mapping rule opens in edit mode - for example:

Step 2 Click the delete mapping row button to remove the rule immediately:

Step 3 Save the mapping shape.

Show me

Last updated