# Transformations & Expressions
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.*
| Expression Type | What It Does | Common Use Case |
| -------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| 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.
{% stepper %}
{% step %}
#### 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.*
> {% endstep %}
{% step %}
#### Add a New Expression
1. Click **Add Expression**.
2. Enter a unique name for the expression.
3. Select the expression type from the dropdown.
4. 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.*
> {% endstep %}
{% step %}
#### 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.*
> {% endstep %}
> {% endstepper %}
### 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: `"Server Down"`. 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.
{% hint style="warning" %}
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.
{% endhint %}
### 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
| Scenario | Expression Type | Configuration Notes |
| ------------------------------------------------------------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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.
| Error Type | Likely Cause | Resolution |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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
---
# 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/transformations-and-expressions.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.