Skip to main content

Custom Events

Zuora

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 an 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 Zuora standard objects that can be used as base objects and the corresponding communication profile used for notifications. For more information, see Communication profiles.

In addition to Zuora standard objects, you can also use custom objects as base objects of custom events. Only the default communication profile supports custom events for custom objects.

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
DeliveryAdjustment 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
SubscriptionChargeDeliverySchedule The profile associated with the account
SubscriptionChargePriceInterval The profile associated with the account
SubscriptionChargePriceIntervalTier The profile associated with the account
SubscriptionOffer The profile associated with the account
SubscriptionProductFeature The profile associated with the account
TaxationItem The profile associated with the account

UpdaterDetail

(Payment Method Update object)
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.

You can use supported Zuora standard objects or custom objects as the base object. The following table lists the value that you should specify in the baseObject field for each object type:

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

See Base objects for custom events for all supported standard objects.

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 

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 a custom event trigger, you should specify the trigger condition in the condition field.

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.

trigger_condition.png

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.

sub_condition.png

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.

For more information about the available fields of each standard object, see Data Source Reference.

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.

Examples

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

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.

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"
  }
}

Custom object record created

You can use the following request sample to create a custom event that will be triggered when certain custom object records are created for the Vehicle custom object.

{
  "active": true,
  "baseObject": "default__vehicle",
  "condition": "changeType == 'INSERT' && default__vehicle.Price__c >= 5000.0",
  "description": "Generate an event when a vehicle record whose price is greater than 5000 is created",
  "eventType": {
    "name": "VehicleCreated",
    "displayName": "Vehicle Created",
    "description": "Generate an event when a vehicle record whose price is greater than 5000 is created"
  }
}

Custom object record updated

You can use the following request sample to create a custom event that will be triggered when certain custom object records are updated for the Entitlement custom object.

{
  "active": true,
  "baseObject": "default__entitlement",
  "condition": "changeType == 'UPDATE' && default__entitlement.Usage__c >= default__entitlement.Entitled__c && default__entitlement.Status != 'Trial'",
  "description": "Generate an event when an entitlement record is updated, if the usage equals to or greater than the entitlement and the entitlement status is not trial",
  "eventType": {
    "name": "EntitlementUpdated",
    "displayName": "Entitlement Updated",
    "description": "Generate an event when an entitlement record is updated, if the usage equals to or greater than the entitlement and the entitlement status is not trial"
  }
}

Limitations 

The custom events have the following limitations:

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

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