System events

System events are identifiable system actions, such as the creation of a document, the status change of a document, and the end of a workflow. You can create custom system events and configure notifications for system events.

System events are processed by transaction, and information is synthesized when multiple actions occur in the context of a single transaction. For example, when a Workflow starts, the Document State may change and Document Roles may be assigned. These items are rolled into a single notification when necessary.

Create custom system events

Warning

System event handlers (any Apex class that implements the SE_ISystemEventHandler or SE_ISystemEventHandlerWithGetters Apex interfaces) do not support the use of data manipulation language (DML) when processing a system event.

To create a custom system event:

Create a System Event (mvn__SE_System_Event__mdt) record. Key fields include:
- System Event Name - enter a unique API name for the record.
- Payload Apex Class Name - specify the payload type for the system event. If your custom system event uses a list of SObjects as the payload, leave this field blank. If the system event uses a list of custom Apex class objects as the payload, enter the API name of a custom Apex class. The custom Apex class must implement the SE_ISystemEventApexClassPayload interface:
```
global interface SE_ISystemEventApexClassPayload {
    String getUniqueId();
}
```
  Example 12. Payload
  /** Custom class that implements the SE_ISystemEventApexClassPayload interface */ public class MyCustomPayload implements SE_ISystemEventApexClassPayload { /** Private variable to store this instance's unique Id */ private String uniqueId; /** Constructor that initializes the instance with an unique Id */ public MyCustomPayload() { this.uniqueId = UUIDGenerator.generateId(); } /** Implementation of the SE_ISystemEventApexClassPayload interface method that returns the unique Id */ public String getUniqueId() { return this.uniqueId; } }
- Payload Apex Class Namespace - enter the namespace of the Apex class defined in the Payload Apex Class Name field.
- Priority - enter the order in which the custom system event should be processed. A system event with a Priority of 1 is processed before a system event with a Priority of 2.
For a list of all the System Event fields, visit System Event.

Create a System Event Configuration (mvn__SE_System_Event_Configuration__mdt) record. Key fields include:

System Event - look up and associate the System Event record that you created in the previous step.

Handler Name - enter the API name of the Apex class that implements the associated System Event. The custom Apex class must implement the SE_ISystemEventHandler interface.

/**
 * @author       Mavens
 * @description  Interface for the System Events handlers
 */
global interface SE_ISystemEventHandler {
    /**
     * Processes the SE_System_Event_Configuration__mdt records for the given new and old Objects.
     *
     * The input variables are generic so that any type of payload in the form of an Object/SObject can be passed,
     * the implementation is responsible for casting them to the appropriate type to be able to process them.
     *
     * @param  config         the SE_System_Event_Configuration__mdt being processed
     * @param  newRecords     the list of new/updated payload Objects
     * @param  oldRecordsMap  the map of old SObject records sorted by Id when the routers processes SObjects
     */
    void process(SE_System_Event_Configuration__mdt config, List<Object> newRecords, Map<Id, SObject> oldRecordsMap);
}

In addition to implementing the SE_ISystemEventHandler interface, the handler can optionally implement the SE_ISystemEventHandlerWithGetters interface. This interface allows the handler to create emails, Salesforce notifications, Chatter posts, and audit logs.

/**
 * @author      Mavens
 * @description Interface for the System Event handlers that also implement getters for notification, chatter posts
 *              and/or SObjects
 */
global interface SE_ISystemEventHandlerWithGetters extends SE_ISystemEventHandler {
    /**
     * @return   the List of generated SE_SalesforceNotification records that represent the custom notifications
     */
    List<SE_SalesforceNotification> getSalesforceNotifications();

    /**
     * @return   the List of generated SE_EmailMessage that represent the emails
     */
    List<SE_EmailMessage> getEmailMessages();

    /**
     * @return   the List of generated SE_ChatterFeedPost that represent the chatter posts
     */
    List<SE_ChatterFeedPost> getChatterFeedPosts();

    /**
     * @return   the List of generated generic SObject records to insert (e.g. document audit log entries)
     */
    List<SObject> getSObjects();
}

For a list of all the System Event Configuration fields, visit System Event Configuration.

Notification channels

When a document system event occurs, notifications are sent to the configured channels for that system event. Channels include email, Salesforce notification, Chatter, and audit log. You can disable notifications for all system events in your Salesforce instance.

Email and Salesforce notifications

You can receive emails and/or Salesforce notifications when document system events occur. Salesforce notifications are alerts that appear in the user interface when you click the Notification Notification icon icon.

To define the types of notifications that users in specific roles receive when specific system events occur, create and modify records for these custom metadata objects:

Document Notification Audience (mvn__CM_Document_Notification_Audience__mdt) - defines target audiences for system event notifications. The target audience can be based on a Document Role, Group, Salesforce user ID, or user query filter. For more information, visit Document Notification Audience.
Document System Event Notification (mvn__CM_Document_System_Event_Notification__mdt) - manages how system event notifications are sent to users via Salesforce notifications and emails. For more information, visit Document System Event Notification.

You can also use custom labels to modify the text in system event notifications. Visit Configure notification body.

Chatter feed

A document's Chatter feed lists the system events that were fired in relation to that document. To specify which system events should create Chatter feed notification, modify the Create Document Chatter Post (mvn__CM_Create_Document_Chatter_Post__c) field for the appropriate System Event mvn__SE_System_Event__mdt) custom metadata records.

When users follow documents, the documents' feeds display in the user’s aggregate Chatter feed.

Audit log

The audit log for a document lists the system events that were fired in relation to the document. To specify which system events should create an audit log entry, modify the Create Document Audit Log (mvn__CM_Create_Document_Audit_Log__c) field for the appropriate System Event mvn__SE_System_Event__mdt) custom metadata records:

To view the audit log for a document in the user interface, use the MCM - Document Activity (cmDocumentActivity) component. The component's Audit Log History tab displays the document record's system event history. A maximum of 500 entries display. If you need to see more than the last 500 entries, use Salesforce's Query REST API.

Note

Audit log details for a Document State Change system event are restricted to the old status value and the new status value for the document.

Disable system event notifications

If you do not want to use system event notifications in your instance or want to disable all system event notifications before a data load, use the System Event Setting (mvn__SE_System_Event_Setting__mdt) custom metadata type to disable notifications for all system events in your Salesforce instance. Disable options include:

Disable Chatter Posts - indicates if Chatter post notifications for systems events are disabled (true) or enabled (false).
Disable Notifications - indicates if all notification channels for system events are disabled (true) or enabled (false).

You can also grant users the ability to mute all document system event notifications for a specific document type or document state.

Create a Document Type Role Permission (mvn__CM_Document_Type_Role_Permission__mdt) metadata record as follows:
1. Set the Document Type and Role fields according to the document and document collaborator that you want to enable the feature for. For example, if you want a reviewer to be able to mute notifications for a publication document, set the Document Type field to Reference Document and set the Role field to Reviewer.
2. Set the Permission field to Mute Notifications. This is the Mute Notifications (CM_Mute_Notifications) Permission (mvn__CM_Permission__mdt) metadata record that will mute all document system event notifications for the document.
Create a Document State Role Permission (mvn__CM_Document_State_Role_Permission__mdt) metadata record as follows:
1. Set the Document State Role field based on the state of the document and type of document collaborator that you want to enable the feature for. For example, if you want a document owner to mute the notifications for a document that is in review, set the Document State Role field to Default - In Review - Owner.
2. Set the Permission field to Mute Notifications. This is the Mute Notifications (CM_Mute_Notifications) Permission (mvn__CM_Permission__mdt) metadata record that will mute all document system event notifications for the document state.

Once configured, the Role Permissions matrix for the specified role will show a checkmark next to "Mute Notifications". These users will then be able to configure the Notifications Muted by Default (mvn__CM_Notifications_Muted_by_Default__c) field on the Document State (mvn__CM_Document_State__mdt) custom metadata type to enable or mute notifications for a specific document state by default. These users will also be able to click Mute Notifications or Unmute Notifications on a Document record to override the default notification settings for the configured document type.

When notifications for a document, document type, or document state are muted, notifications are not sent out to any collaborators on the document. This applies to all Document System Event Notification (mvn__CM_Document_System_Event_Notification__mdt) metadata records configured for the document. However, document-level notification settings are superseded by task-level notification settings. For more information about notification management on activities and tasks, reference Tasks.

Configure notification body

If the out-of-the-box system event handlers build your system event notifications, you can use custom labels to modify the text in your notifications.

To modify the text in system event notifications:

Open the relevant custom label in Edit mode. The custom label Names for system event notifications follow this naming convention: <System Event Name>_<notification location>. Notification locations include:
- Email_Body
- Feed_Body
- Notification_Body
For example, the custom label that defines the email body for the Document New Version system event notification is CM_Document_New_Version_Email_Body.
Modify the Value field. For a list of supported merge fields, visit Supported merge fields.
Click Save.

Supported merge fields

Custom labels for system event notifications only support merge fields for context record fields that are visible to the user.

System event	Supported context record types
Document Create	documentVersion
Document Delete	documentVersion
Document New Version Upload	documentVersion
Document Version Delete	documentVersion
Document New Draft	documentVersion
Document State Change	documentVersion
Document State Entry Obsolete	documentVersion
Document State Entry Published	documentVersion
Document State Entry Withdrawn	documentVersion
Document State Entry Draft	documentVersion
Document Upcoming Expiration	documentVersion
Document Metadata Update	documentVersion lastModifiedBy
Workflow Start	documentVersion workflowInstance
Document Relationship Create	documentVersion1 documentVersion2 documentRelationship product
Document Relationship Delete	documentVersion1 documentVersion2 documentRelationship product
Document Region Create	documentVersion region
Document Region Delete	documentVersion region
Workflow Task Assignment	documentVersion Task
Workflow Task Update	documentVersion Task

Out-of-the-box system events

These System Event (mvn__SE_System_Event__mdt) records exist out-of-the-box:

CM_Document_Create
CM_Document_Delete
CM_Document_Metadata_Update
CM_Document_New_Draft
CM_Document_New_Version_Upload
CM_Document_Region_Create
CM_Document_Region_Delete
CM_Document_Relationship_Create
CM_Document_Relationship_Delete
CM_Document_Role_Create
CM_Document_Role_Delete
CM_Document_State_Change
CM_Document_State_Entry_Draft
CM_Document_State_Entry_Obsolete
CM_Document_State_Entry_Published
CM_Document_State_Entry_Withdrawn
CM_Document_Usage
CM_Document_Version_Delete
CM_Upcoming_Document_Expiration
CM_Workflow_End
CM_Workflow_Start
CM_Workflow_Task_Update

Metadata

These are the primary custom metadata types used to configure system events:

Document Notification Audience (mvn__CM_Document_Notification_Audience__mdt) - defines target audiences for system event notifications. The target audience can be based on a Document Role, Group, Salesforce user ID, or user query filter. When defining a target audience based on Document Role, you must specify the Document Context in which the document role is notified.
Document System Event Notification (mvn__CM_Document_System_Event_Notification__mdt) - manages how system event notifications are sent to users via Salesforce notifications and emails.
System Event (mvn__SE_System_Event__mdt) - defines the system-wide events that can be listened to and processed using a configured custom Apex class.
System Event Configuration (mvn__SE_System_Event_Configuration__mdt) - configures handlers for system events.
System Event Setting (mvn__SE_System_Event_Setting__mdt) - contains configuration settings that affect all system events.