Skip to main content

Functions used in merge fields

Zuora

Functions used in merge fields

The HTML Templates feature is in the Early Adopter phase for invoices. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. If you want to join this early adopter program, submit a request at Zuora Global Support.

When customizing invoice HTML templates, you can decorate merge fields with filter, aggregator, and formatter functions. These functions can not exist alone. You have to use them together with a data field, for example:

{{Invoice.Amount|Localise}}

The Localise function has to be used with a numeric data field Invoice.Amount. A pipe "|" is used between the data field and the decorator function.

Supported filter functions

You can use filter functions to take in a list and output a list of filtered records.

The following table lists the filter functions that you can decorate merge fields with when customizing invoice HTML templates.

Function

Description

Examples

Notes

FilterByValue(FieldName,Operator,Value)

This function filters input data based on the specified argument fields.

You can decorate the FieldName argument. 

This function supports the following operators: 

  • LT: less than

  • LE: less than or equal to

  • GT: greater than

  • GE: greater than or equal to

  • EQ: equal to

  • NE: not equal to


 

You can decorate the FieldName argument. For example, if you want to filter all invoice items by comparing the 0 - 7 substring of their service start date with 2021-01, you can use the following function:

InvoiceItems|FilterByValue(ServiceStartDate|Substr(0,7),EQ,2021-01)

You can specify the FieldName argument to be dotted paths, but the first part must be an attribute of the input object. For example, in the InvoiceItems|FilterByValue(RatePlanCharge.ChargeType,EQ,OneTime) function, RatePlanCharge is a valid field of the InvoiceItems object. 

You can quote the Value argument, but the value cannot contain the dot character ".". If the value contains the following characters, you have to escape (URL Encoding) them:

  • whitespace ' ': %20

  • comma ',':  %2C

  • Left curly brackets '{': %7B

  • Right curly brackets '}': %7D

FilterByRef(FieldName,Operator,RefAttributeName>)

This function filters input data based on the specified RefAttributeName argument.

You can decorate the FieldName argument. 

This function supports the following operators: 

  • LT: less than

  • LE: less than or equal to

  • GT: greater than

  • GE: greater than or equal to

  • EQ: equal to

  • NE: not equal to

InvoiceItem can be the regular charges and the discount charges, for a discount charge, it has an AppliedToInvoiceItemId pointing to a regular invoice item. This linkage gives us chance to show the inline discount by using FilterBy
Ref function together with Cmd_Assign.

{{#InvoiceItems|FilterByValue(ProcessingType,EQ,0)}}

{{Cmd_Assign(RegularItemId,Id)}}

{{ChargeName}} - {{ChargeAmount}}

{{#InvoiceItems|FilterByRef(AppliedToInvoiceItemId,EQ,RegularItemId)}}

 * {{ChargeName}} - {{ChargeAmount}}

{{/InvoiceItems|FilterByRef(AppliedToInvoiceItemId,EQ,RegularItemId)}}

{{/InvoiceItems|FilterByValue(ProcessingType,EQ,0)}}

This example is with two list sections. The first one InvoiceItems|FilterByValue(ProcessingType,EQ,0) returns all the regular invoice items, 

And for each regular invoice item, we use Cmd_Assign(RegularItemId,Id) to give Id an alias RegularItemId.

The second list section InvoiceItems|FilterByRef(AppliedToInvoiceItemId,EQ,RegularItemId) basically is to filter all the invoice items by condition of AppliedToInvoiceItemId = RegularItemId, therein, AppliedToInvoiceItemId is an attribute of its input data InvoiceItems, and RegularItemId is defined in the outer object, aka, the object in the first list section.

If the current object does not have any RefAttributeName property, its outer object in the stack context will be used for searching, until the property is found.

GroupBy(FieldName,FieldName){0..2})

This function takes in a list, and groups the records by the argument fields.

Assume that an input list is as follows:

[
{
  "ChargeName": "C-000001",
  "ChargeAmount": 10,
  "ServiceStartDate": "2021-01-01"
},
{
  "ChargeName": "C-000001",
  "ChargeAmount": 15,
  "ServiceStartDate": "2021-02-01"
},
{
  "ChargeName": "C-000002",
  "ChargeAmount": 12,
  "ServiceStartDate": "2021-01-01"
},
{
  "ChargeName": "C-000002",
  "ChargeAmount": 8,
  "ServiceStartDate": "2021-03-01"
}
]

 

If you apply the GroupBy(ChargeName) function to the input list, it returns the following output in the rendering result:

[
  {
    "ChargeName": "C-000001",
    "_Group": [
        {
            "ChargeName": "C-000001",
            "ChargeAmount": 10,
            "ServiceStartDate": "2021-01-01"
        },
        {
            "ChargeName": "C-000001",
            "ChargeAmount": 15,
            "ServiceStartDate": "2021-02-01"
        }
    ]
  },
  {
    "ChargeName": "C-000002",
    "_Group": [
        {
            "ChargeName": "C-000002",
            "ChargeAmount": 12,
            "ServiceStartDate": "2021-01-01"
        },
        {
            "ChargeName": "C-000002",
            "ChargeAmount": 8,
            "ServiceStartDate": "2021-03-01"
        }
    ]
  }
]

 

From the preceding example, you can see how the input list is transformed. The object in the transformed list consists of two fields only:

  • GroupBy key field. For example, ChargeName.

  • _Group that is a hard-coded key for GroupBy use cases

If you specify multiple GroupBy fields in the function, the records in _Group will be transformed in the same way. For three levels of GroupBy fields, like Items|GroupBy(A,B,C) , the final output example is as follows:

[
{
    "A": "..",
    "_Group": [
        {
            "B": "..",
            "_Group": [
                {
                    "C": "..",
                    "_Group": [
                        {
                            "A": "..",
                            "B": "..",
                            "C": "..",
                            ...
                        }
                    ]
                }
            ]
        }
    ]
}
]

This function supports at most three arguments.

The FieldName argument must be a valid attribute of the input list object type. You can specify the FieldName argument to be dotted paths. 

For example, the InvoiceItems|GroupBy(RatePlanCharge.RatePlan.Name,ChargeName) function groups the invoice items by rate plan name first, and then by charge name for the records with the same rate plan name.

SortBy(FieldName,Direction(,FieldName,Direction){0..2})

This function sorts input data based on the specified argument fields.

This function supports the following directions: 

  • ASC: sorting data from the smallest to the largest

  • DESC: sorting data from the largest to the smallest


 

Assume that you want to show all the charges in order of service start date, to do that, you can:

{{#InvoiceItems|SortBy(ServiceStartDate,ASC)}}

{{ChargeName}} - {{ChargeAmount}} - {{ServiceStartDate}}

{{/InvoiceItems|SortBy(ServiceStartDate,ASC)}}

You can specify the FieldName argument to be dotted paths.

This function supports at most three pairs of field names and directions.

First(N)

This function returns the first N records of the input list.

You can use this function with the SortBy function to define the sorting order.

The InvoiceItems|First(5) function returns the first five invoice items in the rendering result based on the default sorting order.

If less than N records exist, this function returns the original list.

The value of N must be greater than or equal to 1.

Last(N)

This function returns the last N records of the input list.

You can use this function with the SortBy function to define the sorting order.

The InvoiceItems|Last(5) function returns the last five invoice items in the rendering result based on the default sorting order.

If less than N records exist, this function returns the original list.

The value of N must be greater than or equal to 1.

Map(FieldName|QuotedValue(,FieldName|QuotedValue)*)

You can apply a Map function to define an element as the input and the element’s attribute as the output, in the format of item -> item.FieldName.

  • The argument can be either a field name or a quoted value, either single or double quoted.

  • FieldName cannot be a dotted path.

  • The FieldName data type cannot be a list.  For example, InvoiceItems|Map(TaxationItems) is invalid.

  • If you specify only one argument, the Map function returns a list of fieldName values.

  • If you specify multiple arguments, the Map function returns a list of lists.

Assume that an InvoiceItems list is as follows:

[
{
  "ChargeName": "C-000001",
  "ChargeAmount": 10,
  "ServiceStartDate": "2021-01-01"
},
{
  "ChargeName": "C-000001",
  "ChargeAmount": 15,
  "ServiceStartDate": "2021-02-01"
},
{
  "ChargeName": "C-000002",
  "ChargeAmount": 12,
  "ServiceStartDate": "2021-01-01"
},
{
  "ChargeName": "C-000002",
  "ChargeAmount": 8,
  "ServiceStartDate": "2021-03-01"
}
]

 

The InvoiceItems|Map(ChargeName) function returns the following value in the rendering result: ["C-000001","C-000001","C-000002","C-000002"]

The InvoiceItems|Map(ChargeName,ChargeAmount) function returns the following value in the rendering result:

 [["C-000001", 10],["C-000001",15],["C-000002",12],["C-000002",8]]

You can also use quoted values as arguments. For example, the InvoiceItems|Map(ChargeName,'Charge') function returns the following value in the rendering result: [["C-000001","Charge"],["C-000001","Charge"],["C-000002","Charge"],["C-000002","Charge"]]

You can use the Uniq function to dedup the rendering result.

FlatMap(ListFieldName)

This function is similar to the Map function, except that FieldName has to be a list type.

Assume that an input of this function is as follows:

[
{
    "A": "...",
    "L": [
        {"B": "b1"},{"B": "b2"}
    ]
},
{
    "A": "...",
    "L": [
        {"B": "b3"}
    ]
}
]

 

The FlatMap(L) function returns the following output in the rendering result:

[
  {"B": "b1"},
  {"B": "b2"},
  {"B": "b3"}
]

/

Uniq

This function filters out the duplicate records in the list.

An invoice can be generated for multiple subscriptions, and according to the object model, the Subscription is linked on InvoiceItem, to get all the subscriptions of this invoice, you can do:

Invoice.InvoiceItems|Map(Subscription)

But the problem is that the result will contain duplicate records, since there are multiple invoice items for the same subscription.

To get an uniq list of subscription, you can simply append an Uniq function to the above:

Invoice.InvoiceItems|Map(Subscription)|Uniq

 

Supported aggregator functions

You can use aggregator functions to take in a list and return a scalar value or an object.

The following table lists the aggregator functions that you can decorate merge fields with when customizing invoice HTML templates.

Function

Description

Examples

Notes

Sum(FieldName)

This function adds up the values of FieldName of the object list. 

InvoiceItems|Sum(ChargeAmount) 

This example gives you the total charge amount of all invoice items in the rendering result.

FieldName must be a numeric field.

Size

This function returns the size of a list input.

InvoiceItems|Size

If the input is null, 0 is returned.

Min(FieldName)

This function returns the minimum record of the input list, compared by FieldName.

This function is the opposite of the Max(FieldName) function. 

InvoiceItems|Min(ServiceStartDate) 

This example gives you the oldest invoice item of the InvoiceItems object in terms of ServiceStartDate in the rendering result.

FieldName must be fields of comparable data types, for example:

  • Text

  • Number

  • Date/DateTime

  • Boolean

Max(FieldName)

This function returns the maximum record of the input, compared by FieldName

This function is the opposite of the Min(FieldName) function.

InvoiceItems|Max(ServiceStartDate) 

This example gives you the latest invoice item of the InvoiceItem object in terms of ServiceStartDate in the rendering result.

/

IsEmpty

This function tells you whether a list is empty. It returns True for an empty or null list, False for a non-empty list.

To check whether an account has any payment, you can use the following example:

Account.Payments|IsEmpty

 

Supported formatter functions

You can use formatter functions to take in a scalar type input and generate a scalar type value as output.

The following table lists the formatter functions that you can decorate merge fields with when customizing invoice HTML templates.

Function

Description

Examples

Notes

Substr(Begin,End)

This function takes in a text type input and returns a text value.

Arguments Begin and End are integers. The value of these arguments must follow the following formula:

0 <= Begin < End

/

If the input text length is less than End, the End value will be set to the length of the input list.

For example, if you define the function as Substr(0,10) but the input text has only six characters, all the six characters are considered as the input data.

Localise(locale_NAME)

This function formats the input data according to a locale setting. For example, you can use Invoice.Balance|Localise(en_US) to format invoice balances based on US English.

localise_NAME defines a language country code that is composed of two arguments separated by an underscore. For example, fr_CA indicates French Canadian.

  • The first argument is a valid ISO Language Code. These codes are the lower-case two-letter codes as defined by ISO-639. 

  • The second argument to both constructors is a valid ISO Country Code. These codes are the upper-case two-letter codes as defined by ISO-3166. 

See Supported languages in HTML invoice templates for an example list of locale names.

You can specify the locale name to override the default locale. The default locale is determined based on the following order:

  • Use the locale specified in the communication profile

  • Use the tenant locale if the communication profile specifies the locale as DEFAULT LOCALE.

For example, if the default locale is de_DE, the merge field examples and their outputs are as follows:

  • {{Invoice.InvoiceDate|Localise}}: 16/12/2021
  • {{Invoice.InvoiceDate|Localise(it_IT}}: 16.12.2021
  • {{Invoice.InvoiceDate|CreatedDate}}: 16.09.2021 02:26:07+08:00
 

You can specify the locale name to override the default locale. For example, if the default locale is de_DE, the merge field examples and their outputs are as follows: 

  • {{Amount|Localise}}: 1,234,567.89
  • {{Amount|Localise(fr_FR)}}: 1.234.567,89

This function works only for date, datetime, and numeric fields.

The localise_NAME input parameter is optional. 

If no input parameter is specified, the default locale is determined based on the following order:

  • Locale of the Communication Profile

  • Locale in the tenant setting.


 

EqualToVal(Value)

This function compares the input with the argument value, and returns a boolean value so that it can be used as a boolean section.

{{#Account.Status|EqualToVal(Active)}}
Handle Active Account
{{/Account.Status|EqualToVal(Active)}}

The input of this function must be a scalar value.

You can use EqualToVal(0) is used to compare numbers, and it has the same behavior as EqualToVal(0.00).

You can use EqualToVal("0") to compare strings.

IsBlank

This function checks whether the input text is null or blank.

To check whether the Description property of the Account object is blank, you can use the following merge field:

Account.Description|IsBlank

/

Symbol

This function converts a currency code to a currency symbol.

{{Account.Currency|Symbol}} {{Invoice.Balance|Localise}}

The output of the example can be displayed as $ 1,000.00.

/

Round(Precision,RoundingMode)

This function is used for number rounding.

  • The first argument is an integer between 0 and 10.

  • The second argument is optional. The default value of the second argument is HALF_UP. This argument has the following available options:

    • UP
    • DOWN
    • CEILING
    • FLOOR
    • HALF_UP
    • HALF_DOWN
    • HALF_EVEN
    • UNNECESSARY

Assume that an invoice has the amount of 10.125,

{{Amount|Round(2)}} will return 10.13.

You can also use the Round function for padding purposes.

{{Amount|Round(4)}} will return 10.1250.

/