# Integrations Best Practices Building integrations in ZigiOps is designed to be straightforward, but the decisions you make during configuration directly affect reliability, data accuracy, and long-term maintainability. Whether you are customizing a pre-built workflow template or building a custom integration from scratch, following a consistent set of guidelines reduces errors, simplifies troubleshooting, and helps your integrations scale as your environment grows. This page covers best practices across every major phase of integration building in ZigiOps: planning, workflow design, field mapping, filtering, transformations, correlation, trigger selection, security, testing, and ongoing operations. **Related pages:** Data Mapping Fundamentals, Filters and Conditions, Transformations and Expressions, Lookups, Poller and Listener, Scaling and Sizing, Troubleshooting. *** ### 1. Where Should I Start Before Opening the Configurator? Planning your integration before touching the ZigiOps UI prevents misconfigurations and reduces rework. Take time to define the following before you begin: * Identify the source and target systems and the direction of data flow (one-way or bi-directional). * Define the entity types involved, for example incidents, tasks, alerts, or change requests. * List the fields that must be mapped and clarify which are mandatory, optional, or conditional on the target system. * Confirm that the API user account on each system has the permissions required to read, create, and update the relevant entities. * Check whether a pre-built workflow template already covers your use case. {% hint style="info" %} Always validate API credentials and permissions before starting configuration. Authentication errors are among the most common causes of integration failures. {% endhint %} *** ### 2. Should I Use a Template or Build from Scratch? In most cases, you should start with a pre-built workflow template. ZigiOps includes templates for the most common enterprise use cases, such as ServiceNow to Jira, Azure DevOps to ServiceNow, and Jira to Salesforce. Templates include pre-configured actions, triggers, and mappings, which means you can be operational in minutes. #### When to Use a Template * Your use case involves a supported system pair covered by an existing template. * You want a working baseline that you can then customize. * You need to go live quickly with minimal configuration effort. #### When to Build from Scratch * Your use case is not covered by any existing template. * You need a highly specific combination of entities, triggers, or conditions that a template cannot accommodate. * You are integrating using the Web Listener, Web Poller, or Webhook. If you start from a template, always inspect all mappings, conditions, and actions before activating the workflow. Not every default mapping will match your environment. Document any changes you make to the template for future reference. *** ### 3. How Should I Structure My Workflows and Actions? A workflow in ZigiOps represents a complete integration use case and contains all the configuration required to achieve it, including connected systems, actions, mappings, filters, and correlation. Keeping workflows well-structured makes them easier to manage and troubleshoot. #### Workflow Design Guidelines * Keep each workflow focused on a single use case and entity pair. For example, one workflow for incident sync and a separate workflow for change request sync. * Use multiple actions within one workflow rather than creating separate workflows for closely related operations. A single workflow can contain Create, Update, and Sync actions. * Use descriptive names for workflows and actions that reflect their purpose and environment. For example: `snow-incident-to-jira-bug [create]` or `jira-prod-to-snow-test [update]`. * Avoid overlapping triggers across workflows that operate on the same entity in the same source system. This can cause duplicate data or conflicting updates. * Separate production and test configurations using distinct system instances with clearly labeled names. *** ### 4. What Are the Best Practices for Field Mapping? Field mapping defines which data is transferred from the source system to the target system. Accurate mappings are the foundation of a reliable integration. #### Field Mapping Guidelines * Map only the fields that your use case requires. Avoid mapping every available field by default, as unnecessary mappings add complexity and can cause validation errors on the target system. * Use **static value mappings** when you want to report custom values to the target that do not exist in the source - usually for a one-time sync of mandatory fields during data creation. * Use **dynamic mappings** for values derived from source fields at runtime. For example: `summary = {short_description}`. * Validate field types on both sides of the mapping before finalizing. Mismatched types - such as mapping a string to an integer or Boolean - are a common source of errors. * Use **respond field mappings** to write confirmation data or drilldown links back to the source system after a target record is created or updated. * Apply **field mapping conditions** when a field should only be populated under specific circumstances, for example when a lifecycle status changes. {% hint style="info" %} If a required field on the target system is missing from the mapping, the API call will fail. Always check the target system's required fields against your mapping table before activating the workflow. {% endhint %} *** ### 5. How Do I Use Filters and Conditions Effectively? Filters control which records are collected from the source system. Applying the right filters ensures that only relevant data flows through the integration and reduces unnecessary API load. #### Filter Guidelines * Apply filters at the source level to limit collected records to those that match your use case. For example, filter by status, project, or priority before fetching records. * Use related filters only when your use case requires synchronizing related entities such as comments or attachments. Avoid enabling related filters by default. * Avoid over-filtering. Filters that are too restrictive can cause records to be silently skipped, which may be difficult to detect without reviewing the Activity Log. * Test your filters in a non-production environment before going live. Verify that the expected records appear and that unrelated records are excluded. * Combine multiple conditions using AND or OR logic to match your use case precisely. Start simple and add conditions incrementally. *** ### 6. When and How Should I Use Transformations and Expressions? Transformations and expressions allow you to modify data between collection and delivery. They are applied after data is collected from the source and before it is sent to the target. #### Transformation Guidelines * Use expressions to normalize data formats before delivery. Common use cases include converting date and time formats, adjusting text casing, and trimming or extracting substrings. * Reuse expressions across multiple field mappings where the same transformation applies to more than one field. This reduces duplication and keeps the configuration consistent. * Keep transformation logic as simple as possible. Chain expressions only when a single expression is not sufficient for the transformation you need. * When using regex-based Pattern expressions, document the pattern and its purpose. Regex patterns can be difficult to interpret without context. * Test transformation output on sample data before activating the workflow. Use the ZigiOps UI to inspect the transformed values. #### Supported Expression Types | Expression | Description | | ------------------------------------------ | ------------------------------------------------------------------- | | **Pattern** | Regex-based extraction or modification. | | **Extract from Array** | Retrieves a specific object from an array field. | | **Build Array** | Combines multiple values into an array. | | **To Lower Case / To Upper Case** | Converts text casing. | | **First N Characters / Last N Characters** | Trims text to a specified length. | | **Replace Text / Replace Pattern** | Substitutes text or regex matches. | | **Date and Time Format** | Converts timestamps to a required HumanDate string format. | | **Last Time** | Tracks the latest timestamp to prevent duplicate record collection. | *** ### 7. How Should I Configure Lookups? 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. #### Lookup Guidelines * **Use Lookups when** you need to query a target system before writing data to it, and you want to control whether a record gets created or updated based on whether a match already exists. Lookups are the primary mechanism for preventing duplicate records across connected systems. * **Use Lookup Create when** you want to create a record in the target system only if an equivalent one does not already exist. If a match is found, ZigiOps skips the action entirely, so no duplicate is written. * **Use Lookup Update when** you need to update an existing target record identified by a query condition rather than the standard correlation key. Note that this action type must be enabled by a platform administrator under General Settings before it becomes available in the Configurator. * **Always define a Lookup Condition** before saving a Lookup action. Empty conditions are not valid and will block the save. * **Keep in mind that** when multiple target records match a Lookup query, ZigiOps always selects the most recently created one. Plan your Lookup Conditions carefully to avoid unintended matches in high-volume environments. *** ### 8. Why Is Correlation Configuration Critical? Correlation is how ZigiOps maintains the link between related records across two systems. It uses a dedicated system field to store a unique key that identifies which record in the source system corresponds to which record in the target system. Without a correctly configured correlation field, bi-directional workflows cannot reliably update existing records and may create duplicates instead. #### Correlation Guidelines * Always configure a correlation field before activating a bi-directional workflow. * Use the field recommended for each system. Common examples include `correlation_id` for ServiceNow, a dedicated custom field for Jira, and `Vendor Ticket Number` for BMC Remedy. * Verify that the correlation field is writable by the API user account. Read-only fields cannot be used for correlation. * Confirm that the correlation field is unique per record on both systems. Shared or reused values will cause incorrect record matching. * Test correlation on a single record before enabling the workflow for bulk data. Verify that the correlation key is written back to both systems after the first sync. {% hint style="info" %} If correlation is not configured correctly, ZigiOps will attempt to create new records on every poll cycle instead of updating existing ones. Always verify correlation behavior in a test environment first. {% endhint %} *** ### 9. Should I Use a Poller or a Listener? ZigiOps supports two trigger mechanisms for detecting changes in source systems: Pollers and Listeners. Choosing the right one depends on your use case, the capabilities of the source system, and your latency requirements. | | Poller | Listener | | --------------------- | ---------------------------- | ----------------------------------------- | | **Trigger type** | Time-based interval | Event-based (real-time) | | **Best for** | Periodic sync, batch updates | Alerts, immediate incident creation | | **Latency** | Depends on poll interval | Near real-time | | **Setup complexity** | Lower | Higher (endpoint configuration required) | | **HA considerations** | Scalable polling supported | High Availability Listener setup required | #### Poller Guidelines * Set polling intervals based on data volume. Short intervals increase API load on the source system. A 1- to 5-minute interval is appropriate for most use cases. * Use the Last Time expression to track the latest timestamp and avoid collecting the same records on every poll cycle. * Monitor the Activity Log for signs of API throttling, which appear as retry spikes or repeated errors. #### Listener Guidelines * Ensure the source system can deliver events to the ZigiOps listener endpoint via HTTP POST. * Configure High Availability for Listener triggers in production environments where uptime is critical. * Validate the incoming data format against the Document Extract Path configuration before going live. *** ### 10. How Do I Handle Authentication and Security? Each system instance in ZigiOps requires authentication credentials. Correct credential management is essential for maintaining secure and uninterrupted integrations. | Auth Method | When to Use | Notes | | ------------------------------- | --------------------------------------------------------- | ------------------------------------------- | | **API Token** | Most ITSM and DevOps systems | Preferred over Basic Auth; rotate regularly | | **OAuth 2.0** | Cloud-based systems (for example, Jira Cloud, Salesforce) | Most secure; use where supported | | **Personal Access Token (PAT)** | Azure DevOps, Jira Cloud | Scoped to user; set minimum permissions | | **Basic Auth** | Legacy or on-premises systems | Use only when no other option is available | | **Bearer Token** | REST APIs with short-lived tokens | Automate refresh if the token expires | #### Authentication and Security Guidelines * Use the minimum required API permissions for each system instance. Do not use administrator accounts unless the integration requires administrator-level operations. * Prefer API tokens or OAuth over Basic authentication where the system supports it. * Rotate credentials on a regular schedule and update the corresponding system instance in ZigiOps immediately after rotation. * Never share credentials across system instances that serve different environments, such as test and production. * For on-premises systems, verify that the ZigiOps agent can reach the system API through the firewall before configuring the system instance. {% hint style="info" %} ZigiOps does not store transferred data in a database. Only a minimal amount of data is retained for troubleshooting purposes for a configurable, limited period. {% endhint %} *** ### 11. How Should I Test My Integration Before Going Live? Testing before production activation prevents data corruption, duplicate records, and missed synchronization events. Follow a structured testing process for every integration. #### Testing Checklist * Test in a non-production environment using test system instances with dedicated test credentials. * Trigger the workflow manually or with a test record and verify that the correct action is executed. * Check the Activity Log after each test run to confirm that the action completed without errors and that the expected fields were populated. * For bi-directional workflows, test both directions: source to target and target back to source. * Verify that correlation keys are written to both records after the first sync. * Test filters by creating records that should be included and records that should be excluded, then confirm the Activity Log reflects the expected behavior. * Test lookup values by passing known source values and verifying the target values in the created record. * Confirm that transformations produce the expected output by inspecting field values in the target system. {% hint style="info" %} Do not activate a workflow in production before completing at least one full end-to-end test. This includes verifying that the created or updated record in the target system contains all expected field values. {% endhint %} *** ### 12. How Do I Keep Integrations Performing Well at Scale? As the volume of data and the number of workflows grow, performance and reliability become more important. ZigiOps is designed to scale, but configuration decisions affect how well it performs under load. #### Performance Guidelines * Set polling intervals appropriate to your data volume. Polling too frequently on high-volume systems increases API load and may cause throttling. * Use Horizontal Scaling to distribute load across multiple ZigiOps instances when you have many concurrent workflows or high data throughput. * Use Vertical Scaling (increasing CPU and memory) for workflows that involve large payloads or complex transformations. * Monitor the Activity Log regularly for retry spikes, errors, and slow action completion times. * Review the [Scaling and Sizing](/installation-and-deployment/scaling-and-sizing.md) recommendations before deploying to a production environment. * For Linux deployments in High Availability mode, configure network storage for runtime files to ensure consistency across instances. *** ### 13. What Naming Conventions and Documentation Habits Should I Follow? Good naming and documentation practices make integrations easier to manage, hand over, and troubleshoot - especially in environments with multiple workflows or multiple administrators. #### Operational Hygiene Guidelines * Use consistent naming patterns for workflows, actions, and system instances across your environment. * Include the environment in the name of every system instance. For example: `jira-production`, `snow-test`. * Add a description to each workflow explaining its purpose, the systems involved, and the team that owns it. * Maintain a change log for production integrations. Record what was changed, when, and why. * Tag or label integrations by team, system, or use case if your ZigiOps deployment serves multiple teams. * Review and audit active workflows periodically to identify any that are no longer needed or that are generating errors. *** ### Related Pages * [Data Mapping Fundamentals](/design-and-mappings/data-mapping-fundamentals.md) * [Filters and Conditions](/design-and-mappings/filters-and-conditions.md) * [Transformations and Expressions](/design-and-mappings/transformations-and-expressions.md) * [Lookups](/design-and-mappings/lookups.md) * [Poller and Listener](/design-and-mappings/listener-and-poller.md) * [Comments and Attachment Sync](/design-and-mappings/attachments-and-comments.md) * [Custom Fields Sync](/design-and-mappings/custom-fields.md) --- # 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/integrations-best-practices.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.