Event Framework

This is not Salesforce Platform Events. The fusionCore event framework is an in-memory hook system. Handlers run synchronously, in the same transaction, immediately when the event fires — there is no queue and no delivery delay.Its purpose is to let one package define extension points (“hooks”) and let any other package react to them without a compile-time dependency. The package that fires an event does not need to know which handlers exist; handlers are bound to events at runtime through metadata.

This page covers how to fire an event, how to write and register a handler, the events fired across fusionCore today, and the execution characteristics you need to keep in mind. For the related metadata-driven trigger system, see Trigger Framework. For the logging and service utilities referenced below, see Logging and Services.

Firing an Event

Fire an event with FCORE_BASE.ServiceLayer.fireEvent(String name, FCORE_BASE.EventContext context). You pass data into the handlers through an FCORE_BASE.EventContext, which is a simple key/value bag:

setData(String key, Object value) — put a value into the context before firing.
getData(String key) — read a value back out (handlers call this).

Event names are plain strings. Each subscriber package keeps its names in a constants class named ServiceLayerEventConstants that it owns — Commerce (FCORE_PAY) and Subscriptions (FCORE_MEM) each have their own copy. There is no Platform-owned copy. The example below fires the wallet-item-removed hook from a Commerce trigger unit:

FCORE_BASE.EventContext eventContext = new FCORE_BASE.EventContext();
eventContext.setData('ids', removedWalletItemIds);
FCORE_BASE.ServiceLayer.fireEvent(ServiceLayerEventConstants.EVENT_WALLET_ITEM_REMOVED, eventContext);

Handling an Event

A handler extends FCORE_BASE.BaseEventHandler, uses the EH suffix by convention, and overrides execute(). Read the payload through getContext().getData(key). Wrap the body in a try/catch: log the exception via FCORE_BASE.Logger and then rethrow it so the caller can react. Do not swallow it.

global without sharing class WalletItemRemovedEH extends FCORE_BASE.BaseEventHandler {
    public override void execute() {
        List<Id> walletItemIds = (List<Id>) getContext().getData('ids');
        try {
            // react to the hook
        } catch (Exception e) {
            FCORE_BASE.Logger.setApexExecutionContext(WalletItemRemovedEH.class, 'execute');
            FCORE_BASE.Logger.logAndCommit(e, FCORE_BASE.Logger.LogLevel.ERROR, walletItemIds, false);
            throw e;
        }
    }
}

The WalletItemRemovedEH above is illustrative of the handler shape only. See the WalletItemRemoved note for how that hook is actually wired in current source.

There is no EventHandlerException class — rethrow the caught exception directly (throw e;) after logging it.

Registering a Handler

Bind an event name to a handler class with an FCORE_BASE__Event_Handler__mdt custom metadata record. The relevant fields are:

FCORE_BASE__Event_Name__c — the event string this handler responds to.
FCORE_BASE__Apex_Class__c — the handler class (the one extending FCORE_BASE.BaseEventHandler).
FCORE_BASE__Order__c — ascending execution order when several handlers respond to the same event.
FCORE_BASE__Is_Enabled__c — whether the handler runs.

A minimal metadata record looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<CustomMetadata xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>Wallet Item Replaced Handler</label>
    <values>
        <field>FCORE_BASE__Event_Name__c</field>
        <value xsi:type="xsd:string">WalletItemReplaced</value>
    </values>
    <values>
        <field>FCORE_BASE__Apex_Class__c</field>
        <value xsi:type="xsd:string">FCORE_PAY.WalletItemReplacedEH</value>
    </values>
    <values>
        <field>FCORE_BASE__Order__c</field>
        <value xsi:type="xsd:double">10</value>
    </values>
    <values>
        <field>FCORE_BASE__Is_Enabled__c</field>
        <value xsi:type="xsd:boolean">true</value>
    </values>
</CustomMetadata>

When metadata is not appropriate — for example, registering a handler inside a test — register it programmatically instead (see Execution Characteristics).

Events Fired Across fusionCore

The following events are fired across the fusionCore packages today.

Event Name	Handler	What It Does
`CalculatePrice`	`FCORE_PAY.CalculatePriceEH`	Requests price recalculation for orders whose items changed; runs the Pricing Engine (synchronously, or via batch for large orders).
`CalculateTax`	`FCORE_PAY.CalculateTaxEH`	Requests tax calculation; fired by `CalculatePriceEH` after pricing so tax is computed on fresh prices; runs the Tax Engine.
`Payment`	`FCORE_PAY.PaymentEH`	Fired when a payment is applied to one or more orders; validates the financial details in the context and creates the payment Financial Events.
`GenerateInvoice`	`FCORE_PAY.GenerateInvoiceEH`	Fired during order activation; validates the invoice configurations and creates the invoice Financial Events.
`WalletItemReplaced`	`FCORE_PAY.WalletItemReplacedEH` (Subscriptions also subscribes)	Fired when a stored payment method is replaced; Subscriptions reassigns auto-renewing Purchase Activities from the old wallet item to its replacement.
`GenerateRenewalOrder`	`FCORE_MEM.GenerateRenewalOrderEH`	Fired when subscriptions are due for renewal; runs the Subscription Renewal Engine, then fires `RenewalOrderGenerated` and triggers installment generation.
`RenewalOrderGenerated`	`FCORE_MEM.RenewalOrderGeneratedEH`	Fired after the renewal orders are created; moves them to the status configured in the `FC_Renewal_Order_Status` `Constant__mdt` record.
`CancelSubscription`	`FCORE_MEM.CancelSubscriptionEH`	Requests cancellation of one or more subscriptions described by the DTOs in the context.
`GenerateInstallments`	`FCORE_PAY.GenerateInstallmentsEH` and `FCORE_MEM.GenerateInstallmentsEH`	Requests installment generation for payment plans; runs the Installment Generator, switching to batch for large volumes. Both packages register a handler for this event — disambiguate by namespace.

A Note on WalletItemRemoved

WalletItemRemoved is fired when a stored payment method (FCORE_PAY__Wallet_Item__c) is flagged as removed — both from the trigger and from the expiration batch. In current source it is processed by the WalletItemRemovedTU trigger unit in Commerce, and the Stripe add-on subscribes to this hook to detach the payment method in Stripe asynchronously. There is no WalletItemRemovedEH class in the Platform, Commerce, or Subscriptions repos, which is why it does not appear in the table above.

Execution Characteristics

Keep these behaviors in mind when you fire events or write handlers:

Handlers for an event run synchronously, in ascending FCORE_BASE__Order__c.
An exception in a handler is logged (FCORE_BASE.Logger.logAndCommit) and rethrown. Remaining handlers do not run, and the caller must handle the exception.
FCORE_BASE.ServiceLayer.stopPropagation(String eventName) — a handler can stop the remaining handlers for that event.
FCORE_BASE.ServiceLayer.disableEvent(String eventName) / FCORE_BASE.ServiceLayer.enableEvent(String eventName) — temporarily mute an event. Useful in tests and as a recursion guard.
FCORE_BASE.ServiceLayer.registerEventHandler(String eventName, String apexClass, Integer order) — register a handler programmatically (three arguments) when metadata is not appropriate, such as in tests.
Avoid firing an event from its own handler. There is no recursion guard, so it loops.

Developer Guide

fusionCore Infrastructure

Firing an Event

Handling an Event

Registering a Handler

Events Fired Across fusionCore

A Note on WalletItemRemoved

Execution Characteristics

​Firing an Event

​Handling an Event

​Registering a Handler

​Events Fired Across fusionCore

​A Note on WalletItemRemoved

​Execution Characteristics

Firing an Event

Handling an Event

Registering a Handler

Events Fired Across fusionCore

A Note on WalletItemRemoved

Execution Characteristics