# 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)


---

# 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/advanced-shapes/cache/referencing-a-cache-in-mapping-transformations.md?ask=<question>
```

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.