Referencing a cache in mapping transformations

Introduction

If caches have been added to your process flow or company-level caches have been added for use in any process flow, you can reference these in field mapping transformations.

Using a cache lookup transformation function, you can look up values from a cache and map them to fields in a target system.

If you've added/updated a map shape 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.

Adding a cache lookup transformation

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

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

Step 3 Click the add transform button:

Step 4 Click the add transform button:

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

Step 6 Cache reference fields are displayed:

Complete these fields using the table below as a guide:

Field	Summary
Cache	Use the dropdown list to select the cache that you want to reference. Available caches will be: All flow-level caches added for this process flow All company-level caches added from any process flow All flow run-level caches created for this run
Key	Enter the key that was specified in the add to cache shape for the cache that you want to access here. 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 Using output from a transform as the lookup cache key section.
Lookup	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.
Default	If required, specify a default value to be used if the cache lookup transform doesn't find a value to return.
Load all pages	When paginated data is pulled from a connection shape, a payload is created for each page. If the save all pages option is toggled ON when a cache is created, the payload for each page is saved to its own cache key (with key names generated dynamically from a specified key and page numbers). The load all pages option here can be used if you want to lookup all of these pages.
Fail on miss	If this option is togged ON, the map shape (and therefore the process flow) will fail if the cache lookup can't be fulfilled.

Lookup notation example

Let's look at a sample payload:

[
    {
        "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"
    }
]

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

*.customerID

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

0.customerID

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

1.customerID

Step 7 Accept your changes:

...then save the transformation:

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:

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) 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 transform function to join itemref and last_name fields with a hyphen.

• Add a cache lookup transform function as defined above, 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.

The example above describes how you might use a concatenate transform function as the means to generate a cache key however, the output from any transform function can be used.

Related information

• Add to cache shape

• Load from cache shape

• Cache maintenance