IMPORTANT: This documentation has been discontinued. Read the updated String Functions documentation on our new documentation portal.
The functions were created to:
speed up the creation of your integrations even more
decrease the complexity of your pipelines
simplify data conversions and transformations during the flow of your pipelines
The string functions make string treatments, operations and conversions and are available for components that support Double Braces expressions. To know how to provide information to the components using this resource, click here.
CAPITALIZE
This function in Double Braces capitalizes a string when changing the first character to lowercase. The other characters aren't changed.
Syntax
CAPITALIZE(value:string)
Let's say you need to capitalize a string. You can do the following:
{
"name": {{ CAPITALIZE("hi, my name is jacob") }}
}
The expected result will be:
{
"name": "Hi, my name is jacob"
}
CONCAT
By using Double Braces, you can combine the function with the access to the input JSON element of a component.
The function is applied to concatenate parameters and transform them into a string.
Syntax
CONCAT(, , )
Rules
at least 2 parameters are necessary
concatenate null is the same as concatenating "" (empty string)
concatenation always returns string
the fieldX can be of any data type, which will be converted into string in the concatenation
See a simple example below:
Input of a Transformer component
{
"name": "test",
"id": " - 123",
"a": null,
"b": {
"name": "qwert",
"id": "yuiop"
},
"c": -89912
}
Use of the CONCAT function:
{
"concat": {{ CONCAT(message.name, message.id, message.a, message.b, message.c) }}
}
ESCAPE
By using Double Braces, you can combine the function with the access to the input JSON element of a component.
The function is applied to the characters that need an escape even after the conversion to another element. It must be used, for example, when it's desirable to persist on a JSON object that is in string format in a database.
Syntax
ESCAPE(value:string, escapeType:string<optional>)
See a simple example below:
{
"jsonString": "{\"a\": 1,\"b\": 2}"
}
The function can be applied for an escape:
{
"text": {{ ESCAPE(message.jsonString) }}
}
Furthermore, it’s possible to specify the type of escape that should be applied through the optional escapeType parameter. In it, the values "CSV", "HTML", "JSON" and "XML" are accepted. If the parameter isn’t informed, the value "JSON" will be assumed by default.
Let's say you have the object below and need to escape a text in CSV format:
{
"text": "John,33,\"São Paulo\",Brazil,true"
}
To do this, just call the function as follows:
{
"text": {{ ESCAPE(message.text, "CSV") }}
}
The result of executing the function will be as follows:
{
"text": "\"John,33,\"\"São Paulo\"\",Brazil,true\""
}
For the other types, the application of the function is the same depending only on the type of text to be treated. If some type of escape not expected by the function is informed, an exception will be thrown.
UNESCAPE
By using Double Braces, you can combine the function with the access to the input JSON element of a component.
The function is applied to remove the escape contained in the characters of a text. It can be used, for example, when a JSON object that is persisted in a database in string format must be read.
Syntax
UNESCAPE(value:string, escapeType:string<optional>)
See a simple example below:
{
"jsonString": "{\\\"a\\\": 1,\\\"b\\\": 2}"
}
The function can be applied for a UNESCAPE:
{
"text": {{ UNESCAPE(message.jsonString) }}
}
Furthermore, it’s possible to specify the type of escape that should be removed through the optional escapeType parameter. In it, the values "CSV", "HTML", "JSON" and "XML" are accepted. If the parameter isn’t informed, the value "JSON" will be assumed by default.
Let's say you have the object below and need to remove the escape of a text in CSV format:
{
"text": "\"John,33,\"\"São Paulo\"\",Brazil,true\""
}
To do this, just call the function as follows:
{
"text": {{ UNESCAPE(message.text, "CSV") }}
}
The result of executing the function will be as follows:
{
"text": "John,33,\"São Paulo\",Brazil,true"
}
For the other types, the application of the function is the same depending only on the type of text to be treated. If some type of escape not expected by the function is informed, an exception will be thrown.
INDEXOF
This function in Double Braces returns the index inside the first occurrence of a string referent to a specified substring.
Syntax
INDEXOF(str: string, strSearch: string, fromIndex:integer<optional>)
Let’s say you need to search the value "planet" inside the string "Hello planet earth, you are a great planet." and want to know the start index of this occurrence:
{{ INDEXOF("Hello planet earth, you are a great planet.", "planet") }}
The result will be: 6
If you need to search in a string from a determined index:
{{ INDEXOF("Hello planet earth, you are a great planet.", "tree", 3) }}
In the case above, you’re searching from the index 3. As no value will be found with the provided specifications, then -1 will be returned1.
JOIN
This function in Double Braces returns a new string composed of copies of the united elements with a copy of the specified delimiter.
Syntax
JOIN(delimiter:string, value1:string, value2:string, ...., valueN:string)
delimiter: delimiter to be incorporated by each string
values: string to be united
Let's say you need to unite some strings with a delimiter. You can do the following:
{
"test": {{ JOIN("-", "I", "love", "this", "function") }}
}
The expected result will be:
{
"test": "I-love-this-function"
}
LASTINDEXOF
string to be located. The function returns the index number in which the sequence begins, searches characters from the string end to its beginning and returns -1 if the character isn’t found. The last occurrence of the empty string ("") is considered an index value.
Syntax
LASTINDEXOF(str: string, strSearch: string, fromIndex:integer<optional>)
Let’s say you want to search the value “planet” inside the string "Hello planet earth, you are a great planet." and want to know what the start index of this occurrence is:
{{ LASTINDEXOF("Hello planet earth, you are a great planet.", "planet") }}
The result will be: 36
LEFTPAD
This function in Double Braces adds fillings to the left of a string with a specified string.
Syntax
LEFTPAD(value:string, size:number, [padding:string - optional])
value: string to be filled
size: total size of the filling /string to be filled
padding: character of the filling (optional)
Let's say you need to add a filling to the left of a string. You can do the following:
{
"test": {{ LEFTPAD("xpto", 10, "-") }}
}
The expected result will be:
{
"test": "------xpto"
}
IMPORTANT: if you don't specify the "padding" parameter, then the filling will be made with a blank space.
LOWERCASE
By using Double Braces, you can combine the function with the access to the input JSON element of a component.
The function is applied to return the string value in lowercase.
Syntax
LOWERCASE(string)
{
“a”: "2AAA"
}
{
"lc": {{ LOWERCASE( message.a ) }}
}
The return of this function will be 2aaa.
MATCHES
By using Double Braces, you can combine the function with the access to the input JSON element of a component.
The function searches through all the strings, which means, the pattern (regex) that you're searching must be exactly the same as the string being used to the search.
Syntax
MATCHES(string, regex )
Let's say you need to know if the field is in the valid "zip code" format:
{
"zip code": "72716"
}
In the example below the "true" value will be returned, because it matches with the provided regex:
{
"zipcodeValid": {{ MATCHES( message.zip-code, "[0-9]{5}-[0-9]{3}" ) }}
}
The return of this function will be "true" or "false".
NORMALIZE
This function in Double Braces normalizes a sequence of values in characters.
Syntax
NORMALIZE(value:string)
value: string to be normalized
Let's say you need to normalize a string. You can do the following:
{
"test": {{ NORMALIZE("àèìòùęëæoœçáíéúūãõ") }}
}
The expected result will be:
{
"test": "aeioueeocaieuuao"
}
REPLACE
By using Double Braces, you can combine the function with the access to the input JSON element of a component.
The function substitutes each substring of the string that corresponds to the regular expression provided with the substitution you want to make.
Syntax
REPLACE(value, "regExp", "new-value")
regExp: regular expression to be informed as string
The result will be a string or null.
See a simple example below:
{
"string": "ABCDabcd",
"object": {
"this is an object": true
},
"text": "this is a test" ,
"accents": "ÁÂÃáâãÉéíÌÍÓóÛÙúÇç"
}
Application example:
{
"replace_simple": {{REPLACE(message.string, "[A-Z]", ".")}},
"replace_object": {{REPLACE(message.object, "\\\"", "'")}},
"replace_text": {{REPLACE(message.text, "a test", "my test")}},
"accents": {{ REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(message.XML,"[\\xE0-\\xE6]", "a"),"[\\xC0-\\xC6]", "A"),"[\\xE8-\\xEB]", "e"),"[\\xC8-\\xCB]", "E"),"[\\xEC-\\xEF]", "i"),"[\\xCC-\\xCF]", "I"),"[\\xF2-\\xF6]", "o"),"[\\xD2-\\xD6]", "O"),"[\\xF9-\\xFC]", "u"),"[\\xD9-\\xDC]", "U"),"\\xE7", "c"),"\\xC7", "C") }}
}
}
RIGHTPAD
This function in Double Braces adds fillings to the right of a string with a specified string.
Syntax
RIGHTPAD(value:string, size:number, [padding:string - optional])
value: string to be filled
size: size of the filling
padding: character of the filling (optional)
Let's say you need to add a filling to the right of a string. You can do the following:
{
"test": {{ RIGHTPAD("xpto", 10, "-") }}
}
The expected result will be:
{
"test": "xpto------"
}
If you don't specify the "padding" parameter, then the filling will be made with a blank space.
SPLIT
This function in Double Braces divides a string according to the specified regular expression (regex).
Syntax
SPLIT(value:string, regex:string)
value: string to be normalized
regex: delimiting regular expression
Let's say you need to divide a string with a regex. You can do the following:
{
"test": {{ SPLIT("aaa,bbb", ",") }},
"test2": {{ SPLIT("123,abb", "\\.") }}
}
The expected result will be:
{
"test": ["aaa", "bbb"],
"test2": ["123", "abb"]
}
SUBSTRING
This function in Double Braces returns a string derived from its own substring. The substring begins in the specified "beginIndex" and goes until the character in the "endIndex" index.
Syntax
SUBSTRING(value:string, beginIndex:number, [endIndex:number - optional], throwIndexOutOfBoundError:boolean - optional])
value: string
beginIndex: initial index, inclusive
beginIndex: final index, exclusive (optional)
throwIndexOutOfBoundError: if "true", an exception will be thrown if there's some index out of the linked exception; otherwise, the provided string will be returned - "true" is standard (if "beginIndex" is negative, or "endIndex" is greater than the size of the string object, or "beginIndex" is greater than "endIndex", an exception will be thrown)
Let's say you need to extract a substring from a string. You can do the following:
{
"test": {{ SUBSTRING("aaS2fdeS", 3) }},
"test2": {{ SUBSTRING("aaS2fdeS", 3, 5) }},
"test3": {{ SUBSTRING("qqq", 20, 30, false) }}
}
The expected result will be:
{
"test": "2fdeS",
"test2": "2f",
"test3": "qqq"
}
For these cases, an exception will be thrown:
{{ SUBSTRING("qqq", 20, 30) }} or {{ SUBSTRING("qqq", 20, 30, true) }}
or
{{ SUBSTRING("qqq", 20, null, false) }}
TOSTRING
This function in Double Braces converts anything to a string format.
Syntax
TOSTRING(value:any)
value: value to be converted to string
Let's say you need to convert a value to string. You can do the following:
{
"number": {{ TOSTRING(1) }},
"string": {{ TOSTRING("A") }},
"boolean": {{ TOSTRING(false) }},
"null": {{ TOSTRING(null) }}
}
The expected result will be:
{
"number": "1",
"number": "A",
"number": "false",
"number": ""
}
It's also possible to convert an array or object to string.
UPPERCASE
By using Double Braces, you can combine the function with the access to the input JSON element of a component.
The function is applied to return the string value in uppercase.
Syntax
UPPERCASE(string)
{
“a”: "2aaa"
}
{
"uc": {{ UPPERCASE( message.a ) }}
}
The return of this function will be 2AAA.
CONTAINS
This function allows you to verify if a specific value is contained in a string.
Syntax:
CONTAINS(string, value)
Let's say you need to verify if the following string contains the value "function":
{
"field": "Testing the new function CONTAINS()"
}
Verifying:
{
"contains": {{ CONTAINS(message.field, "function") }}
}
The result will be:
{
"contains": true
}
RANDOMSTRINGS
This function allows you to generate random strings based on a charset and size.
Syntax:
RANDOMSTRINGS(charset, size)
Let's say you need to generate random strings based on different charsets and with a size of 20 characters.
Generating the strings:
{
"alphanumeric": {{ RANDOMSTRINGS("ALPHANUMERIC", 20) }},
"ascii": {{ RANDOMSTRINGS("ASCII", 20) }},
"numeric": {{ RANDOMSTRINGS("NUMERIC", 20) }},
"alphabetic": {{ RANDOMSTRINGS("ALPHABETIC", 20) }}
}
The result will be:
{
"alphanumeric": "Oj3DApYQL7uTCodbXlXq",
"ascii": "GV>o8G/pNFofal.A.14X",
"numeric": "02747673464573026135",
"alphabetic": "bOHtZafvGOpdltVrrcEu"
}
The available charsets are ALPHANUMERIC, ASCII, NUMERIC and ALPHABETIC, and the string size limit is 1000 characters.
STRINGMATCHES
This function allows you to search for values within a String based on a Regex, returning the results found within an array.
Syntax:
STRINGMATCHES(value: string, regex: string, flagPattern: string)
value: string to be filled
regex: will be used in the search
patternFlag: flag that can set a pattern for the regex match (optional)
Note: the function accepts more than one patternFlag, if you want you can pass all you want in the last parameters of the function, as an example below:
STRINGMATCHES(Hello eDUcative, educative # Matching the keyword educative, “CASE_INSENSITIVE”, “COMMENTS”)
Notice: Below is the table of valid patternFlags.
CANON_EQ
Enables canonical equivalence.
CASE_INSENSITIVE
Enables case-insensitive matching.
COMMENTS
Allows blank spaces and comments in the pattern.
DOTALL
Activate dot mode.
LITERAL
Enables literal parsing of the pattern.
MULTILINE
Enables multiline mode.
UNICODE_CASE
Enables case-folding with unicode recognition.
UNICODE_CHARACTER_CLASS
Enables the 'unicode' version of predefined character classes and posix character classes.
UNIX_LINES
Enables Unix lines mode.
Let's say you want to do the searches below.
Generating the strings:
{
"normal": {{ STRINGMATCHES("7801111111blahblah 780222222 mumbojumbo7803333333 thisnthat 7804444444", "780{1}\\d{7}") }},
"case_sensitive": {{ STRINGMATCHES("For more information, see Chapter 3.4.5.1", "(chapter \d+(\.\d)*)") }},
"case_insensitive": {{ STRINGMATCHES("For more information, see Chapter 3.4.5.1", "(chapter\d+(\.\d)*)", "CASE_INSENSITIVE") }}
}
The result will be:
{
"normal": [ "7801111111", "7803333333", "7804444444" ],
"case_sensitive": [],
"case_insensitive": ["Chapter 3.4.5.1"]
}
Note: If the regex to be used has backslash (\), a scape is required by adding another backslash. The following example follows:
Original Regex:
(chapter \d+(\.\d)*)
Regex with scape:
(chapter \\d+(\\.\\d)*)
You can also read about these functions: