---
title: "Format and Encode Strings"
slug: "format-and-encode-strings"
description: "Mapp Engage functions that change the case of strings, trim, replace, and concatenate them, and encode them for links and HTML."
status: "update"
updated: 2026-11-04T12:17:26Z
published: 2026-11-04T12:17:26Z
canonical: "docs.mapp.com/format-and-encode-strings"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Format and Encode Strings

These functions format, convert, and encode strings. They return a string which can be displayed in a message or evaluated with operators in personalization rules or selections.

The functions change the value only for the output or the query. The data stored in the source is not changed.

---

## Function Overview

| Function | Description |
| --- | --- |
| `ecm:base64Encode` | 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. |
| `fn:escapeXml` | Escapes characters that could be interpreted as XML or HTML markup. |
| `fn:replace` | Replaces all occurrences of a string in a target with a specified string. |
| `fn:toLowerCase` | Converts all of the characters in a string to lowercase for the purpose of performing a query. |
| `fn:toUpperCase` | Converts all the characters of a string to upper case for the purpose of performing a query. |
| `fn:trim` | Removes leading and trailing white space, tabs, and linefeed characters from a string. |
| `ecx:capitalizeFirstLetter` | Converts the first letter of a string to upper case. |
| `ecx:capitalizeWords` | Converts the first letter of every word in a string to upper case. |
| `ecm:concat` | Concatenates the specified string values. |
| `ecm:urlEncode` | Encodes the specified object for use in a URL. |
| `ecm:urlEncodeUsingCharset` | Encodes the specified object for use in a URL, using the specified character set. |

---

## ecm:base64Encode

The function `ecm:base64Encode` encodes a string in Base64, for example a personalized value in a link. After encoding, the value (for example, the contact's last name) is not directly readable, but the target website can decode it. The value returned is a string data type.

### Example

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

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

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

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

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

This link resolves to the following example URL: `https://website.com/shop/U21pdGg=`

### Structure

`ecm:base64Encode(string)`

### Parameters

| Parameter | Description |
| --- | --- |
| `string` | Specifies the target string. |

---

## fn:escapeXml

The function `fn:escapeXml` escapes characters that could be interpreted as XML or HTML markup, for example `&lt;`, `&gt;`, and `&amp;`. The value returned is a string data type.

### Example

A custom attribute stores free text that contacts entered in a form. Before the value is inserted into the HTML of a message, markup characters are escaped so that they are displayed as text:

```plaintext
<%${fn:escapeXml(user.CustomAttribute['Comment'])}%>
```

### Structure

`fn:escapeXml(string)`

### Parameters

| Parameter | Description |
| --- | --- |
| `string` | Specifies the target string. |

---

## 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:

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

### Structure

`fn:replace(string, string, string)`

### Parameters

| Parameter | Description |
| --- | --- |
| `string` | Specifies the target string. |
| `string` | Specifies the value to replace in the target string. |
| `string` | Specifies the value that replaces the string given in the previous parameter. |

---

## 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, for example "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:

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

### Structure

`fn:toLowerCase(string)`

### Parameters

| Parameter | Description |
| --- | --- |
| `string` | Specifies the target string. |

---

## 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, for example "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:

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

### Structure

`fn:toUpperCase(string)`

### Parameters

| Parameter | Description |
| --- | --- |
| `string` | Specifies the target string. |

---

## 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:

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

### Structure

`fn:trim(string)`

### Parameters

| Parameter | Description |
| --- | --- |
| `string` | Specifies the target string. |

---

## 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:

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

### Structure

`ecx:capitalizeFirstLetter(string)`

### Parameters

| Parameter | Description |
| --- | --- |
| `string` | Specifies the target string. |

---

## 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:

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

### Structure

`ecx:capitalizeWords(string)`

### Parameters

| Parameter | Description |
| --- | --- |
| `string` | Specifies the target string. |

---

## 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:

```plaintext
${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:

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

### Structure

`ecm:concat(string...)`

### Parameters

| Parameter | Description |
| --- | --- |
| `string` | Specifies the target string to concatenate. Additional target strings are added as a list, separated by commas. |

---

## ecm:urlEncode

The function `ecm:urlEncode` encodes the specified object for use in a URL. Spaces and special characters in the value are converted so that they do not break the link. The value returned is a string data type.

### Example

A registration link passes the last name of the recipient to the registration page. URL encoding ensures that last names with spaces (de la Hoya) or special characters (Nuñez) do not break the link:

```plaintext
<a href="https://www.example.com/register?name=<%${ecm:urlEncode(user['LastName'])}%>">Register</a>
```

To encode the value with a specific character set, use `ecm:urlEncodeUsingCharset`.

### Structure

`ecm:urlEncode(object)`

### Parameters

| Parameter | Description |
| --- | --- |
| `object` | Specifies the target object to encode. |

---

## ecm:urlEncodeUsingCharset

The function `ecm:urlEncodeUsingCharset` encodes the specified object for use in 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:

```plaintext
<a href="https://www.example.com/register?name=<%${ecm:urlEncodeUsingCharset(user['LastName'], 'ISO-8859-15')}%>">Register</a>
```

### Structure

`ecm:urlEncodeUsingCharset(object, string)`

### Parameters

| Parameter | Description |
| --- | --- |
| `object` | Specifies the target object to encode. |
| `string` | Specifies the character set used to encode the target object. |