Define Business Events > Defining publishing events > Business event payloads
  

Business event payloads

When business events are published from MDM SaaS applications to targets that Cloud Data Integration supports, event payloads are generated in the JSON format. The event payloads contain parameters that represent information related to the business events. You can use event payloads to audit, track changes, generate reports, or integrate with downstream systems.
For example, you can create records in a business application and propagate the records with all or some fields to a downstream billing system. Also, when you merge and unmerge records in a business application, you can capture these events for processing by downstream systems. The Publish Business Events jobs generate event payloads that contain information related to events, such as event type, asset details, contributing source records, and event metadata.
When you configure a publishing event, you can also configure the data that you want to appear in event payloads.
When records are validated or enriched, event payloads include an update event that indicates whether the record has passed or failed the validation, or the validation or enrichment process failed with an exception.
When you ingress records with business IDs, versions 1 and 2 of the event payloads include an update event. Additionally, version 1 of the event payload incorrectly includes two create events, and version 2 incorrectly includes a create and merge event that you can ignore.

Event payload parameters - version 2 (Recommended)

The payload metadata contains parameters that capture the publishing events for the create, update, delete, merge, unmerge, and restore actions.
The following table describes the v2 version of the payload parameters:
Parameter Name
JSON Property Name
Description
Active Business ID
activeBusinessId
Unique identifier of the master record.
When records are merged, the active business ID is the surviving business ID of one of the master records. For example, two master records with business IDs MDM1 and MDM 2 are merged. If the surviving business ID is MDM1, then the active business ID of both master records is MDM1. The business ID of the master record that's updated is the same as it's active business ID MDM1. The business ID of the master record that didn't survive during the merge has the business ID MDM2.
When a record is created, updated, deleted, unmerged, and restored, the active business ID is the same as the business ID.
Affected XREFs
affectedXrefs
Object that contains details about the source records that the event affects.
The object contains the following source record parameters:
  • - sourceSystemId. Internal ID of the source system that the source record belongs to.
  • - sourcePKey. Primary key of the source record that was used to load the record into the MDM SaaS data store, such as 6242171e87eb93605aeb80e3.
  • - businessId. Unique identifier of the source record, such as MDM00000016V7K.
  • - xrefType. Type of source record. The parameter can have one of the following values:
    • - DATA. Source record that's created when a record is created.
    • - PATCH. Source record that's created when a record is updated.
    • - DELETED. Source record that's created when a record is deleted.
    • - ANCHOR. For internal use only.
  • - xrefChange. The type of event that affected the source record such as create, update, delete, merge, or unmerge.
  • - membershipChange. Indicates whether the source record is added or removed as a contributor to the record. The parameter can have the following values: ADDED, REMOVED, or NONE.
Asset Internal ID
assetId
Unique identifier of an asset. For example, the ID of the predefined Organization business entity in Customer 360 SaaS is c360.organization. Custom assets can have default or custom IDs, such as customer.
Asset Type
assetType
Type of asset, such as a business entity or relationship. The parameter values are BUSINESS_ENTITY or RELATIONSHIP.
Business ID
businessId
Unique identifier of the record, such as MDM00000016V7K.
BVT Changed
bvtChanged
Indicates whether the best version of the truth for a master record has changed. The parameter values are true or false.
Change List ID
changeListId
Unique identifier to track a set of changes or changes that are part of an approval workflow, such as 87698623465834e32af8. If changes to a business entity record don't go through an approval workflow, the value is null.
Changed Fields
changedFields
List of business entity fields that are updated.
Correlation ID
correlationId
Unique identifier of the event, such as ffd74e22-2f9f-4184-b3d3-4792bfb08b5a.
Data Diff
dataDiff
Object that contains the business entity fields that are updated and the type of update that occurred as a result of the event along with the old and new value of the field.
The object contains the following parameters of the field:
  • - fieldPath. Path to the updated field.
  • - changeType. Type of update to the field.
    • The parameter can have the following values:
    • - CREATED. The field is created.
      • A field can be created in the following scenarios:
      • - A new master record is manually created.
      • - An unmerged record becomes a new master record.
      • - A new field is manually added to a record.
      • - A new field is added to a record as a result of a merge action.
      • - A deleted field is restored.
    • - DELETED. The field is deleted.
    • - UPDATED. The field is changed. A field can be changed as a result of a merge or unmerge action, or a field is manually updated with a new value.
  • - oldValue. Value of the field before the update.
  • - newValue. Value of the field after the update.
Date of Change
dateOfChange
Date when the record was updated. The date is in epoch format, such as 1648498462137.
Event Type
eventType
Type of event, such as create, update, delete, and merge.
The parameter can have one of the following values:
  • - MASTER_CREATED. Indicates that a master record was created.
  • - MASTER_UPDATED. Indicates that a master record was updated.
    • If the record data is enriched, a MASTER_UPDATED event is always generated immediately after a MASTER_CREATED event for the same record.
  • - MASTER_DELETED. Indicates that a record was soft-deleted.
  • - MASTER_MERGED. Indicates that records were merged to form a master record.
  • - MASTER_UNMERGED. Indicates that records were unmerged from a master record.
  • - MASTER_PURGED. Indicates that a record was deleted permanently.
  • - MASTER_RESTORED. Indicates that a previously deleted record was restored to the active state.
Implied Operation
impliedOperation
Original event that a user triggers. For example, if the user triggered a create event that's part of a workflow and the workflow contains several events, the implied operation is create.
Members
members
Object that contains contributing source records of the event. When multiple records merge, a new record is created. The event payload associated with the new record can have multiple contributing source records within the members object.
The object contains the following source record parameters:
  • - sourceSystemId. Internal ID of the source system that the source record belongs to.
  • - sourcePKey. Primary key of the source record that was used to load the record into the MDM SaaS data store, such as 6242171e87eb93605aeb80e3.
  • - businessId. Unique identifier of the source record, such as MDM00000016V7K.
Merged Business IDs
mergedBusinessIds
Array that contains the business IDs of master records that didn't survive during a merge.
Payload
payload
Object that contains the user-defined fields of the record.
Review
review
Indicates whether the event triggered an approval workflow. If the event triggered an approval workflow, the parameter can have one of the following values: APPROVED or REJECTED.
Source System Internal ID
sourceSystem
Internal ID of the source system where the event occurred. For example, if the event occurred in Customer 360 SaaS, the internal ID is c360.default.system.
Record States
states
Object that contains details about the state of the record after the event.
The object contains the following parameters:
  • - base. Indicates the state of the record. The parameter can have the following values:
    • - ACTIVE. The record is active after the event.
    • - DELETED. The record was deleted and inactive after the event.
  • - validation. Indicates the validation status of the record. The parameter can have the following values:
    • - PASSED. Record has passed validation.
    • - FAILED. Record has failed validation.
    • - EXCEPTION. The validation or enrichment process failed to complete due to errors, such as connection timeouts or lack of response from the validation service.
    • - SKIPPED. Record was not validated and validation might occur again at a later time.
User Name
userName
User name of the user who triggered the event, such as john or john.smith@abc.com.

Event payload parameters - version 1 (Deprecated)

Version 1 of the payload metadata is deprecated. When you define a new publishing event, use version 2. The v1 version of the payload metadata contains parameters that capture the publishing events for the create, update, and delete actions.
The following table describes the v1 version of the payload parameters:
Parameter Name
JSON Parameter Name
Description
Change List ID
changeListId
Unique identifier to track a set of changes or changes that are part of an approval workflow, such as 87698623465834e32af8. If changes to a business entity record don't go through an approval workflow, the value is null.
Changed Data
changedData
List of business entity fields that are updated.
Asset Internal ID
entityGuid
Unique identifier of the asset. For example, the ID of the predefined Organization business entity in Customer 360 SaaS is c360.organization. Custom assets can have default or custom IDs, such as customer.
Asset Type
entityType
Type of asset, such as a business entity. The parameter value is BusinessEntity.
Event Type
eventType
Type of event, such as create, update, or delete.
The parameter can have one of the following values:
  • - RECORD_CREATED. Indicates that a record was created.
  • - RECORD_UPDATED. Indicates that a record was updated or deleted. See the softDeleteHint parameter to determine whether the record was deleted.
    • If the record data is enriched, a RECORD_UPDATED event is always generated immediately after a RECORD_CREATED event for the same record.
    When you run the reprocess master data job to recalculate trust scores of master records, multiple RECORD_UPDATED event payloads with empty dataDiff parameters are generated. Ensure that you filter out these events with the empty dataDiff parameters.
  • - RECORD_DELETED. Indicates that a source record was unmerged from a master record. The RECORD_CREATED and RECORD_UPDATED events occur along with the RECORD_DELETED events.
  • - RECORD_APPROVED_CREATED. Indicates that a created record went through an approval workflow and was approved.
  • - RECORD_APPROVED_UPDATED. Indicates that an updated or deleted record went through an approval workflow and was approved.
  • - RECORD_APPROVED_DELETED. Indicates that a record was unmerged to form new records. The original record that's unmerged is treated as deleted. These records went through an approval workflow and were approved.
Lineage Hint
lineageHint
Indicates whether lineage exists when merge or unmerge operations result in create, update, or delete events.The parameter can have the following values:
  • - MERGED. Indicates that an update event merged a record with other records. The record is part of the lineage of another record it merged into.
  • - ACTIVATED. Indicates that an update event unmerged a record from another record and activated the record as a separate record.
Members
members
Object that contains the list of contributing source records of the event. When multiple records merge, a new record is created. The event payload associated with the new record can have multiple contributing source records within the members object.
The object contains the following source record parameters:
  • - sourceSystemId. Internal ID of the source system that the source record belongs to.
  • - sourcePKey. Primary key of the source record that was used to load the record into the MDM SaaS data store, such as 6242171e87eb93605aeb80e3.
  • - businessId. Unique identifier of the source record, such as MDM00000016V7K.
Meta
meta
Additional metadata about the event. The metadata contains information such as the internal ID of the business entity that the event was triggered for, internal identifier of the business entity record, and the user name of the user who created the asset.
Parent
parent
Object with two record identifier parameters. When records merge, the new master record that's created becomes the parent of the contributing records. Records for which a create event is published don't have a parent and the parameter value is null.
The object contains the following parameters of the parent record:
  • - internalId. Internal identifier of the new master record that records merge into, such as 6242171e87eb93605aeb80e2.
  • - businessId. Unique identifier of the new master record that records merge into, such as MDM00000016V7K.
Payload
payload
Object that contains the user-defined fields of the record.
Soft Delete Hint
softDeleteHint
Indicates whether a record is active or soft-deleted. You can restore soft-deleted records. The parameter can have one of the following values: DELETED or RESTORED.
For example, when you delete a record from an MDM SaaS business application, the record is soft-deleted and exists in the system. In this case, the value of the eventType parameter is RECORD_UPDATED and the value of the softDeleteHint parameter is DELETED.
Source System Internal ID
sourceSystem
Internal ID of the source system where the event occurred. For example, if the event occurred in Customer 360 SaaS, the internal ID is c360.default.system.
User Name
userName
User name of the user who triggered the event, such as john or john.smith@abc.com.