> 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/cross-reference-shape.md).

# Cross Reference

## Introduction

The **Cross-Reference** shape lets a process flow read and write [cross-reference lookups](https://doc.wearepatchworks.com/product-documentation/process-flows/cross-reference-lookups.md) directly, as data passes through.

Previously, cross-reference lookups could only be used within mapping transformations, and keeping them up to date meant editing values by hand or building cache-based workarounds. With this shape, a flow can maintain a lookup itself - for example, after creating a product in NetSuite, write the returned internal ID against the SKU, ready for any other flow to use.

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FUPhgApIOTOyQSmvwDLBm%2Ficon.png?alt=media&amp;token=fe4e6acf-bceb-47b2-aac5-834cbd16cd5f" alt="" width="142"><figcaption></figcaption></figure>

{% hint style="info" %}
Records in a cross-reference lookup do not expire, and every flow in your company can use them - unlike caches, there's no time-to-live to work around.
{% endhint %}

#### Need to know

* Each Cross-Reference shape runs **one behaviour** - *Upsert* or *Lookup*. To do both, add a shape for each.
* The payload passes through the shape **unchanged on Upsert**; on Lookup, only the configured target field is written.
* **JSON & XML are both supported** - target fields with wildcard paths for arrays (`products.*.sku`) in JSON, or XPath (including namespaces and attribute targets) in XML. Flow variables can be used in paths.
* **Safe to manage** - a lookup can't be deleted while a flow references it, and renaming a lookup won't break the flows using it.
* The shape is fully supported in flow duplication, export/import and **blueprints**, with lookups included as blueprint dependencies.
* The run log summarises exactly what each run did - e.g. `4 inserted, 0 updated, 0 unchanged, 3 skipped`.

#### Behaviours

| Behaviour                 | What it does                                                                                                                                                                 |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Upsert (insert or update) | Matches each record on the key field and inserts it into the lookup if it's absent, or updates it if it's present. The payload passes through unchanged.                     |
| Lookup                    | Matches each record on the key field and writes the matched lookup value to a target field in the payload. Keys with no match use the lookup's default value, if one is set. |

The settings available depend on the behaviour selected:

| Setting                | Upsert | Lookup | Notes                                                                              |
| ---------------------- | ------ | ------ | ---------------------------------------------------------------------------------- |
| Cross-reference lookup | ✓      | ✓      | The lookup to read from or write to - pick an existing one or create one in place. |
| Direction              | ✓      | ✓      | Which side of the lookup is the key: *left to right* or *right to left*.           |
| Key field              | ✓      | ✓      | The payload field to match on.                                                     |
| Value field            | ✓      | -      | The payload field whose value is written into the lookup.                          |
| Target field           | -      | ✓      | The payload field the matched value is written to.                                 |
| Match type             | -      | ✓      | *Exact*, *starts with* or *contains*.                                              |
| Output type            | -      | ✓      | Write the matched value as a *string* or an *integer*.                             |
| Payload format         | ✓      | ✓      | *JSON* or *XML*.                                                                   |

#### Adding a Cross-Reference shape

In this example, we take an incoming payload containing an employee's `name` and `email`, and upsert the pair into an `employees` lookup so any other flow can resolve a name to an email address.

{% stepper %}
{% step %}
**Add the shape**

In your process flow, hover over the point where the Cross-Reference step should run, click to add a new shape, and choose **Cross-Reference** from the shapes list
{% endstep %}

{% step %}
**Choose a behaviour**

Open the shape's settings and use the *behaviour* dropdown to choose **Upsert (insert or update)** - to write records into the lookup - or **Lookup**, to read from it.

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fd1boIS68gRcBfIDlnTvw%2FBehaviour.png?alt=media&amp;token=591f5615-2406-4394-98b5-859454523dc9" alt="" width="375"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Select or create a lookup**

Pick the cross-reference lookup this shape should use. If it doesn't exist yet, click **create cross-reference lookup** to create one in place - give it a name, a description, and (optionally) a default value to be used when a lookup finds no match.

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FlBTflD1r0HwEYud74LWN%2FCreate%20Cross%20reference%20table.png?alt=media&amp;token=f4d100d7-ac15-4b59-b789-1a15e49f4eb4" alt="" width="294"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Configure the fields**

Set the *direction*, then enter the payload fields to use. For our Upsert example: the *key field* is `name` and the *value field* is `email`, with the payload format set to JSON - so each incoming record stores its email address against the employee's name.

For a Lookup, you instead set a *target field* to receive the matched value, plus a *match type* (exact, starts with, contains) and an *output type* (string or integer):

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FXIpGBi19TOmsfQ3VPOWL%2FScreenshot%202026-10-28%20at%2016.12.57.png?alt=media&amp;token=e7910e1c-9dbd-4f8a-9566-c8c347f73c2f" alt="" width="375"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}
**Save and run**

Click **save** - the shape is added to the canvas, showing the behaviour and lookup name. Run the flow, and the Cross-Reference step's log line shows what happened:

`Cross Reference: 1 inserted, 0 updated, 0 unchanged, 0 skipped`

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F8Cqa2bXtZcLn8GOKj0CD%2Fexample%20payload.png?alt=media&amp;token=799762c4-bb22-40e1-8d08-459f0237e6b9" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FVzAixtxQxTBop5IsR34t%2Fexample%20run.png?alt=media&amp;token=38de0bcd-e21f-45b4-a9cb-fa0fcd8733bf" alt="" width="563"><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}

#### Managing cross-reference lookups

Values written by the shape can be viewed and managed from the [cross-reference lookups](https://doc.wearepatchworks.com/product-documentation/process-flows/cross-reference-lookups) page, where you'll find each lookup's details and its stored left/right value pairs. From here you can edit the name, description and default value, add or edit values by hand, import or upload values in bulk, or clear all values.

<div data-with-frame="true"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FWc7cin9tQZg2W1veLFCG%2FCross%20reference%20table.png?alt=media&amp;token=847bbb80-bb99-47b9-8916-8062b88df20e" alt=""><figcaption></figcaption></figure></div>

{% hint style="warning" %}
**Clear all values** removes every record from the lookup immediately and can't be undone - flows that depend on the lookup will start hitting the default value (or no match) on their next run.
{% endhint %}
