Skip to main content

Custom Events

Zuora

Custom Events

You can use the Event Triggers API operations to define, update, and list custom events.

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
DebitMemo The profile associated with the account
DebitMemoItem The profile associated with the account
Feature Tenant default profile
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
Product Tenant default profile
ProductFeature Tenant default profile
ProductRatePlan Tenant default profile
ProductRatePlanCharge Tenant default profile
ProductRatePlanChargeTier Tenant default profile
RatePlanChargeTier The profile associated with the account
RatePlan The profile associated with the account
RatePlanCharge The profile associated with the account
Refund The profile associated with the account
RefundApplication 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

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. 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
Greater than or equal to >= Invoice.Amount >= 1000
Boolean And && Invoice.Amount < 200 && Invoice.Amount > 1000
Boolean Or || Invoice.Amount < 200 || Invoice.Amount > 1000
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

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's Status 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

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' , 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.