Extract and Format Strings

These functions copy the information contained in a target source. They return this information as a text string which can be displayed in a message or evaluated with operators and used in personalization rules or selections. Modifications to the extracted values are made for the purposes of the query only. The actual data stored in the target source is not changed in any way.

Function Overview

ecm:base64Encode

The function ecm:base64Encode encodes a string within a link parameter.

Use this function to encode a recognizable string within a personalized link. After encoding, the personalized string (for example, the contact's first or last name) is not readable.

The function ensures that the personalized value is not directly readable, but can be interpreted by the target website.

Example

Without encoding, a personalized HTML link has the following format:

<a href="">Shop'>https://website.com/shop/<%${user['LastName']}%>">Shop Now!</a>

This link resolves to the following example URL: www.website.com/shop/Smith

With the base64 encoding function, a personalized HTML link has the following format:

<a href="">Shop'>https://website.com/shop/<%${ecm:base64Encode(user['LastName'])}%>">Shop Now!</a>

This link resolves to the following example URL: www.website.com/shop/S2F0aGFyaW5h

Structure​

ecm:base64Encode(string)

Parameters​

​fn:replace​

The function fn:replace replaces all occurrences of a string in a target with a specified string. The value returned is a string data type.

Example

Values saved in a group attribute include underscores. When these values are inserted into a message, the underscore characters are replaced by a space.

The expression for inserting these values into a message is constructed as follows:

<%${fn:replace(group.CustomAttribute['Name'],'_', ' ')}%>

Structure​

fn:replace(string, string, string)

Parameters​

​fn:toLowerCase​

The function fn:toLowerCase converts all of the characters in a string to lower case for the purpose of performing a query. The actual source string is not changed in any way. The value returned is a string data type.

Example

The custom attribute ​user.CustomAttribute['job title']​ contains any number of possible job titles. When the list used to populate this data was created, the spelling of these values was not verified. The values stored in the attribute contain variations in capitalization, e.g., 'MANAGER", 'manager' and 'Manager'.

All recipients with 'manager' (any case) will receive a special text in their email.

The function fn:toLowerCase is used to convert all values in the target attribute to lower case. This result is then compared to specified value manager using the operator ​==​ to convert the resulting string into a Boolean value. The text is inserted into the message using an ​InsertIf​ statement, which is constructed as follows:

<%InsertIf expression="${((fn:toLowerCase(user.CustomAttribute['job title'])=='manager'))}"%>Text<%/InsertIf%>

Structure​

fn:toLowerCase(string)

Parameters​

​fn:toUpperCase​

The function fn:toUpperCase converts all the characters of a string to upper case for the purpose of performing a query. The actual source string is not changed in any way. The value returned is a string data type.

Example

The custom attribute user.CustomAttribute['job title']​ contains any number of possible job titles. When the list used to populate this data was created, the spelling of these values was not verified. The values stored in the attribute contain variations in capitalization, e.g., 'MANAGER", 'manager' and 'Manager'.

All recipients with 'manager' (any case) will receive a special text in their email.

The function fn:toUpperCase is used to convert all values in the target attribute to upper case. This result is then compared to the specified value MANAGER using the operator ​==​ to convert the resulting string into a Boolean value. The text is inserted into the message using an ​InsertIf​ statement, which is constructed as follows:

<%InsertIf expression="${((fn:toUpperCase(user.CustomAttribute['job title'])=='MANAGER'))}"%>Text<%/InsertIf%>

Structure​

​fn:toUpperCase(string)​

Parameters​

​fn:trim​

The function fn:trim removes leading and trailing white space, tabs, and linefeed characters from a string. The value returned is a string data type.

Example

The data imported from an older source had not been cleaned up and contained white spaces. The values must be cleaned up before being evaluated in an expression.

The data was imported to a member attribute named remarks. The function for removing the white space is constructed as follows:

${fn:trim(user.MemberAttribute['remarks'])}

Structure​

fn:trim(string)

Parameters​

​ecx:capitalizeFirstLetter​

The function ecx:capitalizeFirstLetter converts the first letter of a string to upper case. The value returned is a string data type.

Example

Today's date, including the day of the week, is inserted into a message. The day of the week appears as the first word in the phrase and must be capitalized. This element is not capitalized by default in French.

The function ecx:formatDate formats the date in French, and ecx:capitalizeFirstLetter corrects the capitalization. The expression that inserts the result into a message is constructed as follows:

<%${ecx:capitalizeFirstLetter(ecx:formatDate(date.today, 'EEEE d MMMMM yyyy', ecm:timeZone('Europe/London'), 'fr', true))}%>

Structure​

ecx:capitalizeFirstLetter(string)

Parameters​

​ecx:capitalizeWords​

The function ecx:capitalizeWords converts the first letter of every word in a string to upper case. The value returned is a string data type.

Example

The customer's last travel destination is stored in a custom attribute. This value is stored in lower-case text. To use this value in a message, the text string must be formatted correctly. The function ​ecx:capitalizeFirstLetter​ does not correct the capitalization for city names with more than one word, for example, San Diego.

The following example uses the ​ecx:capitalizeWords​ function to format the city names and insert them in a message:

<%${ecx:capitalizeWords(user.CustomAttribute['Last Destination'])}%>

Structure​

ecx:capitalizeWords(string)

Parameters​

​ecm:concat​

The function ecm:concat concatenates the specified string values. The value returned is a string data type.

Example

Values stored in a group attribute represent prices for accommodations in various cities. Prices are saved as fractional numbers to two decimal places. When the price of a hotel in London is inserted into a message, the decimal values are replaced with a dash and preceded by the pound sign (i.e. 255.85 is converted to £255.-). The function fn:substringBefore extracts the value before the decimal point from the attribute ​Rate_London​ as follows:

${fn:substringBefore(group.CustomAttribute['Rate_London'], '.')}

The currency symbol and dash are added to the result using the function ecm:concat. The expression for adding the special characters and inserting the extracted value into a message is constructed as follows:

<%${ecm:concat('£', fn:substringBefore(group.CustomAttribute['Rate_London'], '.'), '.-')}%>

Structure​

ecm:concat(string...)

Parameters​

​ecm:toDate​

The function ecm:toDate converts a target string or value into a date data type. The value returned is a date data type.

This function is often used to convert values to dates for use with functions that require date data types in parameters.

Example

A selection determines whether recipients who are near retirement age receive a message. The segment criteria compare the date of birth stored as an attribute value to a specific date (1 January 1950). In order to compare the two dates using the function ecm:less, both values must be date data types. The function ecm:toDate converts the string '1950-01-01' into a date data type so it can be compared with the date stored in the recipient attribute ​user['DateofBirth']​. The combined functions are constructed as follows:

${ecm:less(user['DateOfBirth'], ecm:toDate('1950-01-01', ecm:timeZone('Europe/Berlin')))}

Structure​

ecm:toDate(string, timezone)

Parameters​

​ecm:urlEncode​

The function ecm:toDate converts a target string or value into a date data type. The value returned is a date data type.

This function is often used to convert values to dates for use with functions that require date data types in parameters.

Example

A selection determines whether recipients who are near retirement age receive a message. The segment criteria compare the date of birth stored as an attribute value to a specific date (1 January 1950). In order to compare the two dates using the function ecm:less, both values must be date data types. The function ecm:toDate converts the string '1950-01-01' into a date data type so it can be compared with the date stored in the recipient attribute ​user['DateofBirth']​. The combined functions are constructed as follows:

${ecm:less(user['DateOfBirth'], ecm:toDate('1950-01-01', ecm:timeZone('Europe/Berlin')))}

Structure​

ecm:toDate(string, timezone)

Parameters​

ecm:urlEncodeUsingCharset​

The function ecm:urlEncodeUsingCharset encodes the specified object as a URL using the specified character set. The value returned is a string data type.

Example

A registration link is included in a message that takes the information stored in the recipient attribute user.LastName and passes it as a variable to the registration page. The message itself is encoded using the ISO-8859-15 character set.

URL encoding ensures that last names with spaces (de la Hoya, van der Waal) or special characters (Nuñez, Köhl) do not break the link.

The HTML for inserting the link in a message is constructed as follows:

<a href="http://host/cmd.jsp?user=<%${ecm:urlEncodeUsingCharset(user['LastName']), 'ISO-8859-15'}%>">Register</a>

Structure​

ecm:urlEncodeUsingCharset(object, string)

Parameters​