Custom Events
You can manage custom events through the Zuora UI, such as creating, editing, deleting, or cloning. See Custom Event Triggers API for more information about managing custom events through the API.
To define a custom event, you must specify the base object and the trigger condition. When a Zuora object changes, the trigger condition defined on the object is evaluated. If the condition is satisfied, a business event will be triggered.
A maximum of 1000 custom event triggers can be created.
Base objects for custom events
Custom event triggers created against base objects such as AccountingCode do not have the context of a customer account, and 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 event triggers created against 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.
The following table summarizes the supported base objects and the corresponding communication profile used for notifications. For more information, see Communication profiles.
Supported base object | Communication profile used |
---|---|
Account | The profile associated with the account |
AccountingCode | Tenant default profile |
AccountingPeriod | Tenant default profile |
Amendment | The profile associated with the account |
BillingRun | Tenant default profile |
Contact | The profile associated with the account |
CreditBalanceAdjustment | The profile associated with the account |
CreditMemo | The profile associated with the account |
CreditMemoApplication | The profile associated with the account |
CreditMemoApplicationItem | The profile associated with the account |
CreditMemoItem | The profile associated with the account |
CreditMemoPart | The profile associated with the account |
DebitMemo | The profile associated with the account |
DebitMemoItem | The profile associated with the account |
Feature | Tenant default profile |
Fulfillment | The profile associated with the account |
Fund | The profile associated with the account |
Invoice | The profile associated with the account |
InvoiceAdjustment | The profile associated with the account |
InvoiceItem | The profile associated with the account |
InvoiceItemAdjustment | The profile associated with the account |
JournalEntry | Tenant default profile |
JournalEntryItem | Tenant default profile |
Order | The profile associated with the account |
OrderAction | The profile associated with the account |
OrderLineItem | The profile associated with the account |
Payment | The profile associated with the account |
PaymentApplication | The profile associated with the account |
PaymentMethod | The profile associated with the account |
PaymentPart | The profile associated with the account |
PaymentSchedule | The profile associated with the account |
PaymentScheduleItem | The profile associated with the account |
Product | Tenant default profile |
ProductFeature | Tenant default profile |
ProductRatePlan | Tenant default profile |
ProductRatePlanCharge | Tenant default profile |
ProductRatePlanChargeTier | Tenant default profile |
RatePlan | The profile associated with the account |
RatePlanCharge | The profile associated with the account |
RatePlanChargeTier | The profile associated with the account |
RatingResult | The profile associated with the account |
Refund | The profile associated with the account |
RefundApplication | The profile associated with the account |
RefundPart | The profile associated with the account |
RevenueEvent | The profile associated with the account |
RevenueEventItem | The profile associated with the account |
RevenueSchedule | The profile associated with the account |
RevenueScheduleItem | The profile associated with the account |
Subscription | The profile associated with the account |
SubscriptionProductFeature | The profile associated with the account |
TaxationItem | The profile associated with the account |
Usage | The profile associated with the account |
ValidityPeriodSummary | The profile associated with the account |
Custom event triggers
When you create a custom event trigger, you must specify the base object and define the trigger condition.
Specify the base object
Use baseObject
field to specify which base object to define a custom event trigger on.
Custom event triggers defined on tenant level base objects are tenant level event triggers. Notifications associated with tenant level events are system notifications.
Note that tenant level event triggers and system notifications are only available in the default communication profile.
Define the trigger condition
Zuora uses the Apache Commons Java Expression Language (JEXL) library syntax for defining triggers.
The condition
field starts with declaring changeType
to trigger the custom event, followed by the additional conditions on the base object. The supported values of changeType
are INSERT
, UPDATE
, and DELETE
.
The expression can only contain fields from the object that the trigger is defined on. For example, Invoice.Amount > 1000.0
. See Data Source Reference for more information about the fields on each object.
You can find all available JEXL syntax in Apache Commons JEXL. For your easy reference, the most commonly used operators and syntax examples are provided in the following table:
Description | JEXL Operator | Syntax Example |
---|---|---|
Equal to | == |
BillingRun.Status == 'Posted' |
Not equal to | != |
PaymentMethod.AccountId != null |
Less than or equal to | <= |
Invoice.Amount <= 1000.0 |
Greater than or equal to | >= |
Invoice.Amount >= 1000.0 |
Boolean And | && |
Invoice.Amount > 200.0 && Invoice.Amount < 1000.0 |
Boolean Or | || |
Invoice.Amount < 200.0 || Invoice.Amount > 1000.0 |
Starts with | =^ |
Account.AccountNumber =^ 'E' |
In or match | =~ |
Account.Batch =~ ['Batch8','Batch9'] |
The following condition example causes an event to be triggered whenever an invoice is posted with an amount greater than 1000:
changeType == 'UPDATE' && Invoice.Status == 'Posted' && Invoice.Status_old != 'Posted' && Invoice.Amount > 1000.0
Where:
-
changeType
is a keyword that specifies the type of change that occurred to the Invoice object. -
Invoice.Status
is the value of the Invoice object'sStatus
field after the change occurred. -
Invoice.Status_old
is the value of the Invoice object's Status field before the change occurred.
In the above example, the value of baseObject
is Invoice
.
Custom fields are also supported. Thus, you can define conditions on custom fields that you specifically created in your tenant.
Moreover, when you define conditions, you can also use JEXL built-in functions. For example, size()
.
In the following example, the JEXL built-in function size()
is used and one condition is defined on the custom field TradingPartnerCode__c
.
(changeType == 'UPDATE' || changeType == ‘INSERT’) && size(Account.CrmId) != 18 && size(Account.TradingPartnerCode__c) > 0
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.
Sample code for custom events
See the following request samples for the Create an event trigger operation to create custom events.
Bill Run Posted
You can use the following request sample to create a custom event of BillRunPosted if you do not use the auto-post on Bill Runs.
{ "active": true, "baseObject": "BillingRun", "condition": "changeType == 'UPDATE' && BillingRun.Status == 'Posted' && BillingRun.Status_old != 'Posted'", "description": "Bill Run Posted", "eventType": { "name": "BillRunPosted", "displayName": "Bill Run Posted", "description": "BillRunPosted", "namespace": "user.notification" } }
Payment Term Updated
You can use the following request sample to create a custom event of AccountPaymentTermUpdate.
{ "active": true, "baseObject": "Account", "condition": "changeType == 'UPDATE' && Account.PaymentTerm_old != Account.PaymentTerm", "description": "Generate an event when a account PaymentTerm is updated", "eventType": { "description": "Generate an event when a account PaymentTerm is updated", "displayName": "Account Update", "name": "AccountPaymentTermUpdate" } }
Limitations
The custom events have the following limitations:
-
The INSERT change type is not supported on RatePlan base object.
-
The INSERT change type is not supported on SubscriptionProductFeature base object.
-
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'
, whereShipping Confirmed
is a constant value. -
Fields on objects are case-sensitive. For example,
PaymentMethod.createdbyid
can result in errors. The correct format isPaymentMethod.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.