> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/map-shape/working-with-field-mappings.md).
# Working with field mappings
## Introduction
This page provides guidance on using the [map shape](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/map-shape.md) to configure field mappings between two [connections](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape.md).
## 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:
{% hint style="info" %}
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:\
{% endhint %}
**Step 3**\
Click the **generate automatic mapping** button:
...when prompted to confirm this operation, click **generate mapping**:
{% hint style="warning" %}
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.
{% endhint %}
{% hint style="info" %}
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
{% endhint %}
**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](#adding-a-new-mapping-rule)
* [Change display names and/or fields in an existing rule](#updating-an-existing-mapping-rule)
* [Add a target mapping for a partial mapping rule](#adding-a-target-mapping-for-a-partial-mapping-rule)
* [Map a source field to multiple targets](#mapping-a-source-field-to-multiple-targets)
* [Map multiple source fields to a single target](#mapping-multiple-source-fields-to-a-single-target)
* [Add transformations for a mapping rule](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/map-shape/working-with-field-transformations.md)
* [Delete a mapping rule](#deleting-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*
{% code lineNumbers="true" %}
```json
{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}
```
{% endcode %}
*Payload used for map shape processing*
{% code lineNumbers="true" %}
```json
[{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}]
```
{% endcode %}
*Output payload for onward processing*
{% code lineNumbers="true" %}
```json
[{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}]
```
{% endcode %}
Wrap input payload: ON / Wrap output payload OFF
*Incoming payload*
{% code lineNumbers="true" %}
```json
{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}
```
{% endcode %}
*Payload used for map shape processing*
{% code lineNumbers="true" %}
```json
[{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}]
```
{% endcode %}
*Output payload for onward processing*
{% code lineNumbers="true" %}
```json
{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}
```
{% endcode %}
Wrap input payload: OFF / Wrap output payload ON
*Incoming payload*
{% code lineNumbers="true" %}
```json
{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}
```
{% endcode %}
*Payload used for map shape processing*
{% code lineNumbers="true" %}
```json
{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}
```
{% endcode %}
*Output payload for onward processing*
{% code lineNumbers="true" %}
```json
[{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}]
```
{% endcode %}
Wrap input payload: OFF / Wrap output payload OFF
*Incoming payload*
{% code lineNumbers="true" %}
```json
{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}
```
{% endcode %}
*Payload used for map shape processing*
{% code lineNumbers="true" %}
```json
{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}
```
{% endcode %}
*Output payload for onward processing*
{% code lineNumbers="true" %}
```json
{"colour_1":"red",
"colour_2":"blue",
"colour_3":"green"}
```
{% endcode %}
**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](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/map-shape.md#auto-generating-mappings-between-connections) 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](#deleting-a-mapping-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](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/map-shape/working-with-field-transformations.md) to [concatenate](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/map-shape/working-with-field-transformations/available-transform-functions.md#text-string) 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
