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
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.
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 payloadON. Wraps the incoming payload in an array[ ]ONLY for processing within the map shape.wrap output payloadON. 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
Payload used for map shape processing
Output payload for onward processing
Wrap input payload: ON / Wrap output payload OFF
Incoming payload
Payload used for map shape processing
Output payload for onward processing
Wrap input payload: OFF / Wrap output payload ON
Incoming payload
Payload used for map shape processing
Output payload for onward processing
Wrap input payload: OFF / Wrap output payload OFF
Incoming payload
Payload used for map shape processing
Output payload for onward processing
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.
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.
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:
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.
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.
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:
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.
Last updated
Was this helpful?