Skip to main content

Custom Events

Zuora

Custom Events

If the Custom Events feature is enabled in your tenant, you can use Event Triggers API to define 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.

Base objects for custom events

You can define a custom event on any of the following base objects. Some of the base objects are tenant level base objects.

Supported base object Tenant level base object or not
Account No
AccountingCode Yes
AccountingPeriod Yes
Amendment No
BillingRun Yes
Contact No
CreditBalanceAdjustment No
CreditMemo No
CreditMemoApplication No
CreditMemoApplicationItem No
CreditMemoItem No
DebitMemo No
DebitMemoItem No
Feature Yes
Invoice No
InvoiceAdjustment No
InvoiceItem No
InvoiceItemAdjustment No
JournalEntry Yes
JournalEntryItem Yes
Order No
OrderAction No
OrderLineItem No
Payment No
PaymentApplication No
PaymentMethod No
PaymentPart No
Product Yes
ProductFeature Yes
ProductRatePlan Yes
ProductRatePlanCharge Yes
RatePlan No
RatePlanCharge No
Refund No
RefundApplication No
RevenueEvent No
RevenueEventItem No
RevenueSchedule No
RevenueScheduleItem No
Subscription No
SubscriptionProductFeature No
TaxationItem No
Usage No

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 

The condition field is a JEXL expression that specifies when to trigger the custom events. The expression can contain fields from the object that the trigger is defined on.

Note that the condition cannot contain fields from data source objects that are joined to the object that the trigger is defined on.

For example, the following condition 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. For all objects, the supported values of changeType are INSERT, UPDATE, and DELETE.

  • 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.

Moreover, when you define conditions, you can also use JEXL built-in functions. For example, size().

In addition,  you can define conditions on custom fields that you specifically created in your tenant.

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 maximum number of event triggers is 20. If you want to increase the limit, submit a request at Zuora Global Support.

  • The INSERT change type is not supported on RatePlan base objects.

  • The INSERT change type is not supported on SubscriptionProductFeature base objects