# Listener & Poller Every ZigiOps integration depends on a mechanism for detecting when something has changed in a source system and triggering the appropriate sync action. ZigiOps provides two detection mechanisms: the **Poller** and the **Listener**. Understanding how each works, when to use one over the other, and how they affect the rest of your integration configuration is fundamental to building reliable, production-ready workflows. *** ### What Is a Poller in ZigiOps? A Poller is a scheduled detection mechanism. It queries the source system's API at a defined interval to check for new or updated records that meet the integration's filter criteria. When the Poller finds qualifying records, it passes them to the workflow for processing. The Poller uses a timestamp-based approach to track which records have already been processed. Each polling cycle checks only records that have been created or modified since the last successful run. ZigiOps stores this timestamp (commonly referred to as the `lasttime` value) internally and advances it after each successful cycle. > **Screenshot placeholder:** ZigiOps workflow configuration screen showing the Poller trigger type selected with a polling interval field set to 5 minutes. *Alt text: ZigiOps workflow configuration screen showing the Poller trigger type selected with a polling interval field set to 5 minutes* *Figure: ZigiOps Poller configuration - trigger type set to Poller with a 5-minute interval* ### How Does the Poller Determine What Records to Collect? The Poller combines two sources of information to determine which records to collect in each cycle: * The **`lasttime` value:** the timestamp of the last successful poll. ZigiOps queries the source system for records modified after this point. * The **Filter configuration:** the conditions defined in the Source tab of the Action, which specify which record types, states, or field values qualify for collection. Both conditions must be met for a record to be collected. A record modified after `lasttime` but not matching the filter criteria is excluded. A record matching the filter but not modified since the last cycle is also excluded. ### What Polling Intervals Are Available? The polling interval is configurable per workflow and defines how frequently ZigiOps queries the source system. | Interval Range | Typical Use Case | Considerations | | --------------- | ------------------------------------------------- | --------------------------------------------------------------------------- | | Under 1 minute | Near-real-time alerting integrations | High API call frequency; confirm source system rate limits before enabling | | 1 to 5 minutes | Incident management, change management | Suitable for most ITSM integrations; balances timeliness with API load | | 5 to 15 minutes | Reporting, batch updates, lower-urgency workflows | Reduces API load; acceptable latency for non-critical data flows | | Over 15 minutes | Scheduled data exports, compliance archiving | Use when source system has strict rate limits or data volumes are very high | *** ### What Is a Listener in ZigiOps? A Listener is an event-driven detection mechanism. Instead of querying the source system on a schedule, the Listener receives data from the source system in real time via an inbound webhook or alert notification. When the source system sends a payload to the ZigiOps Listener endpoint, the workflow is triggered immediately. ZigiOps exposes a dedicated Listener URL for each workflow configured to use this trigger type. The source system must be configured to send event payloads to this URL. ZigiOps parses the incoming data and passes it to the workflow for processing. > **Screenshot placeholder:** ZigiOps workflow configuration screen showing the Listener trigger type selected, with the Listener URL displayed and a Document Extract Path field. *Alt text: ZigiOps workflow configuration screen showing the Listener trigger type selected, with the Listener URL displayed and a Document Extract Path field* *Figure: ZigiOps Listener configuration - trigger type set to Listener with the endpoint URL and Document Extract Path* ### What Types of Listeners Does ZigiOps Support? | Listener Type | Description | Typical Use Case | | ------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | Web Listener | Receives JSON payloads from monitoring, DevOps, or automation tools via HTTP POST | Prometheus alerts, PagerDuty notifications, custom webhook sources | | Web Poller | Actively polls a web endpoint (REST API) that does not support outbound webhooks; uses Basic Auth | APIs that expose a data endpoint but cannot push events | | Webhook (Generic) | Receives webhook events from any system that supports outbound HTTP POST with Basic Auth | Custom integrations, internal tooling, third-party APIs | | System-specific Listeners | Pre-built Listener configurations for supported ZigiOps systems (for example, Jira, ServiceNow) | Standard bidirectional sync flows using webhook triggers | ### What Is the Document Extract Path? When the Listener receives an inbound payload, the data of interest may be nested within a JSON structure. The **Document Extract Path** tells ZigiOps where within the payload to find the relevant records. For example, if the JSON payload contains a `records` array under a `parentItem` key, the Document Extract Path would be set to `parentItem/records`. If the Document Extract Path is left empty, ZigiOps treats the entire payload as the record to be processed. *** ### What Is the Difference Between a Poller and a Listener? The fundamental distinction is the direction of the trigger. The Poller reaches out to the source system. The Listener waits for the source system to reach out to ZigiOps. | Aspect | Poller | Listener | | ------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | Trigger direction | ZigiOps queries the source system | Source system sends data to ZigiOps | | Latency | Determined by the polling interval; minimum equal to the interval setting | Near-real-time; triggered immediately on event | | Source system requirement | Source system must expose a queryable API | Source system must support outbound webhooks or HTTP POST | | API load on source | Periodic API calls regardless of activity | No polling load; source system controls when data is sent | | Reliability model | Timestamp-based; ZigiOps controls what is collected | Event-based; source system controls what is sent | | Use when | Source system does not support webhooks; polling latency is acceptable | Real-time response is required; source system supports outbound events | | Bi-directional sync | Supported; configure separate pollers for each direction | Supported; configure a Listener for the inbound direction and an Action for the outbound | *** ### How Do I Choose Between a Poller and a Listener? In most enterprise integrations, the choice is determined by the capabilities of the source system rather than by preference. Use the following decision guide: * Use a **Poller** when the source system does not support outbound webhooks or event notifications. Most ITSM platforms (ServiceNow, BMC Remedy, Jira Server) support polling via their REST APIs. * Use a **Listener** when the source system supports outbound webhooks and real-time event delivery is a requirement. Monitoring tools such as Prometheus, Dynatrace, and PagerDuty are designed to push events rather than be polled. * Use a **Listener** when polling the source system at the required interval would exceed API rate limits or generate excessive load. * Use a **Poller** when the source system's webhook implementation is unreliable or inconsistent, and a guaranteed periodic check is preferred. * In some integrations, both mechanisms are used simultaneously: a Poller handles the primary data flow from a source ITSM system, and a Listener handles real-time alerts from a monitoring tool. *** ### How Does the `lasttime` Mechanism Work in Poller-Based Integrations? The `lasttime` value is a timestamp that ZigiOps stores after each successful polling cycle. It marks the point in time up to which records have been processed. In the next cycle, ZigiOps queries the source system for records modified after this timestamp, ensuring that only new or updated records are collected and that no record is processed twice under normal operating conditions. The `lasttime` value is stored per workflow and is updated only after a successful cycle completes. If a cycle fails (for example, due to a network error or API timeout), the `lasttime` value is not advanced. This means the next successful cycle will reprocess the records from the failed cycle, providing a built-in retry safety net. > **Screenshot placeholder:** ZigiOps workflow logs showing the `lasttime` value being updated after each successful polling cycle. *Alt text: ZigiOps workflow logs showing the lasttime value being updated after each successful polling cycle* *Figure: ZigiOps polling cycle logs - lasttime value shown advancing after each successful run* ### What Happens If the Poller Misses a Cycle? If a polling cycle does not complete (due to a system outage, network interruption, or scheduled maintenance window), ZigiOps retains the previous `lasttime` value. When the Poller resumes, it processes all records modified since the last successful cycle, including any that arrived during the missed window. This means no records are lost due to missed cycles, but the sync may be delayed until the backlog is processed. For very high-volume environments, a missed cycle followed by a large backlog may affect performance. In these cases, consider enabling bulk transfer capabilities or adjusting the polling interval to reduce per-cycle volume. *** ### Can a Workflow Use Both a Poller and a Listener? A single workflow Action uses one trigger type - either a Poller or a Listener. However, a complete integration scenario can combine both mechanisms across different Actions or workflows. A common architecture uses a Poller to detect new records created in System A and sync them to System B, while a separate Listener workflow receives real-time status updates from System B and applies them back to System A. > **Screenshot placeholder:** ZigiOps architecture diagram showing a Poller workflow (ITSM to DevOps direction) and a Listener workflow (monitoring alerts to ITSM direction) operating in parallel. *Alt text: ZigiOps architecture diagram showing a Poller workflow and a Listener workflow operating in parallel* *Figure: Combined Poller and Listener architecture in ZigiOps - Poller handles scheduled sync, Listener handles real-time alerts* *** ### What Are the Best Practices for Configuring Pollers and Listeners? #### Poller Best Practices * Set the polling interval based on actual SLA requirements rather than the shortest available option. Shorter intervals increase API load on the source system. * Always configure a filter in the Source tab to restrict what records are collected. An unfiltered Poller collects all modified records in the system, which quickly becomes unmanageable at scale. * Monitor the `lasttime` value in ZigiOps logs during initial deployment. If cycles are completing faster than the interval, the filter may be too broad. * Use the bulk transfer capability for high-volume polling scenarios where many records may be updated between cycles. #### Listener Best Practices * Validate the inbound payload format before enabling the Listener in production. Use ZigiOps's request logging to inspect what the source system is actually sending. * Set the Document Extract Path precisely. An incorrect path causes ZigiOps to process the wrong data or fail silently. * Confirm that the source system's webhook configuration includes the correct ZigiOps Listener URL and any required authentication headers. * Test inbound delivery with a manual webhook POST before connecting a live source system event. *** ### What Are the Common Issues with Pollers and Listeners? | Issue | What Goes Wrong | How to Fix It | | ------------------------------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Poller collects too many records per cycle | High API load, slow cycle completion, potential rate limit errors | Narrow the filter criteria in the Source tab; increase the polling interval; enable bulk transfer if available | | `lasttime` stuck after an error | Poller retries the same records indefinitely after a persistent API failure | Investigate the root cause of the failure in ZigiOps logs; resolve the connectivity or permission issue; manually advance `lasttime` if needed | | Listener not receiving payloads | Source system sends events but ZigiOps does not process them | Confirm the Listener URL is correctly configured in the source system; verify network connectivity and firewall rules allow outbound HTTP POST to the ZigiOps endpoint | | Duplicate records on missed cycle recovery | Large backlog after an outage causes duplicate processing | Confirm correlation fields are correctly configured so ZigiOps updates existing records rather than creating new ones | | Rate limit exceeded on source system API | Source system returns 429 errors during Poller cycles | Increase the polling interval; reduce the volume of records per cycle with tighter filters; contact the source system administrator to request a rate limit increase | | Payload parsing failure in Listener | ZigiOps receives the payload but cannot extract the expected data | Review and correct the Document Extract Path; inspect the raw payload in ZigiOps logs to confirm the actual JSON structure | *** ### Where Can I Go from Here? With an understanding of how Pollers and Listeners work, the following topics help you build complete and reliable integration workflows: * **Filters and Conditions:** Define which records are collected by the Poller and under what criteria * **Data Mapping Fundamentals:** Configure how collected data is transformed and delivered to the target system * **Attachment and Comment Syncing:** Extend the Poller or Listener workflow to include related objects * **Scaling and Sizing:** Understand how Poller intervals and volumes affect ZigiOps infrastructure requirements * **Best Practices:** End-to-end guidance for designing, testing, and maintaining integrations in production --- # 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/listener-and-poller.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.