# LookUps ### What Is a Lookup? A Lookup is a built-in ZigiOps mechanism that queries a target system before performing a create or update action. It checks whether a record that matches a defined condition already exists in the target system, then decides whether to proceed with the action or skip it entirely. This prevents duplicate records from being created when multiple source events map to what should be a single target record, and gives integration builders fine-grained control over which writes reach the destination system. #### Key Characteristics * No-code configuration - set up entirely from the ZigiOps UI with no scripting required. * Works with both Poller and Listener triggers. * Lookup Conditions are mandatory - an empty condition is not valid. * Supports any query that the target system's collection supports. * If multiple target records match, ZigiOps always selects the most recently created record. ### How the Lookup Workflow Works Every Lookup action in ZigiOps follows a four-step workflow. The Lookup step is inserted between the standard field mapping transformation and the final write to the target system. | Step | Phase | What Happens | | ------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **1** | Source Query | ZigiOps sends an HTTP request to the source system to collect new or changed data, based on the configured Trigger and Filter conditions. | | **2** | Field Mapping | The collected data is internally transformed according to the integration's field mappings and any configured expressions. | | **3** | Lookup Query | ZigiOps sends an HTTP request to the target system using the configured Lookup Conditions. This checks whether a matching record already exists. | | **4a** | Match Found | Lookup Create: skips creation (no duplicate created). Lookup Update: updates the matched record (the newest one if multiple matches exist). | | **4b** | No Match Found | Lookup Create: creates a new record in the target system. Lookup Update: skips the update (no action taken). | ### Lookup Action Types ZigiOps supports two Lookup action types, each designed for a distinct part of the integration lifecycle. #### Lookup Create Use Lookup Create when you want to create a record in the target system, but only if an equivalent record does not already exist. It is the default Lookup action type and does not require enabling any additional platform settings. **Behavior:** * If no match is found in the target system: creates a new record. * If a match is found: skips creation entirely. No duplicate record is written. #### Lookup Update Use Lookup Update when you want to update an existing record in the target system, identified by a Lookup query rather than the standard correlation key. This action type must be enabled in the ZigiOps general platform settings before it becomes available in the UI. **Behavior:** * If a match is found: updates the matched record using the mapped field values. If multiple records match, ZigiOps updates the most recently created one. * If no match is found: no update is performed. The action completes silently. {% hint style="info" %} Because the target record's key is taken directly from the Lookup result, the standard correlation key is not used for Lookup Update actions. {% endhint %} ### Lookup Conditions Lookup Conditions define the query that ZigiOps sends to the target system to determine whether a matching record exists. They appear as a dedicated filter section above the field mappings in the action configuration UI. **Key rules:** * Lookup Conditions are mandatory. A Lookup action cannot be saved or activated with an empty condition. * Any query syntax supported by the target system's collection is valid. * Conditions can reference source field values dynamically, allowing the query to adapt to each incoming record. ### Enabling Lookup Update (Advanced Actions) The Lookup Update action type is part of ZigiOps' Advanced Actions feature, which is disabled by default. A platform administrator must enable it in the General Settings before integration builders can select it. #### How to Enable Advanced Actions 1. Log in to ZigiOps with an administrator account. 2. Navigate to **General Settings**. 3. Locate the **Enable Advanced Actions** toggle. 4. Switch the toggle to the enabled state. 5. Save your settings. The Lookup Update and Lookup Create action types will now be available in the Configurator. ### Configuring a Lookup Action Lookup actions are configured within a workflow's action settings in the ZigiOps Configurator. The steps below apply to both Lookup Create and Lookup Update, with differences noted where applicable. #### Prerequisites * An existing ZigiOps workflow with at least one configured action. * The target system's collection must support both query and update operations for Lookup Update. * Advanced Actions must be enabled in General Settings. #### Configuration Steps 1. Open your workflow in the ZigiOps Configurator. 2. Select the action you want to configure as a Lookup action (for example, a Create or Update action). 3. Choose the **Target** tab. 4. In the Action Type selector, choose **Lookup Create** or **Lookup Update**. 5. The Lookup Condition filter section appears above the field mappings table. Configure the condition that ZigiOps will query against the target system. 6. Complete the field mappings as usual. 7. Save the action. The Lookup Condition is validated on save - an empty condition will block saving. ### Use Case Example: Preventing Duplicate Incidents This example shows a common production scenario where Lookup Create and Lookup Update work together to prevent a surge of near-identical source alerts from creating multiple duplicate tickets in an ITSM system. **Scenario** A monitoring tool such as SolarWinds generates multiple alerts for the same node and alert type within a short period. Each alert has a unique internal ID (`AlertHistoryID`), so without Lookup logic, each alert would create a separate incident in ServiceNow, flooding the queue with duplicates. **Solution: Custom Correlation Key + Lookup** Instead of using the unique `AlertHistoryID` as the correlation key, define a composite key that groups related alerts together. For example: ``` correlation_id = {nodename}:{alertid}:{eventtype} Example: solarwinds01:107:0 ``` #### Lookup Create Flow 1. An alert is collected from SolarWinds. 2. ZigiOps queries ServiceNow for any incident where `correlation_id = solarwinds01:107:0` AND `state not in (6, 7)`. 3. If no incident is found: ZigiOps creates a new ServiceNow incident with the composite `correlation_id`. 4. If an incident already exists: ZigiOps skips creation. No duplicate is written. #### Lookup Update Flow 1. A subsequent alert update is collected from SolarWinds. 2. ZigiOps queries ServiceNow using the same Lookup Condition. 3. If a matching incident is found: ZigiOps updates it. The record's key is taken from the Lookup result, not the standard correlation field. 4. If no matching incident is found: no update is performed. #### Lookup Behavior Summary | Lookup Query Result | Lookup Create Behavior | Lookup Update Behavior | | ---------------------- | ------------------------------------------ | ------------------------------------------------- | | No match found | Creates a new record in the target system. | No action. Update is skipped. | | One match found | Skips creation. No duplicate record. | Updates the matched record. | | Multiple matches found | Skips creation. No duplicate record. | Updates the most recently created matched record. | ### Lookup vs. Standard Actions | Feature | Standard Action | Lookup Action | | ----------------------------- | ------------------------- | ------------------------------------------------------ | | Duplicate prevention | Not built in. | Built in via Lookup Condition. | | Target record identification | Uses the correlation key. | Uses the Lookup query result. | | Pre-action target query | No. | Yes - mandatory Lookup Condition. | | Requires enabling in Settings | No. | Lookup Update requires Advanced Actions to be enabled. | | Supports Poller trigger | Yes. | Yes. | | Supports Listener trigger | Yes. | Yes. | ### Related Topics | Topic | Description | | ------------------------------- | ---------------------------------------------------------------------------- | | Data Mapping Fundamentals | Learn how field mappings, conditions, and transformations work in ZigiOps. | | Filters and Conditions | Define which records are collected from the source system. | | Transformations and Expressions | Apply data transformations before delivery to the target system. | | Poller and Listener | Understand the two trigger mechanisms ZigiOps uses to detect source changes. | | Correlation | How ZigiOps links records across systems and uses keys to manage updates. | | General Settings | Platform-level configuration including enabling Advanced Actions. | --- # 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://docs.zigiwave.com/design-and-mappings/lookups.md?ask= ``` 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.