Advanced Payload Patterns

This page describes advanced patterns for building dynamic integration payloads in Cutover. It covers techniques for shaping and manipulating payload data, applying logic, and reusing common patterns to support more complex integration requirements.

‍

Using Liquid filters with dynamic references in Custom Integrations

When building custom integrations in Cutover, you can apply Liquid filters to manipulate values before they are sent in your payloads. Liquid filters operate on the resolved values of dynamic fields enabling you to perform calculations or format strings as needed.

You can think of Liquid templating as a pre-processing layer for your integration payloads—it ensures the data sent from Cutover is delivered in exactly the format the receiving system expects.

When a task is executed, the integration engine processes Liquid templates in the following sequence:

Resolution – The raw value is retrieved from Cutover (for example, a task name or duration).
Filter application – Any Liquid filters you’ve defined are applied to that value.
Delivery – The final, transformed value is inserted into the outbound JSON payload and sent to the external system.

Sample JSON payload snippet

{
  "task_name": "{{Task.name | replace: 'Old', 'New'}}",
  "duration_minutes": "{{Task.duration | plus: 10}}",
  "assignee_email": "{{Task.assignee.email | downcase}}",
  "runbook_version": "{{Runbook.parent_version_id}}"
}

Explanation

^{{{Task.name | replace: 'Old', 'New'}}} - Replaces the word 'Old' with 'New' in the Task name.
^{{{Task.duration | plus: 10}}} - Adds 10 to the value returned by the task duration.
^{{{Runbook.parent_version_id}}} - Dynamically references the parent runbook version ID.

Notes

Liquid filters are applied after the dynamic reference is resolved, so they operate on the actual values.

Multiple filters can be chained as needed (e.g., ^{{{Task.name | replace: 'Old', 'New' | upcase}}}).
This approach helps tailor integration payloads dynamically based on task or runbook data.

More information on how to use the Liquid template language can be found in https://shopify.dev/docs/api/liquid

‍

Variable Assignment

Assign dynamic field values to variables for reuse in your payload using the ^assign tag:

// Pre-processing section
{% assign total = CustomField['Revenue'] | plus: 100 %}
{% assign tax = total | times: 0.2 %}

// Payload section
{
  "subtotal": {{ total }},
  "tax": {{ tax }},
  "grand_total": {{ total | plus: tax }}
}

Use cases

Perform calculations before including values in the payload
Reuse computed values multiple times
Improve payload readability by extracting complex expressions

‍

Capture Blocks

‍Use ^capture blocks to build complex strings or perform multi-step transformations before assigning to a variable:Example: Formatting an ArrayGiven a custom field “Array field” that returns ^{["one", "two", "three"]}:

// Pre-processing section
{% capture formattedArray -%}
  {% assign myArray = CustomField['Array field'] | remove: '["' | remove: '"]' | split: '", "' %}
  {%- for item in myArray -%}
    <span>{{ item | strip }}</span><br />
  {%- endfor -%}
{% endcapture -%}

// Payload section
{
  "formatted_html": "{{ formattedArray | escape }}"
}

Result

{
  "formatted_html": "<span>one</span><br /><span>two</span><br /><span>three</span><br />"
}

‍Use cases

Generate formatted HTML for email notifications or webhooks
Build complex strings through iteration and concatenation
Process and transform array data before sending

Note: The ^- in ^{%- and ^-%} removes whitespace, creating a cleaner output.

‍

Conditional Logic

‍Use conditional statements to include different values in your payload based on custom field values.

‍Example: Simple If Statement

// Pre-processing section
{% assign status = CustomField['Environment'] %}

// Payload section
{
  "deploy_url": "{% if status == 'Production' %}https://prod.example.com{% else %}https://staging.example.com{% endif %}"
}

‍Example: Case Statement

‍For multiple conditions, use a ^case statement:

// Pre-processing section
{% assign validation = CustomField['Validation Result'] %}
{% capture decision %}
  {% case validation %}
    {% when "passed" %}GO
    {% when "failed" %}NO GO
    {% when "pending" %}AWAITING REVIEW
    {% else %}UNKNOWN
  {% endcase %}
{% endcapture %}

// Payload section
{
  "decision": "{{ decision | strip }}",
  "timestamp": "{{ 'now' | date: '%Y-%m-%d %H:%M:%S' }}"
}

Result examples

If validation = “passed”: ^{{"decision": "GO", ...}}
If validation = “failed”: ^{{"decision": "NO GO", ...}}
If validation = “anything else”: ^{{"decision": "UNKNOWN", ...}}

Use cases

Map custom field values to API-specific formats
Conditionally include or exclude payload fields
Implement business logic in webhook payloads

‍

Combining Patterns

‍These patterns can be combined for more sophisticated transformations:

// Pre-processing section
{% assign items = CustomField['Task List'] | remove: '["' | remove: '"]' | split: '", "' %}
{% assign priority = CustomField['Priority'] %}

{% capture task_html %}
  <div class="{% if priority == 'High' %}urgent{% endif %}">
    <ul>
    {%- for item in items -%}
      <li>{{ item | strip }}</li>
    {%- endfor -%}
    </ul>
  </div>
{% endcapture %}

// Payload section
{
  "priority": "{{ priority }}",
  "task_count": {{ items.size }},
  "formatted_tasks": "{{ task_html | escape }}"
}

Tip

Always use ^{| escape} when including HTML strings in JSON payloads to ensure proper encoding.For a full reference to the Liquid templating language, please visit https://shopify.dev/docs/api/liquid

‍