From 50e69598132f06beb90fcf9916f29bf0613b863e Mon Sep 17 00:00:00 2001 From: wilwong-twilio <109997887+wilwong-twilio@users.noreply.github.com> Date: Wed, 2 Jul 2025 01:45:03 -0700 Subject: [PATCH 1/8] Update docs to include new liquid syntax function feature --- src/connections/destinations/actions.md | 136 ++++++++++++++++++++++++ 1 file changed, 136 insertions(+) diff --git a/src/connections/destinations/actions.md b/src/connections/destinations/actions.md index 68dd8bef64..2e5fcb5b22 100644 --- a/src/connections/destinations/actions.md +++ b/src/connections/destinations/actions.md @@ -238,6 +238,142 @@ You can't concatenate event variables and plain text with static values and func ![Mapping UI showing two concatenated fields: "+1 phone" and "context.page.url context.page.path"](images/mapping-concatenation.png) +### Liquid syntax +The liquid syntax function allows you to transform event data with fine-grain control before it reaches cloud-mode destinations using the LiquidJS templating language. Use Liquid templates to clean, format, or conditionally transform data such as user properties, timestamps, or event metadata to meet the requirements of your downstream tools. Liquid templates are applied in the Mappings tab of your Segment workspace, ensuring seamless integration with your event pipeline. + +### Supported liquid tags and filters +The following LiquidJS tags and filters are supported for Segment mappings. These are carefully selected to ensure performance, security, and compatibility with real-time event processing. Unsupported tags and filters are disabled to prevent performance degradation or security risks. + +### Supported tags +| Tag Name | Description | +|-------------------|-------------| +| `assign` | Assigns a value to a variable for reuse in the template. | +| `capture` | Captures output into a variable for complex transformations. | +| `case` | Implements switch-like logic for conditional processing. | +| `comment` | Ignores content during rendering; useful for documentation. | +| `decrement` | Decrements a counter variable; useful for simple counting. | +| `echo` | Outputs variable values; operates on provided event data. | +| `else` | Provides an alternative branch in `if` or `case` statements. | +| `elsif` | Adds additional conditions in `if` statements. | +| `if` | Enables conditional logic based on event data. | +| `increment` | Increments a counter variable; useful for simple counting. | +| `liquid` | Allows nested Liquid code execution in a sandboxed environment. | +| `raw` | Outputs content verbatim without escaping. | +| `unless` | Executes logic if a condition is not true (negation of `if`). | +| `when` | Part of `case` statements for matching specific values. | + +### Supported filters +| Filter Name | Description | +|--------------------------------|-------------| +| `abs` | Returns the absolute value of a number. | +| `append` | Concatenates a string to the end of another string. | +| `at_least` | Returns the greater of two numbers. | +| `at_most` | Returns the lesser of two numbers. | +| `capitalize` | Capitalizes the first letter of a string. | +| `ceil` | Rounds a number up to the next integer. | +| `cgi_escape` | Escapes strings for CGI contexts. | +| `compact` | Removes null values from an array. | +| `date` | Formats a date using a specified format (e.g., `%s` for Unix timestamp). | +| `date_to_long_string` | Formats a date into a long string (e.g., `01 July 2025`). | +| `date_to_rfc822` | Formats a date in RFC822 format. | +| `date_to_string` | Converts a date to a short string format. | +| `date_to_xmlschema` | Formats a date in XML schema format. | +| `default` | Provides a default value for null inputs. | +| `divided_by` | Divides a number by another number. | +| `downcase` | Converts a string to lowercase. | +| `escape` | Escapes HTML characters in a string. | +| `escape_once` | Escapes HTML characters only once. | +| `first` | Retrieves the first element of an array. | +| `floor` | Rounds a number down to the previous integer. | +| `inspect` | Converts an object to a JSON string. | +| `join` | Joins array elements into a string with a separator. | +| `json` | Converts an object to a JSON string. | +| `jsonify` | Similar to `json`; converts an object to a JSON string. | +| `last` | Retrieves the last element of an array. | +| `lstrip` | Removes leading whitespace from a string. | +| `minus` | Subtracts a number from another number. | +| `modulo` | Returns the remainder of a division operation. | +| `normalize_whitespace` | Normalizes whitespace in a string. | +| `number_of_words` | Counts the number of words in a string. | +| `plus` | Adds two numbers. | +| `pop` | Removes the last element from an array. | +| `push` | Adds an element to the end of an array. | +| `prepend` | Adds a string to the start of another string. | +| `raw` | Outputs content verbatim without escaping. | +| `remove` | Removes all occurrences of a substring. | +| `remove_first` | Removes the first occurrence of a substring. | +| `remove_last` | Removes the last occurrence of a substring. | +| `replace` | Replaces all occurrences of a substring with another string. | +| `replace_first` | Replaces the first occurrence of a substring. | +| `replace_last` | Replaces the last occurrence of a substring. | +| `round` | Rounds a number to a specified number of decimal places. | +| `rstrip` | Removes trailing whitespace from a string. | +| `shift` | Removes the first element from an array. | +| `size` | Returns the length of a string or array. | +| `slice` | Extracts a portion of a string or array. | +| `slugify` | Converts a string into a URL-friendly format. | +| `split` | Splits a string into an array based on a delimiter. | +| `strip` | Removes whitespace from both ends of a string. | +| `strip_html` | Removes HTML tags from a string. | +| `strip_newlines` | Removes newline characters from a string. | +| `sum` | Sums numeric values in an array. | +| `times` | Multiplies a number by another number. | +| `to_integer` | Converts a value to an integer. | +| `truncate` | Truncates a string to a specified length. | +| `truncatewords` | Truncates a string to a specified word count. | +| `unshift` | Adds an element to the start of an array. | +| `upcase` | Converts a string to uppercase. | +| `uri_escape` | Escapes a string for use in a URI. | +| `url_decode` | Decodes a URL-encoded string. | +| `url_encode` | Encodes a string for use in a URL. | +| `where` | Filters an array based on a property and value. | +| `xml_escape` | Escapes characters for XML compatibility. | + +### Examples +Below are two examples demonstrating how to use Liquid templates in Segment mappings to transform event data for cloud-mode destinations. These examples showcase common use cases like string manipulation and conditional logic. + +#### Example 1: Standardize email addresses +This example converts an email address to lowercase and removes extra whitespace, ensuring consistency for a destination. + +```json +{% if event.properties.email %} + {{ event.properties.email | downcase | strip }} +{% else %} + {{ event.properties.email | default: "unknown@example.com" }} +{% endif %} +``` +Input: `event.properties.email` = "user@example.com" +Output: user@example.com + +Explanation: +* The `if` tag checks if `event.properties.email` exists. +* The `downcase` filter converts the email to lowercase. +* The `strip` filter removes leading/trailing whitespace. +* The `default` filter provides a fallback email if the input is missing. + +#### Example 2: Transform phone number with conditional logic +This example formats a phone number by removing non-digit characters, adding a country code, and prepending a plus sign. + +```json +{% if event.properties.phone %} + {% assign phone = event.properties.phone | strip | remove: "-" | remove: "(" | remove: ")" | remove: " " %} + {% if phone | slice: 0, 1 != "1" %} + {% assign phone = phone | prepend: "1" %} + {% endif %} + {{ phone | prepend: "+" }} +{% else %} + {{ event.properties.phone | default: "" }} +{% endif %} +``` +Input: `event.properties.phone` = "(123) 456-7890" +Output: +11234567890 + +Explanation: +* The `assign` tag stores the cleaned phone number after applying `strip` and `remove` filters to eliminate whitespace and non-digit characters (e.g., `-`, `(`, `)`). +* The `slice: 0, 1` filter checks if the phone number starts with `1`; if not, `prepend: "1"` adds the country code. +* The `prepend: "+"` filter adds the `+` prefix. +* The `default` filter outputs an empty string if the phone number is missing. + ## Conditions > info "" From 95f154edbac78664d1324d93243a006aa05498e1 Mon Sep 17 00:00:00 2001 From: wilwong-twilio <109997887+wilwong-twilio@users.noreply.github.com> Date: Wed, 2 Jul 2025 01:59:18 -0700 Subject: [PATCH 2/8] Update actions.md --- src/connections/destinations/actions.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/connections/destinations/actions.md b/src/connections/destinations/actions.md index 2e5fcb5b22..06d689d64d 100644 --- a/src/connections/destinations/actions.md +++ b/src/connections/destinations/actions.md @@ -241,10 +241,10 @@ You can't concatenate event variables and plain text with static values and func ### Liquid syntax The liquid syntax function allows you to transform event data with fine-grain control before it reaches cloud-mode destinations using the LiquidJS templating language. Use Liquid templates to clean, format, or conditionally transform data such as user properties, timestamps, or event metadata to meet the requirements of your downstream tools. Liquid templates are applied in the Mappings tab of your Segment workspace, ensuring seamless integration with your event pipeline. -### Supported liquid tags and filters +#### Supported liquid tags and filters The following LiquidJS tags and filters are supported for Segment mappings. These are carefully selected to ensure performance, security, and compatibility with real-time event processing. Unsupported tags and filters are disabled to prevent performance degradation or security risks. -### Supported tags +#### Supported tags | Tag Name | Description | |-------------------|-------------| | `assign` | Assigns a value to a variable for reuse in the template. | @@ -262,7 +262,7 @@ The following LiquidJS tags and filters are supported for Segment mappings. Thes | `unless` | Executes logic if a condition is not true (negation of `if`). | | `when` | Part of `case` statements for matching specific values. | -### Supported filters +#### Supported filters | Filter Name | Description | |--------------------------------|-------------| | `abs` | Returns the absolute value of a number. | @@ -329,10 +329,10 @@ The following LiquidJS tags and filters are supported for Segment mappings. Thes | `where` | Filters an array based on a property and value. | | `xml_escape` | Escapes characters for XML compatibility. | -### Examples +#### Examples Below are two examples demonstrating how to use Liquid templates in Segment mappings to transform event data for cloud-mode destinations. These examples showcase common use cases like string manipulation and conditional logic. -#### Example 1: Standardize email addresses +##### Example 1: Standardize email addresses This example converts an email address to lowercase and removes extra whitespace, ensuring consistency for a destination. ```json @@ -351,7 +351,7 @@ Explanation: * The `strip` filter removes leading/trailing whitespace. * The `default` filter provides a fallback email if the input is missing. -#### Example 2: Transform phone number with conditional logic +##### Example 2: Transform phone number with conditional logic This example formats a phone number by removing non-digit characters, adding a country code, and prepending a plus sign. ```json From e63d2a99aa5598f76f2e4b7c1b4dc3768486c849 Mon Sep 17 00:00:00 2001 From: wilwong-twilio <109997887+wilwong-twilio@users.noreply.github.com> Date: Mon, 14 Jul 2025 14:42:30 -0700 Subject: [PATCH 3/8] Update src/connections/destinations/actions.md Co-authored-by: stayseesong <83784848+stayseesong@users.noreply.github.com> --- src/connections/destinations/actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/actions.md b/src/connections/destinations/actions.md index 06d689d64d..9514fe9a05 100644 --- a/src/connections/destinations/actions.md +++ b/src/connections/destinations/actions.md @@ -239,7 +239,7 @@ You can't concatenate event variables and plain text with static values and func ![Mapping UI showing two concatenated fields: "+1 phone" and "context.page.url context.page.path"](images/mapping-concatenation.png) ### Liquid syntax -The liquid syntax function allows you to transform event data with fine-grain control before it reaches cloud-mode destinations using the LiquidJS templating language. Use Liquid templates to clean, format, or conditionally transform data such as user properties, timestamps, or event metadata to meet the requirements of your downstream tools. Liquid templates are applied in the Mappings tab of your Segment workspace, ensuring seamless integration with your event pipeline. +The liquid syntax function enables you to transform event data with fine-grain control before it reaches cloud-mode destinations using the LiquidJS templating language. Use Liquid templates to clean, format, or conditionally transform data such as user properties, timestamps, or event metadata to meet the requirements of your downstream tools. Liquid templates are applied in the **Mappings** tab of your Segment workspace to enable you to integrate with your event pipeline. #### Supported liquid tags and filters The following LiquidJS tags and filters are supported for Segment mappings. These are carefully selected to ensure performance, security, and compatibility with real-time event processing. Unsupported tags and filters are disabled to prevent performance degradation or security risks. From 3782ecbbbe6d1cceb0b438578b02935f6d7b5f6b Mon Sep 17 00:00:00 2001 From: wilwong-twilio <109997887+wilwong-twilio@users.noreply.github.com> Date: Mon, 14 Jul 2025 14:42:51 -0700 Subject: [PATCH 4/8] Update src/connections/destinations/actions.md Co-authored-by: stayseesong <83784848+stayseesong@users.noreply.github.com> --- src/connections/destinations/actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/actions.md b/src/connections/destinations/actions.md index 9514fe9a05..775b401973 100644 --- a/src/connections/destinations/actions.md +++ b/src/connections/destinations/actions.md @@ -242,7 +242,7 @@ You can't concatenate event variables and plain text with static values and func The liquid syntax function enables you to transform event data with fine-grain control before it reaches cloud-mode destinations using the LiquidJS templating language. Use Liquid templates to clean, format, or conditionally transform data such as user properties, timestamps, or event metadata to meet the requirements of your downstream tools. Liquid templates are applied in the **Mappings** tab of your Segment workspace to enable you to integrate with your event pipeline. #### Supported liquid tags and filters -The following LiquidJS tags and filters are supported for Segment mappings. These are carefully selected to ensure performance, security, and compatibility with real-time event processing. Unsupported tags and filters are disabled to prevent performance degradation or security risks. +Segment supports the following LiquidJS tags and filters for mappings. Segment selected these to ensure performance, security, and compatibility with real-time event processing. Segment disabled unsupported tags and filters to prevent performance degradation or security risks. #### Supported tags | Tag Name | Description | From ad858bbd5e287b2e2cafd2a5922a02aae0ea5c4d Mon Sep 17 00:00:00 2001 From: wilwong-twilio <109997887+wilwong-twilio@users.noreply.github.com> Date: Mon, 14 Jul 2025 14:43:07 -0700 Subject: [PATCH 5/8] Update src/connections/destinations/actions.md Co-authored-by: stayseesong <83784848+stayseesong@users.noreply.github.com> --- src/connections/destinations/actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/actions.md b/src/connections/destinations/actions.md index 775b401973..ce46b3dc14 100644 --- a/src/connections/destinations/actions.md +++ b/src/connections/destinations/actions.md @@ -273,7 +273,7 @@ Segment supports the following LiquidJS tags and filters for mappings. Segment s | `ceil` | Rounds a number up to the next integer. | | `cgi_escape` | Escapes strings for CGI contexts. | | `compact` | Removes null values from an array. | -| `date` | Formats a date using a specified format (e.g., `%s` for Unix timestamp). | +| `date` | Formats a date using a specified format (for example, `%s` for Unix timestamp). | | `date_to_long_string` | Formats a date into a long string (e.g., `01 July 2025`). | | `date_to_rfc822` | Formats a date in RFC822 format. | | `date_to_string` | Converts a date to a short string format. | From a1988a05268a5c7bc877315c67791fd92510fa97 Mon Sep 17 00:00:00 2001 From: wilwong-twilio <109997887+wilwong-twilio@users.noreply.github.com> Date: Mon, 14 Jul 2025 14:43:19 -0700 Subject: [PATCH 6/8] Update src/connections/destinations/actions.md Co-authored-by: stayseesong <83784848+stayseesong@users.noreply.github.com> --- src/connections/destinations/actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/actions.md b/src/connections/destinations/actions.md index ce46b3dc14..8079b06b35 100644 --- a/src/connections/destinations/actions.md +++ b/src/connections/destinations/actions.md @@ -274,7 +274,7 @@ Segment supports the following LiquidJS tags and filters for mappings. Segment s | `cgi_escape` | Escapes strings for CGI contexts. | | `compact` | Removes null values from an array. | | `date` | Formats a date using a specified format (for example, `%s` for Unix timestamp). | -| `date_to_long_string` | Formats a date into a long string (e.g., `01 July 2025`). | +| `date_to_long_string` | Formats a date into a long string (for example, `01 July 2025`). | | `date_to_rfc822` | Formats a date in RFC822 format. | | `date_to_string` | Converts a date to a short string format. | | `date_to_xmlschema` | Formats a date in XML schema format. | From 0672daa845eaacb0371b754694d9179221ceeb66 Mon Sep 17 00:00:00 2001 From: wilwong-twilio <109997887+wilwong-twilio@users.noreply.github.com> Date: Mon, 14 Jul 2025 14:43:28 -0700 Subject: [PATCH 7/8] Update src/connections/destinations/actions.md Co-authored-by: stayseesong <83784848+stayseesong@users.noreply.github.com> --- src/connections/destinations/actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/actions.md b/src/connections/destinations/actions.md index 8079b06b35..ce79806055 100644 --- a/src/connections/destinations/actions.md +++ b/src/connections/destinations/actions.md @@ -348,7 +348,7 @@ Output: user@example.com Explanation: * The `if` tag checks if `event.properties.email` exists. * The `downcase` filter converts the email to lowercase. -* The `strip` filter removes leading/trailing whitespace. +* The `strip` filter removes leading or trailing whitespace. * The `default` filter provides a fallback email if the input is missing. ##### Example 2: Transform phone number with conditional logic From 0c3aada1c3172e84c93b36429ce991a5ba59d543 Mon Sep 17 00:00:00 2001 From: wilwong-twilio <109997887+wilwong-twilio@users.noreply.github.com> Date: Mon, 14 Jul 2025 14:43:45 -0700 Subject: [PATCH 8/8] Update src/connections/destinations/actions.md Co-authored-by: stayseesong <83784848+stayseesong@users.noreply.github.com> --- src/connections/destinations/actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/connections/destinations/actions.md b/src/connections/destinations/actions.md index ce79806055..24c9a84ca7 100644 --- a/src/connections/destinations/actions.md +++ b/src/connections/destinations/actions.md @@ -369,7 +369,7 @@ Input: `event.properties.phone` = "(123) 456-7890" Output: +11234567890 Explanation: -* The `assign` tag stores the cleaned phone number after applying `strip` and `remove` filters to eliminate whitespace and non-digit characters (e.g., `-`, `(`, `)`). +* The `assign` tag stores the cleaned phone number after applying `strip` and `remove` filters to eliminate whitespace and non-digit characters (for example, `-`, `(`, `)`). * The `slice: 0, 1` filter checks if the phone number starts with `1`; if not, `prepend: "1"` adds the country code. * The `prepend: "+"` filter adds the `+` prefix. * The `default` filter outputs an empty string if the phone number is missing.