Custom event overview

Custom events are user-defined events that allow you to trigger notifications based on changes to standard or custom objects.

To define a custom event, you must specify the base object and the trigger condition. When an object changes, the trigger condition defined on the object is evaluated. If the condition is satisfied, a business event will be triggered.

You can manage custom events through the Zuora UI or the Custom event triggers API operations.

Base object for custom events

Each custom event must be associated with a base object, which can be either a standard object or a custom object.

Custom event created on base objects, such as Accounting Code, do not have the context of a customer account, so the default communication profile of the tenant is used for notifications. For example, the Accounting Code object is set up in your Zuora tenant based on your corporate business rules. This does not vary or depend on any configuration of the account. Instead, accounting codes are settings on the system level. Therefore, no customer account is associated with this object and Zuora uses and localizes notification messages based on the default communication profile.

In contrast, custom events created on objects like Invoice have the context of a customer account, and thus the the communication profile specified in the account is used for notifications. Zuora sends localized data, such as date formatting, based on the communication profile associated with the account.

Zuora also uses the default communication profile for custom events associated with custom objects.

When creating custom events through API operations, use the baseObject field to specify the base object. The following table list the value that you should specify in the baseObject field.


Base object type	Base object value	Example
Standard object	`<object_name>`	Account, PaymentMethod
Custom object	`default__<custom_object_api_name>`	default__vehicle

For a list of supported standard objects and their communication profile behavior, see Supported base object for custom events.

Trigger condition

Trigger condition is an expression that determines whether to trigger the custom event when the base object changes, such as creation, modification, or deletion.

When creating custom events through API operations, use the condition field to specify the trigger condition.

Trigger condition syntax

Zuora uses the Apache Commons Java Expression Language (JEXL) library syntax for defining triggers. For more information, see Apache Commons JEXL.

Basically, a trigger condition consists of one or more sub-conditions connected by logical operators and must return a boolean value.

The following table lists the most common logical operators:


Name	Operator	Description	Example
Boolean AND	`&&`	Return `true` if both sub-conditions it connects are `true`.	Invoice.Amount > 200.0 && Invoice.Amount < 1000.0
Boolean OR	`\|\|`	Return `true` if at least one of the sub-conditions it connects is `true`.	changeType == 'INSERT' \|\| changeType == 'UPDATE'

Sub-condition syntax

A sub-condition is an expression of two values connected by a comparison operator. The result of a sub-condition is also a boolean value.

Typically, the first operand is a dynamic value of an object field or a variable provided by Zuora, and the second operand is a fixed value. When changes to the base object occur, Zuora calculates the results of sub-conditions with the context data, for example, the related object record and changing type.

The following table lists variables you can use in sub-conditions:


Type	Expression	Note	Example
Base object change type	`changeType`	Available values are as follows: INSERT UPDATE DELETE If a trigger condition does not contain change type constraints, the condition applies to all object change types.	(N/A)
Standard fields of standard objects	`<object_name>.<field_name>`	Adding `_old` to the end of an object field name represents the field value before the change occurred.	Invoice.Status, Invoice.Status_old
Custom fields of standard objects	`<object_name>.<custom_field_api_name>`	Adding `_old` to the end of an object field name represents the field value before the change occurred.	Invoice.MyData__c, Invoice.MyData__c_old
Custom fields of custom objects	`default__<custom_object_api_name>.<custom_field_api_name>`	Adding `_old` to the end of an object field name represents the field value before the change occurred.	default__vehicle.Color__c, default__vehicle.Color__c_old

Sub-conditions can contain fields only from the base object on which the event trigger is defined.

The following table lists the most common comparison operators:


Name	Operator	Example
Equality	==	BillingRun.Status == 'Posted'
Inequality	!=	PaymentMethod.AccountId != null
Greater Than	>	Invoice.Amount > 1000.0
Greater Than Or Equal To	>=	Invoice.Amount >= 1000.0
Less Than	<	Invoice.Amount < 1000.0
Less Than Or Equal To	<=	Invoice.Amount <= 1000.0
Starts With	=^	Account.AccountNumber =^ 'E'
In or Match	=~	Account.Batch =~ ['Batch8','Batch9']

JEXL also provides built-in functions (for example, size()) that can be used in sub-conditions. For all available operators and functions, see Apache Commons JEXL.

Trigger condition examples

See the following examples to better understand trigger conditions.


Example	Description
changeType == 'INSERT'	The event is triggered when a record of the base object is created.
Account.Level__c == 'Premium'	The event is triggered when a premium-level account is created, updated, or deleted.
changeType == 'UPDATE' && Invoice.Status == 'Posted' && Invoice.Status_old != 'Posted' && Invoice.Amount > 1000.0	The event is triggered when an invoice is posted with an amount greater than 1000.
(changeType == 'INSERT' \|\| changeType == 'UPDATE') && size(default__vehicle.Serial__c) > 12	The event is triggered when a record of the Vehicle custom object is created or updated, and the vehicle serial number is greater than 12 characters. In this example, two sub-conditions for change type are grouped by `()` because the boolean AND operator (`&&`) has higher precedence than the boolean OR operator (`\|\|`).

Best practice for creating trigger conditions

It is recommended to use decimals when comparing numeric values. Using decimals helps prevent unexpected results when comparing an integer with a field that contains a decimal value.

For example, if you want to trigger an event when the Account object is updated and the account balance value is positive, use the following trigger condition:

changeType == 'UPDATE' && Account.Balance > 0.0

Otherwise, if you use Account.Balance > 0 in the trigger condition, the event might not be triggered because the Account.Balance field contains decimal values.

Limitations

Custom events have the following limitations:

A maximum of 1000 custom event triggers can be created.
Base object values for Zuora standard objects are case sensitive. For example, PaymentMethod is correct, and Paymentmethod or paymentmethod is incorrect.
Base object values for custom objects must be lowercase. For example, default__vehicle .
When creating custom events, you cannot match fields of the RatePlanCharge object against constant values for the condition field. For example, the following condition will cause errors: RatePlanCharge.ShippingProcessStatus__c == 'Shipping Confirmed' , where Shipping Confirmed is a constant value.
Fields on objects are case-sensitive. For example, PaymentMethod.createdbyid can result in errors. The correct format is PaymentMethod.CreatedById .
A condition cannot contain fields from data source objects that are joined to the base object.
Do not create duplicate events because they will be either merged or deleted. Zuora considers events that have the same trigger condition as duplicate events, regardless of event type names.
For custom events triggered on the Amendment object, merge fields defined within the notification definition are only available for the amendment completed events.

Welcome to Zuora Product Documentation

Explore our rich library of product information