# Data Mapping Fundamentals Data mapping is the foundation of every integration built in ZigiOps. It defines exactly how data moves from one system to another: which fields are read, how values are transformed, and what is ultimately written to the target system. Getting mapping right determines whether an integration becomes a reliable operational bridge or a source of silent data errors. This page covers the core mapping concepts used throughout ZigiOps, the types of mapping available, common pitfalls, and the best practices that keep integrations stable as systems evolve. ### What is field mapping in ZigiOps? Field mapping is the configuration that tells ZigiOps what data to deliver to the target system and how. Every Action in a workflow contains a Field Map tab where you specify: * which fields in the target system should be created or updated * what values should be placed in those fields * where those values come from (source fields, static strings, or combinations)
Mpping panel in ZigiOps
Field mapping works alongside the Source tab, which controls data collection (what records to extract and under what conditions). The Field Map controls data delivery. Together, they cover the full Extract-Transform-Load (ETL) cycle that underlies every ZigiOps integration. ### What types of field mapping does ZigiOps support? ZigiOps supports five mapping types, each suited to different scenarios. The table below summarizes all types with examples. | Mapping Type | Description | Example | | ------------------------- | ------------------------------------------------------------------------- | ---------------------------------------- | | Direct Field Mapping | Copies a value from a source field into a target field as-is | summary = {short\_description} | | Static (Hard-coded) Value | Assigns a fixed value to a target field, regardless of source content | priority = 3 | | Combined Value | Builds a target field value from multiple source fields and fixed strings | summary = {number}: {short\_description} | | Conditional Mapping | Applies rules to translate values based on context or conditions | If state = 2, send 'In Progress' to Jira | | Respond Field Mapping | Maps data from the target system back to the source after an action | Send created issue URL back as a comment | #### Direct field mapping The most common type. A source field is mapped directly to a target field. For example, the Jira Summary field is mapped to the ServiceNow Short Description field. Whatever value exists in Summary at the time of sync is written to Short Description. Example: short\_description = {summary} #### Static (hard-coded) value mapping A fixed value is assigned to a target field regardless of what the source system contains. This is commonly used for required target fields that have no equivalent in the source system. A typical case is integrating Jira with BMC Remedy. Remedy has mandatory fields such as First Name and Last Name that do not exist in Jira. ZigiOps allows you to define static values for those fields so that the record is accepted by Remedy without failing validation. Example: first\_name = "Integration" (static value covering a required Remedy field) #### Combined value mapping A target field is built by combining one or more source fields with fixed strings. This is useful when the target system expects a formatted value that does not exist as a single field in the source. A common use case is constructing a full URL for a Jira ticket and sending it as a comment in ServiceNow or Remedy. The URL is formed from three parts: the Jira base URL (taken from the system instance configuration), a hard-coded path segment (/browse/), and the Jira ticket key (a dynamic field value). Example: comment = {jira\_base\_url}/browse/{issue\_key} #### Conditional mapping Conditional mapping adds context-aware rules to a field. Instead of sending a value directly, ZigiOps evaluates one or more conditions first and translates the value accordingly. This is essential when the two systems represent the same concept differently. The most common scenario is status synchronization. ServiceNow represents states as numeric values (1, 2, 3...) while Jira uses named statuses (To Do, In Progress, Done). Without conditional mapping, ZigiOps would send the raw numeric state to Jira, which would reject or ignore it. Conditional mapping solves this by defining translation rules at the field level. See the dedicated section below for a full explanation of conditional mapping. #### Respond field mapping Respond field mapping runs in the reverse direction: it maps data from the target system back to the source after an action completes. The most common use case is creating a confirmation comment in the source system that includes a drilldown link to the newly created record in the target system. Example: After creating a ServiceNow incident from a Jira task, use respond mapping to post the ServiceNow incident URL as a comment on the Jira task. ### What is the difference between simple and conditional mapping? Simple mapping assigns one value to one field. The value can be a source field, a static string, or a combination, but the assignment does not change based on context. Simple mapping works well for fields that carry stable, compatible values between systems. Conditional mapping adds a layer of logic. For a given field, ZigiOps evaluates a condition and applies a different value depending on the result. This allows a single mapping rule to handle multiple scenarios, such as translating all possible status values between two systems. When to use simple mapping: the source and target fields carry the same meaning and compatible values (for example, a description field, a ticket title, or a reference number). When to use conditional mapping: the systems represent the same concept with different values, formats, or data types (for example, statuses, priorities, issue types, or any enumerated field). ### What is conditional mapping and when is it required? Conditional mapping is the mechanism that allows ZigiOps to translate meaning instead of simply copying values. It applies explicit, auditable rules at the field level that determine if and how a value is transformed before it reaches the target system. Conditional mapping is required in the following situations: * Status and state synchronization between systems that use different value formats (numeric vs. named) * Priority alignment between systems that calculate or represent priority differently * Issue type or record type translation (for example, Jira Bug does not automatically equal a ServiceNow Incident) * Assignment routing when one system uses individuals and the other uses groups or queues * Mandatory field population when the target system requires fields the source does not provide * Filtering internal records that should not cross system boundaries * Preventing synchronization loops in bi-directional flows Without conditional mapping, integrations that encounter mismatched values will either silently drop the update, overwrite with incorrect data, or fail outright. In production environments where governance and SLAs are involved, these failures are not always visible until significant damage has occurred. ### How does conditional mapping work in ZigiOps? Conditions in ZigiOps are configured at the individual field level within the Field Map tab. For any field in the mapping, you can open the Condition option and define one or more rules. Each rule specifies: * a condition expression (for example, "if {state} equals 2") * the value to send when that condition is true (for example, "In Progress") ZigiOps evaluates the conditions at runtime, during each polling or listener cycle. When the condition is matched, the defined value is sent. If no condition is matched, the field can be left empty or set to a default value. Conditions are visible in the UI, auditable, and can be updated without modifying code or redeploying the integration. This makes them significantly easier to maintain than script-based conditional logic used in generic iPaaS platforms. #### Status mapping example: ServiceNow to Jira The table below shows a practical status mapping between a ServiceNow incident and a Jira task. ServiceNow sends numeric state values through its API. Jira expects named status values that match its workflow transitions. Without conditional mapping, the integration would pass numeric values to Jira, which would reject them. --- # 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/data-mapping-fundamentals.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.