# Custom Fields Enterprise systems rarely operate with only their default field sets. Teams add custom fields to capture organization-specific data: internal classifications, SLA tiers, business unit codes, regulatory tags, or project identifiers. When integrating two systems that both carry custom fields, ZigiOps must be configured to recognize, collect, and deliver those fields as part of the sync. This page explains what custom fields are in the context of ZigiOps integrations, how ZigiOps discovers them, how to map them, and what to watch for when custom fields differ in type, format, or availability between systems. *** ### What Are Custom Fields in Enterprise Integrations? Custom fields are fields added to a system's standard schema by administrators or developers to meet organization-specific requirements. They are distinct from the built-in fields that ship with the product (such as summary, priority, or status) and may not exist in every instance of the same system. Examples of custom fields commonly encountered in ZigiOps integrations include: | System | Custom Field Example | Typical Purpose | | ------------ | ----------------------------------- | --------------------------------------------------------------- | | Jira | `customfield_10200` (Business Unit) | Tag issues to internal business units for reporting | | ServiceNow | `u_sla_tier` (SLA Tier) | Classify incidents by contractual SLA level | | BMC Remedy | `z_vendor_ref` (Vendor Reference) | Store third-party ticket IDs for cross-vendor tracking | | Salesforce | `Regulatory_Flag__c` | Mark records subject to regulatory review | | Azure DevOps | `Custom.ReleaseTarget` | Indicate the target release for a work item | | Zendesk | `ticket_field_360001234567` | Capture customer-specific data not available in standard fields | Custom fields are defined at the instance level, which means the same product (for example, Jira) may have completely different custom fields across different customer environments. ZigiOps handles this by discovering the schema of each connected system at configuration time rather than relying on a fixed built-in field list. *** ### How Does ZigiOps Discover Custom Fields? When you add a connected system in ZigiOps and configure an Action, ZigiOps queries the source system's API schema endpoint to retrieve the full list of available fields, including custom ones. This discovery process populates the field selectors in the **Field Map** tab with the actual fields available in your specific instance. > **Screenshot placeholder:** ZigiOps Field Map tab showing a mix of standard and custom fields in the source field selector dropdown. *Alt text: ZigiOps Field Map tab showing a mix of standard and custom fields in the source field selector dropdown* *Figure: Field Map tab in ZigiOps showing custom fields alongside standard fields* Custom fields are included in the selector alongside standard fields. In systems such as Jira, custom fields appear with their internal API identifier (for example, `customfield_10200`) alongside their display label. In ServiceNow, custom fields typically carry the `u_` prefix. ZigiOps displays both the API name and the display label where the system's API provides both. If a custom field is not visible in the selector after connecting a system, the most common causes are: * The field is not exposed through the system's public API (some custom fields are UI-only) * The integration user does not have read permission for that field * The field was added after the connected system schema was last refreshed in ZigiOps To refresh the field list, reconnect the system or trigger a schema reload from the **Connected Systems** settings in ZigiOps. *** ### How Do I Map Custom Fields in ZigiOps? Custom fields are mapped using the same **Field Map** interface as standard fields. There is no separate configuration mode for custom fields - they appear in the same source and target field selectors and support all the same mapping types: direct, static, combined, conditional, and respond. 1. Open the workflow Action where the custom field should be synced. 2. Navigate to the **Field Map** tab. 3. In the **Target Field** column, locate the custom field in the target system. Use the field's API name if the display name is ambiguous. 4. In the **Source Value** column, select the corresponding custom field from the source system, or configure a static or combined value if there is no direct equivalent. 5. If the custom field uses a controlled vocabulary (such as a dropdown or multi-select), add conditional mapping rules to translate the values between systems. 6. Save and test the Action using a record that contains a known custom field value. > **Screenshot placeholder:** ZigiOps Field Map tab showing a custom field from ServiceNow (`u_sla_tier`) mapped to a Jira custom field (`customfield_10200`). *Alt text: ZigiOps Field Map tab showing a custom field from ServiceNow mapped to a Jira custom field* *Figure: Custom field mapping in ZigiOps - ServiceNow SLA Tier field mapped to a Jira custom field* *** ### What Custom Field Data Types Does ZigiOps Support? Custom fields in enterprise systems can store many different types of data. ZigiOps handles the most common types encountered in production integrations. | Data Type | Examples | Mapping Approach | | ------------------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Text (single-line) | Reference numbers, external IDs, free text labels | Direct field mapping; no transformation required if character sets are compatible | | Text (multi-line) | Description overflows, notes, long-form content | Direct mapping; verify target field character limit to avoid truncation | | Dropdown (single select) | SLA tier, business unit, region | Conditional mapping required if source and target use different option values or labels | | Multi-select | Tags, product lines, affected teams | Conditional mapping; confirm target system accepts multi-value input in the expected format | | Date and datetime | Target resolution date, review deadline | Use transformation expressions to normalize date formats before delivery if systems use different date formats | | Numeric | Story points, effort hours, cost codes | Direct mapping if numeric formats match; apply transformation if decimal separator differs | | Boolean (checkbox) | Regulatory flag, escalation indicator | Direct mapping; confirm target system uses the same true/false encoding (true/false vs 1/0 vs Yes/No) | | User or group reference | Assigned reviewer, owning team | Lookup required to resolve the user or group ID in the target system before mapping | *** ### What Is the Difference Between Syncing a Custom Field and a Standard Field? From ZigiOps's perspective, the mapping mechanics are identical. A custom field is mapped the same way as a standard field. The practical differences arise outside the mapping configuration: * **Availability:** Custom fields exist only in specific system instances. A field visible in your staging environment may not exist in production if it was added by a different administrator. * **API exposure:** Not all custom fields are available through the system API. Some are UI-only and cannot be read or written programmatically. * **Permission scope:** Integration users may not automatically receive access to custom fields. Access must be granted explicitly by the system administrator. * **Schema drift risk:** Custom fields are more frequently renamed, removed, or restructured than standard fields. Integrations that rely on custom fields require more frequent schema audits. *** ### How Do I Handle Custom Fields That Only Exist in One System? It is common for a custom field to exist in the source system but have no direct equivalent in the target system. ZigiOps provides several approaches depending on the requirement: | Scenario | Recommended Approach | | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Target system has a suitable custom field | Map directly using the Field Map. Use conditional mapping if value formats differ. | | Target system has no matching field but the value must be preserved | Use combined value mapping to embed the custom field value in a text field such as the description or a comment body. | | The field is required in the target but has no source equivalent | Use static value mapping to supply a default that satisfies the target system validation. | | The field should be carried back to the source after action completion | Use respond field mapping to write the target system value back to the source after the action completes. | *** ### What Are the Most Common Issues with Custom Field Syncing? | Issue | What Goes Wrong | How to Fix It | | ------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Field not visible in the selector | Custom field is missing from the source or target dropdown | Confirm API exposure and integration user permissions; refresh the system schema in ZigiOps | | Value rejected by target system | Target system returns a validation error for the custom field value | Confirm the accepted value format; use conditional or transformation mapping to normalize the value | | Schema drift after system upgrade | A renamed or restructured custom field silently breaks the mapping | Audit field mappings after every system upgrade; set up monitoring alerts for sync errors | | Multi-select values not delivered correctly | Multi-value field arrives as a concatenated string instead of an array | Confirm the target system's expected input format; apply a transformation expression if format conversion is needed | | User reference field mismatch | User ID from the source system does not resolve to a valid user in the target | Use a lookup to find the matching user in the target system based on a shared attribute such as email address | | Date format mismatch | Date field is rejected because source and target use different date formats | Apply a date format transformation expression before mapping to normalize to the target system format | *** ### Where Can I Go from Here? Custom field syncing is one component of a complete integration mapping strategy. The following topics provide additional guidance: * **Data Mapping Fundamentals:** Core concepts for all field mapping types in ZigiOps * **Transformations and Expressions:** Apply format conversions and data normalization before delivery * **Lookups:** Resolve cross-system references such as user IDs and group names * **Filters and Conditions:** Control which records are collected and which fields are evaluated * **Best Practices:** End-to-end guidance for designing and maintaining reliable 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/custom-fields.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.