# Filters & Conditions Filters and conditions are the primary mechanisms in ZigiOps that determine which records are collected from a source system, when actions are executed, and how field values are assigned based on runtime data. Configuring them correctly is essential for keeping integrations precise, performant, and safe to run in production environments. This page explains how each type of filter and condition works, where it is configured in the ZigiOps UI, how to combine them effectively, and the most common mistakes to avoid. ### What Is the Difference Between Filters and Conditions in ZigiOps? The terms filter and condition serve related but distinct purposes in ZigiOps: * A **filter** controls which records are retrieved from the source system. It is applied before any action logic runs and determines the input to the workflow. * A **condition** controls whether an action executes for a given record, or how a specific field is populated during mapping. Conditions are evaluated at runtime, after records have already been retrieved. ZigiOps supports four types of filters and conditions. The table below summarizes each type, where it is configured, and what it controls. | Filter Type | Where It Is Configured | What It Controls | | ----------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Source Filter | Source tab > Filter field | Defines the query or condition used to fetch records from the source system. Only records that match the filter are retrieved. | | Related Filter | Source tab > Related Filter field | Fetches related records tied to the primary record, such as comments, attachments, or child items. | | Field Mapping Condition | Field Map tab > individual field | Controls whether a specific field is sent to the target system and what value is assigned, based on runtime data. | | Action Condition | Action tab > Condition section | Determines whether the entire action should execute. If the condition is not met, the action is skipped for that record. | ### What Is a Source Filter and How Does It Work? The source filter is the query ZigiOps sends to the source system API to retrieve records. It determines the full set of records that the workflow processes in each polling cycle or listener event. Every workflow should have a source filter configured. Without one, ZigiOps retrieves all records of the specified entity type, which creates unnecessary load on both ZigiOps and the source system. Source filters are configured in the **Source tab** of an action, inside the **Filter** field. The syntax depends on the source system. For example: * In ServiceNow: `state=1^priority=2` * In Jira (JQL): `project = OPS AND status != Done` * In monitoring tools such as Dynatrace or SolarWinds, filters may reference event severity, entity type, or status codes specific to that platform. > **Figure 1:** Source tab with a filter scoping retrieval to updated ServiceNow incidents using the `lasttime` expression. #### Using `lasttime` in Source Filters For polled integrations, the source filter should include the `lasttime` expression to ensure only new or recently updated records are retrieved on each cycle. Without it, the poller fetches the entire record set on every run, which increases latency and creates a risk of re-processing records that have already been synced. **Example `lasttime` filter for ServiceNow:** ``` sys_updated_on>javascript:gs.dateGenerate('{lasttime}') ``` ZigiOps updates the `lasttime` value automatically after each successful poll, recording the timestamp of the latest processed record. ### What Is a Related Filter and When Is It Required? A related filter is a secondary filter that retrieves records linked to the primary record. The most common use cases are: * Syncing comments or work notes attached to an incident or task * Syncing file attachments associated with a record * Retrieving child records or sub-tasks linked to a parent Related filters are configured in the **Related Filter** section of the Source tab. They run after the primary source filter has identified the parent record and use that record identifier to scope the related query. {% hint style="warning" %} If comment or attachment sync is not working, the most frequent cause is a missing or incorrectly scoped related filter. The related filter must reference the correct parent field identifier used by the source system API. {% endhint %} > **Figure 2:** Related Filter section in the Source tab configured to sync comments from the parent record. ### What Is a Field Mapping Condition and How Does It Work? A field mapping condition is a rule applied at the individual field level within the **Field Map** tab. It tells ZigiOps to send a specific value to the target field only when a defined condition is true. Field mapping conditions are used in two ways: * **Value translation:** The source system sends one representation of a value (such as a numeric state code), and ZigiOps translates it to the equivalent value expected by the target system (such as a named status string). * **Conditional delivery:** The field is only populated in the target system when certain criteria are met. If no condition matches, the field can be left empty or assigned a default value. Each condition rule within a field mapping specifies: * A condition expression evaluated against source data, for example: `if {state} equals 2` * The value to send when that expression is true, for example: `In Progress` Multiple condition rules can be stacked for a single field, covering all possible source values. ZigiOps evaluates them in order and applies the first matching rule. > **Figure 3:** Field Map tab with stacked condition rules for translating ServiceNow state values to Jira workflow statuses. #### Example: ServiceNow State to Jira Status Mapping ServiceNow represents incident state as a numeric value in its API. Jira uses named workflow statuses. Without a field mapping condition, the numeric value would be sent directly to Jira, which would either fail validation or store a meaningless value. | ServiceNow State Value | Condition Rule | Jira Status Sent | | ---------------------- | --------------------- | ---------------- | | 1 | `if {state} equals 1` | To Do | | 2 | `if {state} equals 2` | In Progress | | 3 | `if {state} equals 3` | On Hold | | 6 | `if {state} equals 6` | Done | | 7 | `if {state} equals 7` | Cancelled | ### What Is an Action Condition and When Should It Be Used? An action condition is a logical gate that determines whether an entire action runs for a given record. It is evaluated after the record has been retrieved but before the action logic executes. If the condition is not met, the record is skipped and no data is sent to the target system. Action conditions are configured in the **Condition** section of an action. They support logical AND and OR operators and can reference any field available in the source record. | Scenario | Action Condition | Result | | --------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------- | | Only create Jira tasks from ServiceNow incidents with priority 1 or 2 | `priority equals 1 OR priority equals 2` | Records with other priorities are skipped entirely. | | Sync only open or in-progress records | `state not equals 6 AND state not equals 7` | Closed and cancelled records do not trigger an update. | | Avoid creating duplicate records across systems | `correlation_id is empty` | The create action runs only when no correlation exists yet. | | Prevent internal comments from crossing system boundaries | `is_public equals true` | Only customer-visible comments are synced. | > **Figure 4:** Action Condition configured with AND logic to prevent duplicate record creation in bi-directional workflows. Action conditions are especially important in bi-directional integrations, where both systems can originate updates. Incorrectly scoped conditions are a common cause of synchronization loops and duplicate record creation. ### What Filter and Condition Operators Does ZigiOps Support? | Operator | Meaning | Example | | ------------------ | ------------------------------------ | --------------------------------------- | | `equals` | Exact match | `state equals 1` | | `not equals` | Excludes the specified value | `state not equals 6` | | `contains` | Partial string match | `short_description contains timeout` | | `does not contain` | Excludes records with that substring | `description does not contain internal` | | `is empty` | Field has no value | `assigned_to is empty` | | `is not empty` | Field has a value | `priority is not empty` | | `greater than` | Numeric or date comparison | `created_on greater than {lasttime}` | | `less than` | Numeric or date comparison | `severity less than 3` | > **Figure 5:** Condition Builder UI with the operator dropdown expanded, showing all available filter operators. ### How Do I Combine Multiple Conditions? ZigiOps supports both AND and OR logic for combining multiple conditions within a single action condition or field mapping condition. * **AND logic:** All conditions in the set must be true for the rule to apply. Use AND when you need to narrow scope, for example: `priority equals 1 AND state not equals 6`. * **OR logic:** At least one condition in the set must be true. Use OR when multiple values should produce the same outcome, for example: `state equals 1 OR state equals 2`. AND and OR can be combined within the same condition set. When mixing both, group related conditions carefully to ensure the logic evaluates as intended. ZigiOps evaluates conditions left to right within each logical group. ### What Are the Most Common Filter and Condition Pitfalls? | Pitfall | What Goes Wrong | Recommended Fix | | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | No source filter configured | ZigiOps retrieves all records of that type, causing unnecessary processing and possible duplication | Always define a filter that scopes the query to relevant records | | Filter references a field name that changed in the system | The filter returns no results or throws an API error | Audit filters after any system upgrade that modifies field names | | `lasttime` filter not configured for pollers | Every polling cycle retrieves the full record set instead of only new or updated records | Use the `lasttime` expression as part of the source filter for all polled integrations | | Action condition too broad | Records that should be excluded continue to trigger the action | Use AND logic to combine multiple conditions and narrow the scope precisely | | Field mapping condition with unmatched value | The field is silently left empty in the target system | Add a default fallback condition or use `is not empty` to guard against unmapped values | | Related filter missing for comment sync | Comments and work notes are not synced even though the parent record is | Configure the related filter explicitly in the Related Filter section of the action | ### How Do Filters and Conditions Relate to Data Mapping? Filters and conditions work alongside field mapping but serve a different purpose. Field mapping defines what data is sent and how it is formatted. Filters and conditions define when data is collected and when actions are triggered. The interaction between them matters in practice: * A source filter scopes the records that enter the mapping pipeline. If the filter is too broad, mapping logic runs against records it should not touch. If it is too narrow, valid records are excluded. * A field mapping condition can reference any source field, including fields that are not part of the field mapping itself. This allows conditions to use metadata fields (such as record type or category) as decision criteria without including those fields in the sync payload. * An action condition can use the same fields referenced in the field mapping. If a field value is expected in both the condition and the mapping, ensure the field is available in the source record at the time the action runs. For a complete reference on field mapping types and best practices, see the Data Mapping Fundamentals page. ### Best Practices for Configuring Filters and Conditions #### Always Scope Source Filters to Avoid Full Record Retrieval Define a source filter for every workflow. At minimum, include a state or status filter that excludes closed or inactive records. For pollers, always combine the status filter with the `lasttime` expression to retrieve only records modified since the last cycle. #### Test Filters in the Source System Before Configuring Them in ZigiOps Before adding a filter to a workflow, run the equivalent query directly against the source system API or UI. Confirm that the results match the intended scope. This prevents the common issue of filters that are syntactically valid but return an unexpected record set. #### Use Action Conditions to Prevent Synchronization Loops In bi-directional workflows, add an action condition that checks whether the record was last modified by the integration user. If the last update was made by ZigiOps, skip the action to prevent the record from bouncing back and forth between systems indefinitely. #### Use Field Mapping Conditions for All Enumerated Fields Any field that carries a controlled vocabulary - such as status, priority, issue type, or category - should use a field mapping condition. Do not assume that field names or values match across systems. Even when both systems use the word "High" for a priority level, the internal representation may differ. #### Audit Filters and Conditions After System Updates Enterprise systems change over time. Field names are renamed, new states are added, and workflows are restructured. After any system upgrade or configuration change, review all filters and conditions that reference that system to confirm they remain accurate. ### Where Can I Go from Here? Once you understand how filters and conditions work in ZigiOps, the following topics provide the next layer of configuration depth: * **Data Mapping Fundamentals:** Understand field mapping types, conditional value translation, and how mapping interacts with filters * **Transformations and Expressions:** Apply data transformations after collection and before delivery to the target system * **Lookups:** Retrieve related values from the target system based on source field content * **Poller and Listener:** Configure the timing and trigger mechanism that determines when ZigiOps collects data * **Attachment and Comment Syncing:** Configure related filters for binary and text-based related data * **Best Practices:** End-to-end guidance for designing, testing, and maintaining stable integrations --- # 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/filters-and-conditions.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.