> 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/advanced-shapes/cache/referencing-a-cache-in-mapping-transformations.md).

# Referencing a cache in mapping transformations

## Introduction

If caches have been [added to your process flow](/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/cache/add-to-cache-shape.md) or [company-level caches have been added](/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/cache/add-to-cache-shape.md) for use in any process flow, you can reference these in field mapping transformations. 

Using a [cache lookup transformation function](#adding-a-cache-lookup-transformation), you can look up values from a cache and map them to fields in a target system.

{% hint style="info" %}
If you've added/updated a [map shape](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/map-shape.md) before, you'll be used to selecting a **source** field and a **target** field. However, when referencing a cache we don't select a **source** field - the specified cache data is our source.
{% endhint %}

## Adding a cache lookup transformation

**Step 1**\
In your process flow, access settings for the **map shape** that you want to update:

<div align="left"><figure><img src="/files/rumaNumpAUrM7M0NuOCV" alt="" width="172"><figcaption></figcaption></figure></div>

**Step 2**\
Click the **add mapping rule** option - for example:

<div align="left"><figure><img src="/files/sQyvhN6CEB9Uun3oZIbg" alt="" width="375"><figcaption></figcaption></figure></div>

**Step 3**\
Click the **add transform** button:

<div align="left"><figure><img src="/files/aFq93FlqfaudRaoTCIIs" alt="" width="375"><figcaption></figcaption></figure></div>

**Step 4**\
Click the **add transform** button:

<div align="left"><figure><img src="/files/HWQrxp5X57pWlQhtLyLZ" alt="" width="375"><figcaption></figcaption></figure></div>

**Step 5**\
Click in the **name** field to access a list of all available transform functions, then select **cache lookup**:

<div align="left"><figure><img src="/files/WFPIpbODaZ4hfIEEgLLn" alt="" width="375"><figcaption></figcaption></figure></div>

**Step 6**\
Cache reference fields are displayed:

<div align="left"><figure><img src="/files/OY3RoSOWQ8swOU3tdxzR" alt="" width="375"><figcaption></figcaption></figure></div>

Complete these fields using the table below as a guide:

<table><thead><tr><th width="269">Field</th><th>Summary</th></tr></thead><tbody><tr><td>Cache</td><td><p>Use the dropdown list to select the cache that you want to reference. Available caches will be:</p><ul><li>All <strong>flow</strong>-level caches added for this process flow</li><li>All <strong>company</strong>-level caches added from any process flow</li><li>All <strong>flow run-level</strong> caches created for this run</li></ul></td></tr><tr><td>Key</td><td>Enter the key that was specified in the <a href="/pages/aGi157tdOz4wMkNdBOWh">add to cache shape</a> for the cache that you want to access here. <br><br>Alternatively, if this transformation is preceded by another transformation function, you can leave this field blank and pick up a value from the output of the previous function. For further information please see the <a href="#using-output-from-a-transform-as-the-lookup-cache-key">Using output from a transform as the lookup cache key</a> section.</td></tr><tr><td>Lookup</td><td>You can use dot notation to look up specific elements from the cached payload. If you leave this field blank, the full cached payload is retrieved.</td></tr><tr><td>Default</td><td>If required, specify a default value to be used if the cache lookup transform doesn't find a value to return.</td></tr><tr><td>Load all pages</td><td>When paginated data is pulled from a <a href="https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connection-shape">connection shape</a>, a payload is created for each page. If the <strong>save all pages</strong> option is toggled ON when a cache is created, the payload for each page is saved to its own <strong>cache key</strong> (with key names generated dynamically from a specified key and page numbers). The <strong>load all pages</strong> option here can be used if you want to lookup all of these pages.</td></tr><tr><td>Fail on miss</td><td>If this option is togged ON, the map shape (and therefore the process flow) will fail if the cache lookup can't be fulfilled. </td></tr></tbody></table>

<details>

<summary><img src="/files/VDlwYFR9Br2ScHUDewYv" alt="" data-size="line"> Lookup notation example</summary>

Let's look at a sample payload:

{% code lineNumbers="true" %}

```json
[
    {
        "objectId": "SI9cUU7SV2",
        "customerID": "10000006",
        "orderID": "0001",
        "first_name": "Jude",
        "last_name": "Hey",
        "productType": "musical",
        "createdAt": "2023-07-10T20:42:23.107Z",
        "updatedAt": "2023-08-09T11:47:18.790Z"
    },
    {
        "objectId": "op0wuUY8Ub",
        "first_name": "Caroline",
        "last_name": "Sweet",
        "orderID": "00002",
        "customerID": "10000005",
        "productType": "sport",
        "createdAt": "2023-07-10T20:43:25.895Z",
        "updatedAt": "2023-08-09T11:47:12.910Z"
    }
]
```

{% endcode %}

The following notation in the **lookup** field will retrieve ALL `customerID` values:

{% code lineNumbers="true" %}

```
*.customerID
```

{% endcode %}

The following notation in the **lookup** field will retrieve the FIRST `customerID` value:

{% code lineNumbers="true" %}

```
0.customerID
```

{% endcode %}

The following notation in the **lookup** field will retrieve the SECOND `customerID` value:

{% code lineNumbers="true" %}

```
1.customerID
```

{% endcode %}

</details>

**Step 7**\
Accept your changes:

<div align="left"><figure><img src="/files/9kiYa772FYtOusN5mfUH" alt="" width="375"><figcaption></figcaption></figure></div>

...then save the transformation:

<div align="left"><figure><img src="/files/4jpLOeCvZZGw4XV46UVc" alt="" width="375"><figcaption></figcaption></figure></div>

**Step 8**\
Now you can select a target field in the usual way. Once your mapping is complete, the row should be displayed without a source field - for example:

<div align="left"><figure><img src="/files/vh4XoXh8qpNlxYFfiFvO" alt="" width="375"><figcaption></figcaption></figure></div>

From here you can save changes or add more mapping rules as needed. Next time the process flow runs, the specified cache values will be mapped to the target field.

## Using output from a transform as the lookup cache key

The steps detailed above show how to configure the cache lookup transform with a known cache key. However, it's possible to populate the cache key automatically, using the output from a previous transform function.

To do this, you add a mapping row in the usual way and define any required transform functions to produce the required value for cache keys. Once this is done, add a **cache lookup** transform function (as shown [above](#adding-a-cache-lookup-transformation)) but leave the `key` field blank.

When the `key` field is blank, output from the previous transform function for the mapping is applied.

### Example

Suppose you have a cache where multiple cache keys have been defined in the form:

`itemref`-`last_name`

For example:

`1000021-Smith`

Now suppose you want to define a **cache lookup** transformation which will determine the key by manipulating mapped fields. You would:

* Add a mapping row with two source fields - one for `itemref` and another for `last_name`.
* Select `itemref` as the target field.
* Add a [concatenate](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/map-shape/working-with-field-transformations/available-transform-functions/string-transform-functions/concatenate-transform-function.md) transform function to join `itemref` and `last_name` fields with a hyphen.
* Add a **cache lookup** transform function as defined [above](#adding-a-cache-lookup-transformation), but leave the `key` field blank
* When the process flow runs, output from the **concatenate** transform function will be applied as the `key` for the **cache lookup** transform function.

{% hint style="info" %}
The example above describes how you might use a [concatenate](/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/map-shape/working-with-field-transformations/available-transform-functions/string-transform-functions/concatenate-transform-function.md) transform function as the means to generate a cache key however, the output from any transform function can be used.
{% endhint %}

## Related information

* [Add to cache shape](/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/cache/add-to-cache-shape.md)
* [Load from cache shape](/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/cache/load-from-cache-shape.md)
* [Cache maintenance](/product-documentation/process-flows/building-process-flows/process-flow-shapes/advanced-shapes/cache/cache-maintenance.md)