String functions

Learn about string functions in the Digibee Integration Platform and how to use them.

String functions are used to manipulate string data. These are the string functions you can use with Digibee's Double Braces language:

Function	Description
CAPITALIZE	Capitalizes the first character of a string
LOWERCASE	Converts all characters to lowercase
UPPERCASE	Converts all characters to uppercase
NORMALIZE	Transforms special characters into non-special characters
CONTAINS	Checks if a substring is contained in a given string
INDEXOF	Returns the index of the first occurrence of a substring
LASTINDEXOF	Returns the index of the last occurrence of a substring
MATCHES	Checks if a string matches a regular expression
STRINGMATCHES	Returns all matched expressions in a string that satisfy a pattern
FUZZYMATCH	Performs an approximate comparison between a string and a list of candidates
CONCAT	Concatenates any number of strings into a single string
CONCATWITHOUTTAB	Concatenates strings and replaces tab characters with spaces
JOIN	Concatenates a list of strings with a specified separator
REPLACE	Replaces all occurrences of a substring based on a regular expression
SPLIT	Splits a string into an array based on a regular expression
SUBSTRING	Extracts a substring from a given string
TRIM	Removes blank spaces at the beginning and end of a string
LEFTPAD	Fills the left side of a string with a character to a specific length
RIGHTPAD	Fills the right side of a string with a character to a specific length
ESCAPE	Encodes a string using escape sequences
UNESCAPE	Unencodes a string that has escape sequences
DEFAULT	Returns a default value for null or nonexistent references
TOSTRING	Converts an object to its string representation
RANDOMSTRINGS	Generates random strings given a charset and length

Case and normalization

CAPITALIZE

Capitalizes the first character of a string. Other characters are not affected.

Syntax

CAPITALIZE(value : string) -> string

• value: the string whose first letter is to be capitalized.

Returns: a string that is a version of value with the first character in upper case.

Usage example

{{ CAPITALIZE("hello, world!") }}

The expected result is:

"Hello, world!"

LOWERCASE

Converts all characters to lowercase.

Syntax

LOWERCASE(value: string) -> string

• value: the input string to be converted to lowercase.

Returns: the string that is the lowercase equivalent of the input string.

Usage example

{{ LOWERCASE("HELLO, WorLD!") }}

The expected result is:

"hello, world!"

UPPERCASE

Converts all characters to uppercase.

Syntax

UPPERCASE(value: string) -> string

• value: the input string to be converted to uppercase.

Returns: the string that is the uppercase equivalent of the input string.

Usage example

{{ UPPERCASE("Hello, world!") }}

The expected result is:

"HELLO, WORLD!"

NORMALIZE

Transforms special characters into non-special characters.

Syntax

NORMALIZE(value: string) -> string

• value: the string to be normalized.

Returns: the normalized string with special characters replaced by their non-special counterparts.

Usage example

{{ NORMALIZE("São Paulo") }}

The expected result is:

"Sao Paulo"

Search and matching

CONTAINS

Checks if a substring is contained in a given string.

Syntax

CONTAINS(main_string: string, sub_string: string) -> boolean

• main_string: the main string to search in.

• sub_string: the substring to search for.

Returns: true if the substring is found in the main string, false otherwise.

Usage example

{{ CONTAINS("Hello, world!", "world") }}

The expected result is:

true

INDEXOF

Returns the index of the first occurrence of a substring within a given string. This search is case-sensitive and the index starts at 0.

Syntax

INDEXOF(main_string: string, sub_string: string, fromIndex: integer<optional>) -> int

• main_string: the main string to search in.

• sub_string: the substring to search for.

• fromIndex: the index from which the search should start. Defaults to 0.

Returns: an integer indicating the index of the first occurrence of the substring in the main string. If the substring is not found, the function returns -1.

Usage examples

1. Substring found

{{ INDEXOF("Hello, world!", "world") }}

The expected result is:

7

2. Substring not found

{{ INDEXOF("Hello, world!", "welcome") }}

The expected result is:

-1

LASTINDEXOF

Returns the index of the last occurrence of a substring within a given string. This search is case-sensitive and the index starts at 0.

Syntax

LASTINDEXOF(main_string: string, sub_string: string) -> int

• main_string: the main string to search in.

• sub_string: the substring to search for.

• fromIndex: the index from which the search should start. Defaults to 0.

Returns: an integer indicating the index of the last occurrence of the substring in the main string. If the substring is not found, the function returns -1.

Usage examples

1. Substring found

{{ LASTINDEXOF("Hello, world!", "o") }}

The expected result is:

8

2. Substring not found

{{ LASTINDEXOF("Hello, world!", "a") }}

Because the substring "a" is not contained in the string "Hello, world!", the expected result is:

-1

MATCHES

Checks if a string matches a regular expression.

Syntax

MATCHES(value: string, pattern: string) -> boolean

• value: the string to match against the given regular expression.

• pattern: the regular expression pattern to match against the input string.

Returns: true if the input string matches the regular expression, false otherwise.

Usage example

{{ MATCHES("123-456-7890", "\\d{3}-\\d{3}-\\d{4}") }}

The expected result is:

true

STRINGMATCHES

Returns an array of all the matched expressions in a string that satisfy a given pattern.

Syntax

STRINGMATCHES(value: string, pattern: string, patternFlag: string<optional>) -> Array[string]

• value: the string to search for matches.

• pattern: the regular expression pattern to match against the string.

• patternFlag: controls the behavior of the regular expression engine, such as case-insensitive matching, multi-line matching, or extended syntax. If not specified, the regular expression engine uses its default behavior. Options are:

Flag	Description
CANON_EQ	Activates canonical equivalence matching of Unicode characters. Characters that look identical are matched even if they have different Unicode codepoints.
CASE_INSENSITIVE	Deactivates case sensitivity.
COMMENTS	Allows comments in the regular expression pattern. Comments can be added after a hashtag #.
DOTALL	Activates "dotall" mode, allowing a dot . to match the newline character \n.
LITERAL	Treats the pattern as a sequence of literal characters. Metacharacters or escape sequences are given no special meaning.
MULTILINE	Activates matching across multiple lines.
UNICODE_CASE	Allows case-insensitive matching of Unicode characters, taking into account Unicode case folding rules.
UNICODE_CHARACTER_CLASS	Allows Unicode character classes in the regular expression pattern.
UNIX_LINES	Changes the behavior of the ^ and $ metacharacters to match the beginning and end of a line, respectively, rather than the beginning and end of the input string.

Returns: an array of all the matched expressions in the string that satisfy the pattern.

Usage example

{{ STRINGMATCHES("Hello, world!", "hello", "CASE_INSENSITIVE") }}

The expected result is:

["Hello"]

FUZZYMATCH

Performs an approximate comparison between a reference string and a list of candidates based on similarity.

Syntax

FUZZYMATCH(inputString, threshold, candidateOrArray1, candidateOrArray2, ...)

• inputString: The reference string for comparison. If null, it is treated as an empty string and execution is not stopped.

• threshold: A number between 0 and 1 that defines the minimum similarity (for example, 0.8 for 80%). The value must be a JSON number, not a string. Passing "0.8" (quoted) raises a type error. Values outside the [0, 1] range also raise an error.

• candidates: One or more arguments after the threshold, each of which can be a string, a JSON array, or any other JSON value (numbers, booleans, objects). Non-string values are converted to their JSON string representation before comparison. When an argument is an array, each of its first-level elements is evaluated as an independent candidate. Scalars and arrays can be mixed in the same call, and at least one candidate must be provided. Array expansion happens only at the first level: if an element of the array is itself an array or an object, it is treated as a single candidate and its JSON serialization is what gets compared.

Returns: an array of strings containing the candidates that have a similarity greater than or equal to the provided threshold, sorted by descending similarity (the most similar first). The returned values preserve their original formatting (case and accents).

Similarity is computed as 1 − (Levenshtein distance / max length of normalized strings). A score of 1 means identical strings (after normalization); a score of 0 means completely different strings.

For score calculation, the function applies the following normalization to both the input string and each candidate before comparing them:

• converts text to lowercase (case-insensitive),

• removes diacritics (accents),

• replaces punctuation with spaces,

• collapses multiple spaces into a single space, and trims leading/trailing whitespace.

Normalization affects only the score calculation. The original candidate text is preserved in the returned array.

Usage examples

Match with normalization (case and accents)

Even with accentuation differences in the candidate, normalization allows a match if the threshold is met.

• Expression: {{ FUZZYMATCH("ACME CORPORATION", 0.9, "ÁCME CORPÔRATION") }}

• Result: ["ÁCME CORPÔRATION"]

Multiple candidates with sorting

The function filters out candidates that do not meet the minimum threshold and sorts the results by proximity score.

• Expression: {{ FUZZYMATCH("Acme Corp", 0.5, "Globex", "Acme Corporation", "Aacme Corp") }}

• Result: ["Aacme Corp", "Acme Corporation"]

Strict threshold (no match)

If no candidate reaches the minimum similarity, an empty array is returned.

• Expression: {{ FUZZYMATCH("Apple", 0.9, "Pineapple", "Banana") }}

• Result: []

Array as candidates

Pass an array variable directly. Each element is evaluated as an independent candidate.

• Expression: {{ FUZZYMATCH("ACME", 0.9999, message.array) }}

• Result: Elements of message.array that meet the threshold, sorted by descending similarity.

Mixed scalar and array candidates

Scalars and arrays can be combined in the same call and are evaluated together.

• Expression: {{ FUZZYMATCH("ACME", 0.9, "ACME FIXED", message.otherArray) }}

• Result: All candidates from both sources that meet the threshold, sorted by descending similarity.

Empty array

An empty array does not add candidates and does not cause an error.

• Expression: {{ FUZZYMATCH("ACME", 0.99, []) }}

• Result: []

Parameter error handling

The function requires at least 3 parameters (input, threshold, and 1 candidate).

• Expression: {{ FUZZYMATCH("test", 0.8) }}

• Result: Error: Wrong number of parameters for function FUZZYMATCH expected at least 3 mandatory but got 2

Nested array (single candidate, no expansion)

Only the first level of an array argument is expanded. A nested array is treated as one candidate and its JSON serialization is compared.

• Expression: {{ FUZZYMATCH("a,b", 0.99, [["a", "b"], "c"]) }}

• Result: [] The inner ["a", "b"] is compared as the literal string '["a","b"]', not as the candidates "a" and "b" separately.

Invalid threshold

The threshold must be a number within the inclusive range [0, 1]. Any other value raises an error.

• Expression: {{ FUZZYMATCH("a", 1.5, "a") }}

• Result: Error: FUZZYMATCH threshold must be between 0 and 1, got 1.5

Null input is treated as an empty string

Null inputs do not stop execution. They are normalized to an empty string before comparison, and candidates are scored against that empty string.

• Expression: {{ FUZZYMATCH(null, 0.0, "anything") }}

• Result: ["anything"]

With threshold 0, every candidate matches because any similarity (including 0.0) satisfies the condition. With a higher threshold, the result is typically [] because the empty input has very low similarity to non-empty candidates.

Concatenation and joining

CONCAT

Concatenates any number of strings into a single string.

Syntax

CONCAT(*values: string) -> string

• values: any number of strings to be concatenated. Returns: the concatenated string.

Usage example

{{ CONCAT("Hello", ", ", "world!") }}

The expected result is:

"Hello, world!"

CONCATWITHOUTTAB

Concatenates two or more strings and replaces every tab character (\t) with a single space ( ).

Syntax

CONCATWITHOUTTAB(<string1>[, <string2>, ..., <stringN>])

• <string1>, <string2>, ..., <stringN>: one or more text expressions.

• Brackets [ ] indicate that additional parameters are optional.

Usage example

"hi": {{ CONCATWITHOUTTAB("Hello", "\tWorld")}}}

The expected result is:

{
  "hi": "Hello World"
}

JOIN

Concatenates a list of strings into a single string with a specified separator character between each string.

Syntax

JOIN(separator: string, *values: string) -> string

• separator: the separator character to be used between each string.

• values: any number of strings to be concatenated.

Returns: a string value representing the concatenated string with the specified separator character between each string in the input list.

Usage examples

Separator as space

{{ JOIN(" ", "These","words", "are", "separated","by","spaces") }}

The expected result is:

"These words are separated by spaces"

Separator as hyphen

{{ JOIN("-", "These","words", "are","separated","by","hyphens") }}

The expected result is:

"These-words-are-separated-by-hyphens"

Transformation

REPLACE

Replaces all occurrences of a substring in a string based on a given regular expression.

Syntax

REPLACE(value: string, pattern: string, replacement: string) -> string

• value: the string to be searched and altered.

• pattern: the regular expression pattern that specifies the substring to search for.

• replacement: the string that will replace all occurrences of the matched pattern in the input string.

Usage example

{{ REPLACE("Hello, world!", "Hello", "Bonjour") }}

The expected result is:

"Bonjour, world!"

SPLIT

Splits a string into an array of strings based on a specified regular expression pattern.

Syntax

SPLIT(value: string, pattern: string) -> Array[string]

• value: the string to be split.

• pattern: the regular expression pattern that specifies the split point. The string will be split at all occurrences of the pattern.

Returns: an array of strings resulting from the split operation.

Usage example

{{ SPLIT("Hello, world!", " ") }}

The expected result is:

["Hello,", "world!"]

SUBSTRING

Extracts a substring from a given string.

Syntax

SUBSTRING(value: string, start: int, end: int<optional>, throwIndexOutOfBoundError: boolean<optional>) -> string

• value: the original string from which the substring is to be extracted.

• start: the starting index of the substring. The index starts at 0.

• end: the ending index of the substring. If not provided, the extraction ends at the last character of the original string.

• throwIndexOutOfBoundError: if true, an error will be thrown if the provided indexes are out of range. Otherwise, the original string will be returned. Defaults to true.

Returns: the extracted substring from the original string.

Usage example

{{ SUBSTRING("Hello, world!", 0, 5) }}

The expected result is:

"Hello"

TRIM

Removes blank spaces at the beginning and end of a string.

Syntax

TRIM(value : string) -> string

• value: the string to be trimmed.

Returns: a string that is a trimmed version of value.

Usage example

{{ TRIM(" Hello, world! ") }}

The expected result is:

"Hello, world!"

LEFTPAD

Fills the left side of a given string with a specified character to a specific length.

Syntax

LEFTPAD(value: string, length: integer, character:string<optional>) -> string

• value: the input string to be padded.

• length: the length of the desired string.

• character: the character that will be used to pad the left side of the input string. Defaults to a blank space.

Returns: a padded string of the desired length with the specified character filling the left side of the input string. If the input string is already longer than the specified length, the original string is returned.

Usage examples

String shorter than the target length

{{ LEFTPAD("example", 10, "-")

The expected result is:

"---example"

String already at the target length

{{ LEFTPAD("hello", 5, "*")

Because "hello" already has 5 characters, the expected result is:

"hello"

RIGHTPAD

Fills the right side of a given string with a specified character to a specific length.

Syntax

RIGHTPAD(value: string, length: integer, character:string<optional>) -> string

• value: the input string to be padded.

• length: the length of the desired string.

• character: the character that will be used to pad the right side of the input string. Defaults to a blank space.

Returns: a padded string of the desired length with the specified character filling the right side of the input string. If the input string is already longer than the specified length, the original string is returned.

Usage examples

String shorter than the target length

{{ RIGHTPAD("example", 10, "-") }}

The expected result is:

"Example---"

String already at the target length

{{ RIGHTPAD("hello", 5, "*") }}

Because "hello" already has 5 characters, the expected result is:

"hello"

Encoding

ESCAPE

Encodes a string using escape sequences.

Syntax

ESCAPE(value: string, escapeType: string<optional>) -> string

• value: the string to be encoded.

• escapeType: the type of escaping to be used. Valid options are "JSON", "XML", "CSV", and "HTML". Defaults to "JSON".

Returns: a new string in which certain characters have been escaped.

Usage example

{{ ESCAPE("<h1>Hello, world!</h1>", "HTML") }}

The expected result is:

"<h1>Hello, world!</h1>"

UNESCAPE

Unencodes a string that has escape sequences.

Syntax

UNESCAPE(value: string, escapeType: string<optional>) -> string

• value: the string to be unencoded.

• escapeType: the type of escaping to be used. Valid options are "JSON", "XML", "CSV", and "HTML". Defaults to "JSON".

Returns: a new string in which certain characters have been unescaped.

Usage example

{{ UNESCAPE("<h1>Hello, world!</h1>", "HTML") }}

The expected result is:

"<h1>Hello, world!</h1>"

Utility

DEFAULT

Returns a default value when a reference is made to a null or nonexistent value.

Syntax

DEFAULT(value : string, defaultValue : string) -> string

• value: the value to be checked for null or nonexistence.

• defaultValue: the default value to be returned if value is null or nonexistent.

Returns: either value, if value is not null or nonexistent, or defaultValue, if it is.

Usage example

Suppose you are using this function in the JSON parameter of a JSON Generator component that receives the following payload:

{
  "name" : "John Doe",
  "age" : null
}

You can use the DEFAULT function to replace the null value with a "not available" string.

{
  "name" : "John Doe",
  "age" : {{ DEFAULT(message.age, "not available") }}
}

The expected result is:

{
  "name" : "John Doe",
  "age" : "not available"
}

Read this article to learn more about referencing data with Double Braces.

TOSTRING

Converts an object to its string representation.

Syntax

TOSTRING(object: any) -> string

• object: the object to be converted to a string. It can be of any type.

Usage example

{{ TOSTRING(123) }}

The expected result is:

"123"

RANDOMSTRINGS

Generates random strings given a charset and string length.

Syntax

RANDOMSTRINGS(charset: string, length: int) -> string

• charset: the charset to be used. Options are: "ALPHANUMERIC", "ALPHABETIC", "ASCII", and "NUMERIC".

• length: the length of the output string.

Usage example

{{ RANDOMSTRINGS("ALPHANUMERIC",10) }}

The output varies because it is random. One possible output is:

"lUbCIs7T3G"