Skip to content

Commit 2c2380d

Browse files
stayseesongstayseesong
authored
Merge pull request #7734 from segmentio/wilwong-twilio-patch-1
Update docs to include new liquid syntax function feature
2 parents f30daf9 + 0c3aada commit 2c2380d

File tree

1 file changed

+136
-0
lines changed

1 file changed

+136
-0
lines changed

‎src/connections/destinations/actions.md

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,6 +238,142 @@ You can't concatenate event variables and plain text with static values and func
238238

239239
![Mapping UI showing two concatenated fields: "+1 phone" and "context.page.url context.page.path"](images/mapping-concatenation.png)
240240

241+
### Liquid syntax
242+
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.
243+
244+
#### Supported liquid tags and filters
245+
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.
246+
247+
#### Supported tags
248+
| Tag Name | Description |
249+
|-------------------|-------------|
250+
| `assign` | Assigns a value to a variable for reuse in the template. |
251+
| `capture` | Captures output into a variable for complex transformations. |
252+
| `case` | Implements switch-like logic for conditional processing. |
253+
| `comment` | Ignores content during rendering; useful for documentation. |
254+
| `decrement` | Decrements a counter variable; useful for simple counting. |
255+
| `echo` | Outputs variable values; operates on provided event data. |
256+
| `else` | Provides an alternative branch in `if` or `case` statements. |
257+
| `elsif` | Adds additional conditions in `if` statements. |
258+
| `if` | Enables conditional logic based on event data. |
259+
| `increment` | Increments a counter variable; useful for simple counting. |
260+
| `liquid` | Allows nested Liquid code execution in a sandboxed environment. |
261+
| `raw` | Outputs content verbatim without escaping. |
262+
| `unless` | Executes logic if a condition is not true (negation of `if`). |
263+
| `when` | Part of `case` statements for matching specific values. |
264+
265+
#### Supported filters
266+
| Filter Name | Description |
267+
|--------------------------------|-------------|
268+
| `abs` | Returns the absolute value of a number. |
269+
| `append` | Concatenates a string to the end of another string. |
270+
| `at_least` | Returns the greater of two numbers. |
271+
| `at_most` | Returns the lesser of two numbers. |
272+
| `capitalize` | Capitalizes the first letter of a string. |
273+
| `ceil` | Rounds a number up to the next integer. |
274+
| `cgi_escape` | Escapes strings for CGI contexts. |
275+
| `compact` | Removes null values from an array. |
276+
| `date` | Formats a date using a specified format (for example, `%s` for Unix timestamp). |
277+
| `date_to_long_string` | Formats a date into a long string (for example, `01 July 2025`). |
278+
| `date_to_rfc822` | Formats a date in RFC822 format. |
279+
| `date_to_string` | Converts a date to a short string format. |
280+
| `date_to_xmlschema` | Formats a date in XML schema format. |
281+
| `default` | Provides a default value for null inputs. |
282+
| `divided_by` | Divides a number by another number. |
283+
| `downcase` | Converts a string to lowercase. |
284+
| `escape` | Escapes HTML characters in a string. |
285+
| `escape_once` | Escapes HTML characters only once. |
286+
| `first` | Retrieves the first element of an array. |
287+
| `floor` | Rounds a number down to the previous integer. |
288+
| `inspect` | Converts an object to a JSON string. |
289+
| `join` | Joins array elements into a string with a separator. |
290+
| `json` | Converts an object to a JSON string. |
291+
| `jsonify` | Similar to `json`; converts an object to a JSON string. |
292+
| `last` | Retrieves the last element of an array. |
293+
| `lstrip` | Removes leading whitespace from a string. |
294+
| `minus` | Subtracts a number from another number. |
295+
| `modulo` | Returns the remainder of a division operation. |
296+
| `normalize_whitespace` | Normalizes whitespace in a string. |
297+
| `number_of_words` | Counts the number of words in a string. |
298+
| `plus` | Adds two numbers. |
299+
| `pop` | Removes the last element from an array. |
300+
| `push` | Adds an element to the end of an array. |
301+
| `prepend` | Adds a string to the start of another string. |
302+
| `raw` | Outputs content verbatim without escaping. |
303+
| `remove` | Removes all occurrences of a substring. |
304+
| `remove_first` | Removes the first occurrence of a substring. |
305+
| `remove_last` | Removes the last occurrence of a substring. |
306+
| `replace` | Replaces all occurrences of a substring with another string. |
307+
| `replace_first` | Replaces the first occurrence of a substring. |
308+
| `replace_last` | Replaces the last occurrence of a substring. |
309+
| `round` | Rounds a number to a specified number of decimal places. |
310+
| `rstrip` | Removes trailing whitespace from a string. |
311+
| `shift` | Removes the first element from an array. |
312+
| `size` | Returns the length of a string or array. |
313+
| `slice` | Extracts a portion of a string or array. |
314+
| `slugify` | Converts a string into a URL-friendly format. |
315+
| `split` | Splits a string into an array based on a delimiter. |
316+
| `strip` | Removes whitespace from both ends of a string. |
317+
| `strip_html` | Removes HTML tags from a string. |
318+
| `strip_newlines` | Removes newline characters from a string. |
319+
| `sum` | Sums numeric values in an array. |
320+
| `times` | Multiplies a number by another number. |
321+
| `to_integer` | Converts a value to an integer. |
322+
| `truncate` | Truncates a string to a specified length. |
323+
| `truncatewords` | Truncates a string to a specified word count. |
324+
| `unshift` | Adds an element to the start of an array. |
325+
| `upcase` | Converts a string to uppercase. |
326+
| `uri_escape` | Escapes a string for use in a URI. |
327+
| `url_decode` | Decodes a URL-encoded string. |
328+
| `url_encode` | Encodes a string for use in a URL. |
329+
| `where` | Filters an array based on a property and value. |
330+
| `xml_escape` | Escapes characters for XML compatibility. |
331+
332+
#### Examples
333+
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.
334+
335+
##### Example 1: Standardize email addresses
336+
This example converts an email address to lowercase and removes extra whitespace, ensuring consistency for a destination.
337+
338+
```json
339+
{% if event.properties.email %}
340+
{{ event.properties.email | downcase | strip }}
341+
{% else %}
342+
{{ event.properties.email | default: "unknown@example.com" }}
343+
{% endif %}
344+
```
345+
Input: `event.properties.email` = "user@example.com"
346+
Output: user@example.com
347+
348+
Explanation:
349+
* The `if` tag checks if `event.properties.email` exists.
350+
* The `downcase` filter converts the email to lowercase.
351+
* The `strip` filter removes leading or trailing whitespace.
352+
* The `default` filter provides a fallback email if the input is missing.
353+
354+
##### Example 2: Transform phone number with conditional logic
355+
This example formats a phone number by removing non-digit characters, adding a country code, and prepending a plus sign.
356+
357+
```json
358+
{% if event.properties.phone %}
359+
{% assign phone = event.properties.phone | strip | remove: "-" | remove: "(" | remove: ")" | remove: " " %}
360+
{% if phone | slice: 0, 1 != "1" %}
361+
{% assign phone = phone | prepend: "1" %}
362+
{% endif %}
363+
{{ phone | prepend: "+" }}
364+
{% else %}
365+
{{ event.properties.phone | default: "" }}
366+
{% endif %}
367+
```
368+
Input: `event.properties.phone` = "(123) 456-7890"
369+
Output: +11234567890
370+
371+
Explanation:
372+
* The `assign` tag stores the cleaned phone number after applying `strip` and `remove` filters to eliminate whitespace and non-digit characters (for example, `-`, `(`, `)`).
373+
* The `slice: 0, 1` filter checks if the phone number starts with `1`; if not, `prepend: "1"` adds the country code.
374+
* The `prepend: "+"` filter adds the `+` prefix.
375+
* The `default` filter outputs an empty string if the phone number is missing.
376+
241377
## Conditions
242378

243379
> info ""

0 commit comments

Comments
 (0)