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:

As we're configuring a new map shape, there's no danger that we would overwrite existing mappings. However, always use this option with caution if you're working with an existing map shape - any existing mapping rules are overwritten when you choose to generate automatic mappings.

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:

• Add a new mapping rule

• Change display names and/or fields in an existing rule

• Add a target mapping for a partial mapping rule

• Map a source field to multiple targets

• Map multiple source fields to a single target

• Add transformations for a mapping rule

• Delete a mapping rule

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