Publish Event Messages with Apex

Create Events in Apex

Before you can publish event messages, create platform event instances.

Create Events Using the Event API Name:

Create an event instance the same way that you create a Salesforce or custom object instance. Use the new operator with the event API name.

// Create event 
Event_Name__e event = new Event_Name__e();
// Set field values
event.field1__c = 'value';
...

// Or create event with fields
Event_Name__e event = new Event_Name__e(field1__c='value', …);

Create Events With a Prepopulated EventUuid Field:

If you want to have the standard EventUuid field prepopulated in the event variable, use the Apex sobjectType.newSobject method to create an event.

The EventUuid field holds a universally unique identifier (UUID) that identifies an event message. You can use the EventUuid field to track the delivery of event messages. For more information, see Get the Result of Asynchronous Platform Event Publishing with Apex Publish Callbacks.

// Create event 
Event_Name__e event = (Event_Name__e)Event_Name__e.sObjectType.newSObject(null, true);
// Set field values
event.field1__c = 'value';
...
// Display the prepopulated EventUuid
System.debug(‘EventUuid: ’ + event.EventUuid);

To publish event messages, call the EventBus.publish method. For example, if you defined a custom platform event called Low Ink, reference this event type as Low_Ink__e. Next, create instances of this event, and then pass them to the Apex method.

Immediate Publish Result in Database.SaveResult

For each event, Database.SaveResult contains information about whether the operation was successful and the errors encountered. If the isSuccess() method returns true, the publish request is queued in Salesforce and the event message is published asynchronously. For more information, see High-Volume Platform Event Persistence. If isSuccess() returns false, the event publish operation resulted in errors, which are returned in the Database.Error object. EventBus.publish() can publish some passed-in events, even when other events can’t be published due to errors. The EventBus.publish() method doesn’t throw exceptions caused by an unsuccessful publish operation. It’s similar in behavior to the Apex Database.insert method when called with the partial success option.

Database.SaveResult also contains the Id system field. The Id field value isn’t included in the event message delivered to subscribers. It isn’t used to identify an event message, and isn’t always unique.

Status Code Returned for Asynchronous Publishing

To indicate that the publish operation is asynchronous, the OPERATION_ENQUEUED status code is returned for a successful EventBus.publish call in Database.SaveResult, in addition to the event UUID. You can get the status code and event UUID after checking for a successful result. This example is a printout of the contents of Database.SaveResult after a successful publish call. The getStatusCode method of Database.Error returns the status code of OPERATION_ENQUEUED. The getMessage method returns the event UUID value for the published event message.

Database.SaveResult[getErrors=(
    Database.Error[getFields=();
    getMessage=d65ae914-2488-414a-85d4-4df93ea9a05c;
    getStatusCode=OPERATION_ENQUEUED;]);
getId=e02xx0000000001AAA;isSuccess=true;]

Publish Behavior

The platform event message is published either immediately or after a transaction is committed, depending on the publish behavior that you set in the platform event definition. For more information, see Platform Event Fields. Apex governor limits apply. For events configured with the Publish After Commit behavior, each method execution is counted as one DML statement against the Apex DML statement limit. You can check limit usage using the Apex Limits.getDMLStatements() method. For events configured with the Publish Immediately behavior, each method execution is counted against a separate event publishing limit of 150 EventBus.publish() calls. You can check limit usage using the Apex Limits.getPublishImmediateDML() method.