Transformations & Expressions
This page covers expressions in ZigiOps, when to use them, how each expression type works.
Transformations and expressions in ZigiOps allow you to modify, reformat, and restructure field data after it is collected from the source system and before it is delivered to the target system. Where field mapping defines what data moves and where it goes, transformations define how that data is shaped in transit.
This page covers what expressions are, when to use them, how each expression type works, and how to combine them with field mappings for reliable integrations.
What Are Expressions in ZigiOps?
An expression is a reusable data transformation rule that you configure in ZigiOps and apply inside field mappings. Expressions operate on the collected source field value and produce a modified output that is delivered to the target field.
Expressions are configured separately from field mappings and referenced within them. A single expression can be reused across multiple field mappings within the same workflow, reducing duplication and making updates easier to manage.
Expressions run at runtime, during each polling or listener cycle, after data collection and before delivery. They do not modify data in the source system.
When Should I Use Expressions Instead of Direct Field Mapping?
Direct field mapping is sufficient when the source value can be written to the target field without modification. Use expressions when:
The source and target systems use different formats for the same type of data (for example, date formats or text casing)
You need to extract a specific part of a larger field value (for example, pulling a ticket number from a structured string)
The target system requires a specific length or structure that the source does not enforce
You need to combine, split, or restructure a value before delivery
You want to remove or replace specific characters or patterns from a value
What Expression Types Does ZigiOps Support?
ZigiOps supports twelve expression types, grouped into text operations, array operations, pattern-based operations, and date-time formatting.
Screenshot placeholder: ZigiOps expression type selector showing all available transformation options in the Expressions tab. Alt text: ZigiOps expression type selector showing all available transformation options in the Expressions tab Figure 1: The ZigiOps Expressions tab with the expression type dropdown expanded, showing all available transformation types.
Pattern
Extracts or modifies data using a regular expression (regex)
Extract a ticket number from a string such as "INC0012345 - Server Down"
Extract from Array
Retrieves a specific object from an array value
Pull the first element from a multi-value field returned by the source API
Build Array
Combines multiple values into a single array using a separator
Merge tag values from two source fields into one structured array
To Lower Case
Converts all characters in the value to lowercase
Normalize email addresses or usernames before delivery
To Upper Case
Converts all characters in the value to uppercase
Format status codes or identifiers to match target system conventions
First N Characters
Trims the value to the first N characters
Truncate a long description to fit a target field with a character limit
Last N Characters
Returns only the last N characters of the value
Extract a suffix or reference code from the end of a structured value
Replace Text
Replaces a specified string with another string
Remove a prefix from a field value before writing to the target
Replace Pattern
Replaces text that matches a regex pattern with another string
Strip HTML tags or special characters from a description field
Date and Time Format
Converts a timestamp into a specified human-readable format
Reformat a Unix timestamp to DD/MM/YYYY HH:MM for a ServiceNow date field
Last Time
Records the most recent timestamp of collected data to prevent re-processing duplicates
Ensure the poller only retrieves records updated after the last successful run
Prefix / Suffix Add
Prepends or appends a fixed string to the field value
Add a system identifier prefix to all outbound comment values
How Do I Create and Apply an Expression?
Expressions are configured in the Expressions section of a workflow action. Once created, they are referenced inside field mappings using the expression name.
Open the Expressions Section
Navigate to the workflow action where you want to apply the transformation. Select the Expressions tab within the action configuration panel.
Screenshot placeholder: ZigiOps action configuration panel with the Expressions tab selected, showing the Add Expression button. Alt text: ZigiOps action configuration panel with the Expressions tab selected, showing the Add Expression button Figure 2: The Expressions tab inside a ZigiOps workflow action, where new expressions are created and existing ones are managed.
Add a New Expression
Click Add Expression.
Enter a unique name for the expression.
Select the expression type from the dropdown.
Configure the expression parameters based on the type selected (for example, the regex pattern for a Pattern expression, or the format string for a Date and Time Format expression).
Screenshot placeholder: ZigiOps Add Expression dialog with the expression name field, type dropdown, and parameter input fields visible. Alt text: ZigiOps Add Expression dialog with the expression name field, type dropdown, and parameter input fields visible Figure 3: The Add Expression dialog in ZigiOps. The name, type, and configuration fields vary based on the expression type selected.
Reference the Expression in a Field Mapping
In the Field Map tab, locate the target field where you want to apply the transformation. In the value input for that field, reference the expression by its name using the curly-brace syntax: {expression_name}. The expression output replaces the raw source field value at runtime.
Screenshot placeholder: ZigiOps Field Map tab showing a target field value referencing an expression name inside curly braces. Alt text: ZigiOps Field Map tab showing a target field value referencing an expression name inside curly braces Figure 4: A field mapping referencing a configured expression. The expression name in curly braces is replaced with the transformed value at runtime.
Expression Type Reference
Pattern
The Pattern expression uses a regular expression to extract or validate part of a field value. This is useful when the source field contains structured text from which only a portion is needed.
Example: Source value: "INC0012345 - Server Down". Pattern: INC\d+. Output: "INC0012345".
Pattern expressions follow standard regex syntax. If the pattern does not match, the expression returns an empty string.
Extract from Array
When a source field returns an array of values, the Extract from Array expression retrieves a specific element by its index position. Index counting starts at 0.
Example: Source value: ["tag1", "tag2", "tag3"]. Index: 1. Output: "tag2".
Use this expression when the source system API returns multi-value fields as arrays and the target field expects a single value.
Build Array
The Build Array expression combines multiple source field values or static strings into a single array, using a specified separator. The result is a structured array that can be written to a target field that accepts array input.
Example: Values: {tag_field}, "static-tag". Separator: ,. Output: ["tag_field_value", "static-tag"].
To Lower Case and To Upper Case
These expressions convert the entire value of a source field to lowercase or uppercase. They are commonly used to normalize identifiers, email addresses, status codes, or category values before delivery to systems that enforce case-sensitive matching.
Example (To Lower Case): Source: "CRITICAL". Output: "critical".
Example (To Upper Case): Source: "in progress". Output: "IN PROGRESS".
First N Characters and Last N Characters
These expressions trim a field value to a defined number of characters, counted from either the beginning or end of the string. They are most commonly used to enforce field length constraints when the source field can contain values longer than the target system accepts.
Example (First N Characters): Source: "This is a very long incident summary that exceeds the limit". N: 50. Output: "This is a very long incident summary that exceeds".
Always account for word boundaries if the truncated output will be read by users. Truncating mid-word may reduce readability.
Replace Text
The Replace Text expression substitutes a specific string within the field value with a different string. The replacement applies to the first occurrence by default.
Example: Source: "JIRA-1234: Login failure". Replace "JIRA-1234: " with "". Output: "Login failure".
Use Replace Text for simple, known string substitutions. For pattern-based replacements across variable content, use Replace Pattern instead.
Replace Pattern
The Replace Pattern expression uses a regular expression to find and replace matched content within a field value. This is more flexible than Replace Text because it matches variable content based on a pattern rather than a fixed string.
Example: Source: "<b>Server Down</b>". Pattern: <[^>]+>. Replacement: "". Output: "Server Down".
Replace Pattern is commonly used to strip HTML or markup tags from description fields before writing them to plain-text target fields.
Date and Time Format
The Date and Time Format expression converts a timestamp value from the source system into a human-readable format compatible with the target system. Source systems often return timestamps as Unix epoch integers or ISO 8601 strings. Target systems may require specific regional date formats.
Example: Source: "1700000000" (Unix timestamp). Format: DD/MM/YYYY HH:mm. Output: "14/11/2023 22:13".
Configure the output format string using standard date-time format tokens (for example, YYYY for four-digit year, MM for two-digit month, DD for two-digit day). Verify the format string against the target system documentation to ensure the output is accepted without validation errors.
Last Time
The Last Time expression records the most recent timestamp of the data collected during the last successful polling cycle. On the next cycle, ZigiOps uses this stored timestamp to filter out records already processed, ensuring only new or updated records are retrieved.
Last Time is used in the Source configuration of an action, not in the Field Map tab. It prevents duplicate record processing in high-volume or long-running integrations and is particularly important in scheduled batch sync scenarios.
Last Time is a Source-level expression and is not applied to individual field values. Configure it in the Source filters section of the action.
Can Expressions Be Combined or Chained?
ZigiOps does not currently support native expression chaining, where the output of one expression feeds directly into the input of another. However, you can achieve multi-step transformations by applying a combined value mapping that references both an expression and additional static or dynamic content.
If a transformation requires sequential operations (for example, extract a substring and then convert it to uppercase), the recommended approach is to simplify the regex or format pattern to produce the correct output in a single expression where possible, or to split the logic across two separate field mappings that write to intermediate fields.
If your use case requires complex multi-step transformations that cannot be handled with the available expression types, contact ZigiWave support to discuss custom transformation options.
Common Transformation Scenarios
Source date is Unix timestamp; target requires DD/MM/YYYY
Date and Time Format
Set format string to DD/MM/YYYY. Verify the source field value is a valid Unix timestamp integer.
Description field exceeds target character limit
First N Characters
Set N to the maximum character count the target field accepts. Add a note in documentation that truncation is applied.
Source field contains HTML markup; target is plain text
Replace Pattern
Use the pattern <[^>]+> with an empty string as replacement to strip all HTML tags.
Status field returns numeric value; target requires uppercase text
To Upper Case (combined with conditional mapping)
Apply conditional mapping first to convert the numeric value to a named status string, then apply To Upper Case if the target enforces uppercase values.
Source array field; target requires single string value
Extract from Array
Confirm the array index of the required value with the source system API documentation.
Need to add a system prefix to all outbound comments
Replace Text or Prefix / Suffix Add
Use Prefix / Suffix Add to prepend the prefix, or use Combined Value mapping with a static prefix string before the expression reference.
Prevent duplicate record processing in a high-volume poller
Last Time
Configure Last Time in the Source filters section. Set the timestamp field to the source system modification date field.
Troubleshooting Expression Errors
Expression errors appear in the ZigiOps Activity Log and Error Log.
Empty output from Pattern expression
The regex pattern does not match the source field value
Test the pattern against a sample value using an external regex tester. Check for special characters in the source value that may need escaping.
Date and Time Format produces incorrect output
The source timestamp format does not match the expected input type (Unix integer vs. ISO string)
Verify the source field type in the system API documentation. Adjust the format string or pre-process the value with a Replace Pattern expression first.
First N Characters cuts mid-word
The N value is set to a character count that lands inside a word
Increase or decrease N to the nearest word boundary, or review whether the truncation behavior is acceptable for the target audience.
Replace Pattern removes unintended content
The regex pattern is too broad and matches content outside the intended range
Narrow the pattern by anchoring it more specifically. Test against multiple representative source values before deploying.
Expression not applied at runtime
The expression name in the field mapping is misspelled or uses incorrect casing
Verify the expression name matches exactly as configured in the Expressions tab. Expression names are case-sensitive.
Best Practices for Transformations and Expressions
Name Expressions Clearly and Consistently
Use names that describe what the expression does and which field it applies to. For example, date_format_created_on or truncate_summary_50 is more maintainable than expression1 or my_transform.
Test Expressions Against Representative Source Data Before Going Live
The output of regex patterns and date formats depends entirely on the shape of the source value. Test each expression against real sample data from the source system, not assumed values. Edge cases such as null values, special characters, and unexpected formats will only appear in testing if representative data is used.
Document Every Expression and Its Purpose
Add a comment or description to each expression explaining why it exists and what source field it operates on. This makes future audits faster and reduces the risk of accidental deletion during maintenance.
Avoid Over-Engineering Transformations
If a transformation requires a complex chain of operations that cannot be handled by a single expression, consider whether the source or target system configuration could be adjusted to eliminate the need. Complex transformations are harder to debug and more likely to produce unexpected output when source data changes.
Audit Expressions After System Updates
If the source system changes a field format (for example, switching from numeric state IDs to named statuses), any Pattern or Replace expressions that relied on the old format will produce incorrect output. Include expression review as part of your post-upgrade integration audit.
Where Can I Go from Here?
Once you are comfortable with transformations and expressions, the following topics cover adjacent capabilities that work alongside them:
Filters and Conditions: Control which records are collected and under what criteria
Data Mapping Fundamentals: Core concepts for field mapping types, sync pitfalls, and best practices
Lookups: Retrieve related values from the target system based on source field content
Attachment and Comment Syncing: Configure related field mapping for binary and text-based related data
Custom Fields Syncing: Map non-standard fields present only in specific system instances
Best Practices: End-to-end guidance for designing, testing, and maintaining integrations
Last updated
Was this helpful?