Lookups Actions

Lookups actions enable you to create and manage bi-directional ID mappings between different systems. This is essential for implementing the Data Mapping Pattern in your workflows.

Available Operations

Lookup Actions

• Add ID mappings to a lookup - Create new mappings between systems
• Search lookup values - Find mappings by source or target values
• Get all lookup values - Retrieve all mappings from a lookup table
• Remove values from a lookup - Delete specific mappings

Lookup Collection Actions

• Create a new lookup collection - Set up a new lookup table
• List all lookup collections - View all available lookup tables

Add ID mappings to a lookup

Create new ID mappings between different systems.

Add ID Mappings Configuration

Parameter	Type	Required	Description
Lookup Name	String	Yes	Unique name for the lookup table
Source Value	String	Yes	Value from the source system
Target Value	String	Yes	Value from the target system
Metadata	Object	No	Additional data to store with the mapping

Add ID Mappings Example

{
  "left": "ERP_CUST_123",
  "right": "SHOPIFY_CUST_456",
  "leftMetadata": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "rightMetadata": {
    "shopifyId": "456789",
    "tags": ["vip", "premium"]
  }
}

Add ID Mappings Response

{
  "success": true,
  "data": {
    "id": "lookup_value123",
    "left": "ERP_CUST_123",
    "right": "SHOPIFY_CUST_456",
    "leftMetadata": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "rightMetadata": {
      "shopifyId": "456789",
      "tags": ["vip", "premium"]
    },
    "createdAt": "2024-01-01T10:00:00.000Z"
  }
}

Search lookup values

Find mappings by source or target values.

Search Lookup Values Configuration

Parameter	Type	Required	Description
Lookup Name	String	Yes	Name of the lookup table
Source Value	String	Yes	Source value to look up

Search Lookup Values Example

{
  "query": "ERP_CUST_123",
  "direction": "left"
}

Search Lookup Values Response

{
  "success": true,
  "data": {
    "found": true,
    "mapping": {
      "id": "lookup_value123",
      "left": "ERP_CUST_123",
      "right": "SHOPIFY_CUST_456",
      "leftMetadata": {
        "name": "John Doe",
        "email": "john@example.com"
      },
      "rightMetadata": {
        "shopifyId": "456789",
        "tags": ["vip", "premium"]
      },
      "createdAt": "2024-01-01T10:00:00.000Z"
    }
  }
}

Get all lookup values

Retrieve all mappings from a lookup table.

Get All Lookup Values Configuration

Parameter	Type	Required	Description
Lookup Name	String	Yes	Name of the lookup table
Limit	Number	No	Maximum number of mappings to return
Offset	Number	No	Number of mappings to skip

Get All Lookup Values Example

{
  "page": 1,
  "limit": 100
}

Get All Lookup Values Response

{
  "success": true,
  "data": {
    "values": [
      {
        "id": "lookup_value123",
        "left": "ERP_CUST_123",
        "right": "SHOPIFY_CUST_456",
        "leftMetadata": {
          "name": "John Doe",
          "email": "john@example.com"
        },
        "rightMetadata": {
          "shopifyId": "456789",
          "tags": ["vip", "premium"]
        },
        "createdAt": "2024-01-01T10:00:00.000Z"
      }
    ],
    "meta": {
      "page": 1,
      "limit": 100,
      "total": 1,
      "totalPages": 1
    }
  }
}

Remove values from a lookup

Delete specific mappings from a lookup table.

Configuration

Parameter	Type	Required	Description
Lookup Name	String	Yes	Name of the lookup table
Source Value	String	Yes	Source value to remove
Target Value	String	No	Target value to remove (optional)

Example

{
  "valueId": "lookup_value123"
}

Response

{
  "success": true,
  "data": {
    "removed": true,
    "valueId": "lookup_value123",
    "removedAt": "2024-01-01T10:00:00.000Z"
  }
}

Create a new lookup collection

Set up a new lookup table for ID mappings.

Create Lookup Collection Configuration

Parameter	Type	Required	Description
Collection Name	String	Yes	Unique name for the lookup table

Create Lookup Collection Example

{
  "name": "customer-mapping",
  "description": "Map customer IDs between ERP and Shopify",
  "leftSystem": "erp",
  "rightSystem": "shopify"
}

Create Lookup Collection Response

{
  "success": true,
  "data": {
    "id": "lookup123",
    "name": "customer-mapping",
    "description": "Map customer IDs between ERP and Shopify",
    "leftSystem": "erp",
    "rightSystem": "shopify",
    "appId": "app123",
    "createdAt": "2024-01-01T10:00:00.000Z",
    "updatedAt": "2024-01-01T10:00:00.000Z"
  }
}

List all lookup collections

View all available lookup tables.

List Lookup Collections Configuration

No parameters required.

List Lookup Collections Example

{}

List Lookup Collections Response

{
  "success": true,
  "data": [
    {
      "id": "lookup123",
      "name": "customer-mapping",
      "description": "Map customer IDs between ERP and Shopify",
      "leftSystem": "erp",
      "rightSystem": "shopify",
      "appId": "app123",
      "createdAt": "2024-01-01T10:00:00.000Z",
      "updatedAt": "2024-01-01T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

Common Patterns

Data Mapping Pattern

Implement the data mapping pattern for system integration:

1. Check if mapping exists
2. If not exists: Create new mapping
3. Use mapping for data synchronization

// Step 1: Search for existing mapping
{
  "query": "{{ $json.shopifyCustomerId }}",
  "direction": "left"
}

// Step 2: If not exists, create mapping
{
  "left": "{{ $json.shopifyCustomerId }}",
  "right": "{{ $json.crmCustomerId }}",
  "leftMetadata": {
    "source": "shopify",
    "customerId": "{{ $json.shopifyCustomerId }}"
  },
  "rightMetadata": {
    "source": "crm",
    "customerId": "{{ $json.crmCustomerId }}"
  }
}

Bidirectional Lookups

Create lookups that work in both directions:

// Forward lookup: Shopify ID → CRM ID
{
  "query": "shopify_12345",
  "direction": "left"
}

// Reverse lookup: CRM ID → Shopify ID
{
  "query": "crm_67890",
  "direction": "right"
}

Next Steps

Ready to explore more actions? Check out:

1. Locks Actions - Coordinate resource access
2. Last Updated Actions - Enable incremental polling
3. App Info Actions - Monitor system health