Extract and Format Numbers

These functions provide tools that interpret numeric values. Many of these functions return information as an integer, which can be further evaluated with mathematical operations.

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

ecx:formatNumber

The function ecx:formatNumber formats a number based on the specified variables. The value returned is a string data type.

Examples

Structure

ecx:formatNumber(string1, string2, string3)

Parameters

ecx:forceNumber

The function ecx:forceNumber parses numbers in a string attribute as an actual number. Use it together with ecx:formatNumber.

Function Logic

• If string_or_number is null:
  > return 0

• else if string_or_number is numeric:
  > return string_or_number

• else if string_or_number is convertible to numeric after replacing any , to . to ensure compatibility with different decimal separators:
  > return numeric converted value with . as decimal separator

• else:
  > return 1

• end if

Examples

Structure

ecx:forceNumber(string)

Example in combination with ecx:formatNumber:

<%${ecx:formatNumber(ecx:forceNumber(user.CustomAttribute['Price']), '#,##0.00', '')}%>

ecm:round

The function ecm:round rounds the target number to the specified number of fractional digits. The value returned is a number.

Example

An external application regularly updates the prices of items in a product catalog. The application calculates currency conversions to values with four decimal places. These values are imported into an unlinked related data set named Products.

Prices from this data set are inserted into a message, rounding the number to two decimal places. The expression is constructed as follows:

<%${ecm:round(ecx:related('Products', user.CustomAttribute['ProductID_2'])['Price'], 2)}%>

Structure

ecm:round(number, integer)

Parameters

Mathematical Operations (General)

A full range of mathematical operations can be used in association with functions. Mathematical operations return numbers as results. If any non-numeric values are subjected to mathematical operations (for example, a string), the non-numeric value is returned unmodified. Calculations that contain more than one arithmetic operation use the standard order of operations. For example, the calculation ${10+15*3-5} returns a value of 50.

Example

The custom attribute AtbNumber is assigned a numeric data type.

When the value stored in AtbNumber is 5, the following expression returns a numeric value of 15:

<%${user.CustomAttribute['AtbNumber']*4-5}%>

ecm:max

The function ecm:max returns the maximum value from the specified arguments. Only arguments with numeric data types are evaluated. Null arguments or non-number data types are ignored. The value returned is an object type.

Example

${ecm:max(6,10,8)}

This returns 10.

Structure

ecm:max(object...)

Parameters

ecm:min

The function ecm:min returns the minimum value from the specified arguments. Only arguments with numeric data types are evaluated. Null arguments or non-number data types are ignored. The value returned is an object type.

Example

${ecm:min(6,10,8)}

This returns 6.

Structure

ecm:min(object...)

Parameters

ecm:avg

The function ecm:avg returns the average value from the specified arguments. Only arguments with numeric data types are evaluated. Null arguments or non-number data types are ignored. The value returned is an object type.

Example

${ecm:avg(6,10,8)}

This returns 8.

Structure

ecm:avg(object...)

Parameters

ecm:random

The function ecm:random returns a random positive integer between two integers. The result can include the values used to define the upper and lower ranges. The value returned is an integer data type.

Example

${ecm:random(3, 6)}

This returns an integer value from the range 3 to 6, for example, 5.

Structure

ecm:random(integer, integer)

Parameters

Note

If either parameter is entered as a negative integer or the lower range value is greater than the upper range, the function returns a value of -1.

ecx:distribute

The function ecx:distribute generates a random result according to the standard uniform distribution. The parameters define the ratio of the probability that the result returns the value true. The value returned is a Boolean data type.

Example

A message contains a personalized message which includes a special offer. The offer is only visible to a percentage of randomly selected recipients.

The expression that inserts personalization into a message is constructed as follows:

<%InsertIf expression="${ecx:distribute(1,5)}" id="name"%>Text1<%/InsertIf%>

In this example, there is a 20% (1 in 5) chance that personalization is displayed in the message.

The ID assigned to the personalization identifies the variation in the statistics and helps measure the performance of messages sent with the personalized message part.

Note

The ID assigned to the personalization in the expression is limited to 35 characters.

Structure

ecx:distribute(integer, integer)

Parameters