correlation_cache

Looks up a source record ID in a table correlation and returns the corresponding target record ID. This is used to resolve cross-system record relationships during data migration.

Syntax

correlation_cache(correlation_name, source_id)

Parameters

Name	Type	Required	Description
correlation_name	string	Yes	The name of the table correlation to look up.
source_id	string	Yes	The primary key value of the source record to find in the correlation.

Returns

Type: string or None

The primary key value of the first matching target record, or None if no match is found or the source ID is None.

Examples

Looking up a correlated record:

correlation_cache("incidents", [sys_id])

Returns the target system ID that corresponds to the source record's sys_id in the "incidents" correlation.

Using in a field mapping:

correlation_cache("users", [assigned_to])

Translates a source user reference into the corresponding target system user ID.

Handling missing correlations gracefully:

if_null(correlation_cache("companies", [company_id]), "UNKNOWN")

Falls back to "UNKNOWN" when no correlated target record exists.

Notes

This function can only be used during procedure execution. Calling it outside of an execution context raises an error.
If the specified correlation name does not exist in the project, a ValueError is raised.
When source_id is None (e.g., the source field is empty), the function returns None without raising an error.
If multiple target records match, only the first target record's primary key is returned.
Table correlations must be configured in the project before this function can be used.

Why Use Table Correlations — Overview of table correlations and when to use them
ID Mappings — Using the ID mapping type as a declarative alternative to this function
Chaining Correlations — Using correlation_cache() in chained reference field scenarios
correlation_keys() — Companion function for retrieving all correlated source IDs