# 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
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/map-shape/working-with-field-mappings.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.