Insights & updates from our experts
Overview
A lookup table is a table of text values that belongs to the iPaaS account, not to a single job or solution. Runbooks use it to keep data between runs, for example to remember which Xurrent request belongs to which ticket in another system, to translate codes from one system to another, or to note which records a scheduled job already processed.
Lookup tables are managed under Lookup tables in the left sidebar of iPaaS. The Lookup Tables connector gives runbook steps access to them. A connection names one table, and each step on that connection reads or writes that table.
- Every value is stored as text. Numbers,
true/false, times and dates are converted to text when they are written. - Spaces, tabs and line breaks at the start and end of a value are removed.
- Matching is exact and case-sensitive.
ABC-1does not matchabc-1orABC-1. - Each entry gets an Entry ID (a UUID) when it is added. Entries are returned oldest first.
Prerequisites
- A lookup table in the account with at least one column. Create it under Lookup tables → Create table, then choose Add column.
- A Lookup Tables connection in the solution that names the table.
Managing lookup tables
The Lookup tables page lists every table in the account with its number of columns and entries and the time of the last change. Open a table to:
- Add, rename and remove columns. A removed column keeps its values for a while and can be restored until they are cleared. Its values are cleared automatically later, or straight away with Clear now. An entry that has no other value left is then deleted.
- Add, open, edit and delete entries, and search entries by column values (exact match, case-sensitive).
- Rename table, Truncate table (delete every entry) or Delete table. You must type the table's name to truncate or delete it. A table can only be deleted when no solution has a connection to it. The dialog lists the solutions that use it.
Connection
| Field | Type | Required | Description |
|---|---|---|---|
Table | String | Yes | The name of a lookup table in this account. When you save the connection, iPaaS finds the table and lists its columns. The table name must be a fixed value. It can't come from a variable or expression. |
The connection keeps a list of the table's columns. Each step on the connection shows one field per listed column. When columns are added or renamed later, the connection shows Refresh columns. Choose it so that steps show the new columns. Jobs always use the table's current columns.
A connection stays tied to its table after steps use it. To use another table, create a new connection. A step can't move to a connection for another table. Add a new step there instead.
Triggers
None. This connector is used in runbook steps only.
Actions
All actions except Delete Entry and Truncate Table return the entry or entries together with columns, the list of the table's columns (column key and label). In the designer, the fields of entry show under their column labels.
Map each column field separately. A column field takes one mapping per column. You can't map the whole Values, Lookup by or Search by object from one expression, variable or fixed value.
Add Entry
Adds an entry to the connection's table.
Use case: Store the ID of a ticket created in another system against the Xurrent request it belongs to.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
values (Values) | Object, one field per column | Yes (at least one value) | – | A value per column. Each mapped column gets its value as text. A column left unmapped gets no value. An entry needs at least one value that is not blank. |
Output
| Field | Type | Description |
|---|---|---|
entry_id | String | The Entry ID of the new entry. |
entry | Object | The entry's values, one field per column. Columns without a value are null. |
columns | Array | The table's columns: column (key) and label. |
Error Handling
The step fails when every value is blank, when the table has no columns, or when the table is full.
Lookup Entry
Finds the oldest entry whose mapped columns all match exactly (case-sensitive).
Use case: Translate a value from one system to another, such as a Jira project key to a Xurrent team.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
match (Lookup by) | Object, one field per column | Yes (at least one column) | – | The values to match. All mapped columns must match. A column may take a list of values. The column matches when it equals any of them. |
Output
Same as Add Entry: entry_id, entry and columns.
Error Handling
The step fails when no entry matches. It also fails when a mapped value is blank, because a blank value can't be matched. To continue when nothing is found, put the step in a Try/Catch block, or use Search Entries and check whether entries is empty.
Search Entries
A nested action. It runs the steps inside once per page of matching entries, oldest first.
Use case: Process every entry for one customer, or check whether a value exists without failing the job.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
match (Search by) | Object, one field per column | Yes (at least one column) | – | The values to match, as for Lookup Entry. |
at_most (At most) | Integer | No | No limit | The most entries to return across all pages, as a whole number. |
Output (per page)
| Field | Type | Description |
|---|---|---|
entries | Array | A page of entries, each with entry_id and entry. |
columns | Array | The table's columns: column (key) and label. |
When nothing matches, the steps inside run once with entries empty.
Get All Entries
A nested action. It runs the steps inside once per page of entries, oldest first.
Use case: Export a whole table, or loop over every mapping during a scheduled sync.
Input Parameters
None.
Output (per page)
Same as Search Entries: entries and columns. An empty table runs the steps inside once with entries empty.
Update Entry
Changes the values of one entry.
Use case: Record the latest status or sync time of a linked record.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
entry_id (Entry ID) | String | Yes | – | The Entry ID of the entry to change, usually from a Lookup Entry or Search Entries step. |
values (Values) | Object, one field per column | No | – | A value per column to write. A mapped column is written as sent, so a blank value clears it. Unmapped columns keep their values. With no column mapped, nothing is written and the entry is returned unchanged. |
ignore_if_not_found (Ignore if not found) | Boolean | No | false | When on, a missing entry returns no entry (entry_id and entry are null) instead of failing the step. |
Output
The whole entry after the change: entry_id, entry and columns.
Error Handling
The step fails when the entry would have no values left. Use Delete Entry instead.
Delete Entry
Deletes one entry.
Input Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
entry_id (Entry ID) | String | Yes | – | The Entry ID of the entry to delete. |
ignore_if_not_found (Ignore if not found) | Boolean | No | true | When off, a missing entry fails the step. |
Output
| Field | Type | Description |
|---|---|---|
deleted_entry_id | String | The Entry ID that was deleted, or null when there was no such entry. |
Truncate Table
Permanently deletes every entry of the table. The table and its columns stay.
Important: The entries are deleted for every solution that uses the table, and this can't be undone.
Input Parameters
None.
Output
| Field | Type | Description |
|---|---|---|
count | Integer | How many entries were deleted. |
Example
A table Jira links has two columns, Request ID and Jira key. A Lookup Entry step maps Request ID from the trigger. Its output looks like this:
{
"entry_id": "01a159ba-0ad3-7361-975e-5156287da3b3",
"entry": {
"01a19d02-4c1e-7a10-8f3b-2d6e9c0a1b11": "81415508",
"01a19d02-5e72-7b44-9c08-7f1a3d2e4c22": "OPS-1042"
},
"columns": [
{ "column": "01a19d02-4c1e-7a10-8f3b-2d6e9c0a1b11", "label": "Request ID" },
{ "column": "01a19d02-5e72-7b44-9c08-7f1a3d2e4c22", "label": "Jira key" }
]
}
In the job output, each field of entry is keyed by its column's key, and columns pairs each key with its label. In the designer you don't need the keys: the fields of entry show under their column labels (here Request ID and Jira key), so later steps can map Jira key directly.
Solutions, promotion and test cases
- Tables are shared by the account. Every solution in the account that has a connection to a table sees the same entries.
- Export and import. A solution carries the names and columns of the tables it uses, not their entries. When you import a solution as a zip, iPaaS creates any table or column that is missing in the account. It shows what it will create before you confirm. A GitHub sync can't create tables or columns. Import the solution as a zip first.
- Promotion is blocked when a step uses a column that was removed, or a column that the connection doesn't list. The message names the step. Fix the step or choose Refresh columns on the connection.
- Test cases can read lookup tables but can't write to them. Mock the write steps in a test case.
- Steps that still use a removed column fail until they stop using it or the column is restored. The designer marks these steps.
- Table names are unique in the account, and the check ignores case. Values can't hold secrets, such as connection credentials.
- When a table is busy because other jobs are writing to it at the same time, the step tries again every 5 seconds for up to 10 minutes before it fails.
Best Practices
- Normalize values before writing and before matching (for example, use the same case), because matching is exact and case-sensitive.
- Use Lookup Entry when exactly one match is expected and a missing match is an error. Use Search Entries with At most set to 1 when a missing match is normal.
- Before Add Entry, search first so that you don't create duplicates. Lookup tables don't enforce unique values.
- Keep the Entry ID from a lookup or search and pass it to Update Entry or Delete Entry.
- Use one table per purpose and give columns clear labels. Runbook steps show the labels.
- Be careful with Truncate Table in shared tables, because it affects every solution that uses the table.
Common Use Cases
- Cross-system ID mapping: link Xurrent requests to tickets in Jira, ServiceNow or another tool so that updates go to the right record.
- Value translation: map categories, priorities, sites or teams from one system's codes to another's.
- Sync state: remember which records were processed or the last sync time between scheduled runs.
- Configuration data: keep routing rules or recipient lists that administrators edit on the Lookup tables page without changing the runbook.



.webp)










.webp)

















