Synchronization Methods in MDM

Overview

This document provides an overview of synchronization methods available in Master Data Management (MDM), focusing on Java Message Service (JMS) and HTTP calls. It outlines how to set up synchronization via these methods, including setting up JMS endpoints and HTTP synchronization, and configuring your origin system and the systems you want to sync.

Syncing via JMS

Setting up the JMS Endpoints

To sync via JMS, the system you wish to sync to must subscribe to a JMS Topic. The following steps outline how to set up JMS endpoints:

Go to /master-data-management/code/master_data_management/listener/topicsubcriber/ and copy TemplateListenerService then paste it on your package.
Rename the service based on your preference and then open the service and configure the switch cases base on the system entities and operation. This listener service will be the one that will process all the JMS messages.
Create a Trigger in your package with the type JMS Listener then specify the destination as topic://MdmSubscriberTopic and for the service invoke the service that you copied into your package.

JMS Message Properties

The following table details the message properties needed when sending a message to the MdmJmsQueue or MdmSubscriberTopic:

Name	Description	Example
origin	The system or third-party application from which the JMS message originated	Hubspot, Google Directory
entity	The Common Data Model entity, indicating which System API service to run	Contact, Opportunity
itemId	The name of the property containing the SystemRef or ID of the synced record	itemId, contactId
sender	Defaults to `MDM`, indicating the source of the JMS payload	MDM (Default)
operation	Indicates whether a record needs to be created, updated, or deleted	CREATE, UPDATE, DELETE
foreignKeys	An array of key-value pairs defining properties with foreign key values	[{"name": "`Name of the foreign key property`", "value": "`Value of the foreign key`", "property": "", "system": ""}]

Syncing via HTTP Calls

Setting up for HTTP Synchronization

To sync via HTTP calls directly to third-party APIs, follow these steps:

Setting up your origin system

This would be the source of all changes made and will start the syncing process.

Add a New System on your MDM UI.
Add your origin System's Webhook Configuration
- Go to your origin System's website and setup its webhook
- Identify how your origin System configures webhooks:
  - Creates webhooks specific to an Entity and Operation (e.g. The system can create one webhook specifically for adding a Contact record and another webhook for updating a Contact Record) or
  - Creates a general webhook that runs for all entities and operations
2a. System creates webhooks specific to an Entity and Operation
- If your system allows this, you only need to indicate the specific entity and operation in the /sync url as query parameters:
- Add the following as the webhook URL: <Your server hosting>/api/master_data_management/1.0/sync/system/<System Name>?entityProperty=<Entity Name>&operationProperty=<Operation> Example: <Your server hosting>/api/master_data_management/1.0/sync/system/Pipedrive?entityProperty=Opportunity&operationProperty=CREATE
2b. System a general webhook that runs for all entities and operations
- If your system allows this, the webhook would need to be parsed in order to get the entity and operation. Make sure to indicate the properties in the payload that contains the operation and entity values in the operationProperty and entityProperty of the Webhook Configuration respectively (Found in Step 4).
- Add the following as the webhook URL: <Your server hosting>/api/master_data_management/1.0/sync/system/<System Name> Example: <Your server hosting>/api/master_data_management/1.0/sync/system/Onepage
Add the webhook configuration

The webhook configuration of a system tells the MDM implementation what to look for in a received webhook payload to extract the needed data. such as entity, operation, data object, etc.. for syncing.

Webhook Configuration Properties

Name	Description
operationProperty	If the operation (CREATE,UPDATE,DELETE) isn't already declared in the query parameters, MDM will look for the property containing the operation in the webhook payload, some examples of operationProperty values can be `event` or `operation` in the payload
entityProperty	If the entity isn't already declared in the query parameters, MDM will look for the property containing the entity in the webhook payload.
dataProperty	The property whose value contains the fields of a modified/created record. These fields and their values are what will then be mapped to CDM and synced to other APIs
dataPropertyType	Values can be `array` or `object`. The method in extracting a record's fields and values will vary based on this.
dataObjectHasEntityObject	Checks whether the data object has another object inside with the entity name, containing the record's fields and values, instead of just directly in the data object itself.
deleteDataProperty	Has the same purpose as the `dataProperty` but for DELETE operations
deleteDataType	Has the same purpose as the `dataPropertyType` but for DELETE operations
deleteIdProperty	Tells which property in the payload contains the ID property for deletion.

Add the entity mappings

Entity terms may vary across different systems. For example, a contact entity in one system could be a customer or person entity in another. This feature allows the implementation to know which entities in which systems refer to the same common entity.

Name	Description	Example
System	The system to which the entity belongs to	Pipedrive
System Entity	The name of the entity being used by the system	Pipedrive uses `person`
Map to Entity	Choose among the entities you added in Step 2, the common entity that System entity refers to	Contact

Setting up systems you want to sync

For each system you want to sync with, add a new system entry and provide the system's API URL, authentication details, and endpoints.
Define endpoints for different entities and specify the endpoint path, HTTP method, and operation (CREATE, UPDATE, DELETE).