Capability

The master data synchronization capability is a central hub that keeps a "golden record" of the master data. The central golden record is a normalized model based on the union of the proprietary client models.

When data is updated in one of the clients, these changes will be validated and forwarded to all the other clients. This process is called the synchronization process and is fairly straight forward from the perspective of the clients:

Whenever a client has an updated master data record it informs the synchronization capability. The capability collects the updated master data record from the client, validates the data, updates the golden record and sends updates to all the other clients that have a copy of that specific master data record.

Contract

In most capability contracts, the contract only defines the API of the capability. The master data synchronization capability is different in this aspect; it also contains requirements on the client API.

Object data requirements

There are some semantic and syntactic rules when it comes to sending and receiving the data for a master data object:

• The object must have a single primary key. If this is not true for your client model, you can construct a "pseudo key" by combining the fields that make the object unique.
• All object attributes must be sent as strings.
• A null value for an attribute or a missing attribute means that the client has no information about the attribute. It will not affect the central golden record.
• Dates and times must be formatted according to ISO8061.

SynchronizedEntity.Updated

When a master data object has been updated in the client, the client must publish the business event SynchronizedEntity.Updated.

{
  "Key": {
    "ClientName": "string",
    "EntityName": "string",
    "Value": "string"
  },
  "Timestamp": "string",
  "UserName": "string",      // optional
  "Data": {}                 // optional
}

GET /{entityName}/{id}

The client must provide a GET method for every master data entity, so that the synchronization capability can retrieve updated data records.

The response must be one of the following:

• 200 OK
  The data was successfully retrieved. The response content must be a JSON representation of the object.
• 301 Moved Permanently
  The object has changed id. The response content must contain the new id and the corresponding URL should be returned in Headers.Location.
• 403 Forbidden
  The caller did not have sufficient privileges for this call.
• 404 Not Found
  No object with the specified id could be found. NOTE! 404 can be returned by the web server because of a number of reasons. Match needs to understand when the 404 is because the object really is not found in the system. To make that possible, the system must put the follwing JSON string (case insensitive) in the content part of the response: "CBF83F95-8A30-4887-B57B-3E471246D825".
• 410 Gone
  Same as 404, but for objects that the systems knows has been deleted. Should return the same text in the content part of the response as a 404.
• 500 Internal Server Error
  Some internal problem in the service.
• 501 Not Implemented
  Is used for a method that hasn't been implemented.

Example of a successful retrieval of data for an object of entity "Contact" and primary key 2345:

GET /Contact/2345
200 OK
{
    "FirstName" : "John",
    "LastName": "Doe",
    "Gender": "1",
    "Birthday": "1980-12-24"
}

PUT /{entityName}/{id}

The client should provide a PUT method for every master data entity, so that the synchronization capability can update the client data records as part of the synchronization process. The reason that it is not mandatory is to allow for "deaf" clients, i.e. clients that only provide their data, but will not listen to updates, e.g. external data providers such as Bisnode.

The response is the same as for GETabove, but with the following modifications:

• The following status codes are not used: 200 OK
• 204 No Content
  The update was successful.
• 400 Bad Reqeust
  The content of the request was not of the agreed format.
• 409 Conflict
  The data has been changed since the last GET, so the update is stale. The synchronization capability must make a new GET and base the update on that data.

Example of a successful update of data for an object of entity "Contact" and primary key 2345:

PUT /Contact/2345
{
    "FirstName" : "Jonny",
    "LastName": "Doe",
    "Gender": "1",
    "Birthday": "1980-12-24"
}
204 No Content

POST /{entityName}

The client can provide a POST method for a master data entity, so that the synchronization capability can create new client data records as part of the synchronization process. Normally, new master data entities should be created by other means than from the synchronization capability, but it can be used for some simple cases.

The response is the same as for GETabove, but with the following modifications:

• The following status codes are not used: 301 Moved Permanently, 404 Not Found, 410 Gone
• 200 OK
  The data was successfully created. The response content must be a JSON string with the newly created key.
• 400 Bad Reqeust
  The content of the request was not of the agreed format.

Example of a successful creation of data for an object of entity "Contact" that resulted in an object with primary key 2345:

POST /Contact
{
    "FirstName" : "John",
    "LastName": "Doe",
    "Gender": "1",
    "Birthday": "1980-12-24"
}
200 OK
"2345"