The following section will outline how real time synchronization will work between the Dsync API and a System through the use of a connector. The connector will act as a mechanism to send and receive data from source and destination endpoints respectively.
Job ID and Entities
Job IDs are automatically assigned to an endpoint when a relationship is created in Dsync. The ID is saved in the connector as part of a predefined entity and is used throughout the connector to load a type of entity to be updated with destination data or sending source data to Dsync that was updated. There is a one to one relationship between the entity type and the Job ID per user and they are delivered from Dsync to the connector and need to be saved against the entity (please refer to the attached destination.html > ‘Add job for entity’ web service).
Primary Keys (Dsync IDs)
Each entity will have a primary key (or Dsync ID) that needs to be made available in order to synchronize data from different systems. This primary key will be defined in the data layout of each entity using the ‘primary_key’ boolean tag (please refer to the attached destination.html > ‘Get data layout’ web service).
The primary key can be changed from within the DSYNC application’s dashboard using the ‘Shared Key’ dropdown. DSYNC handles this change internally so there is no web service call needed.
Entity Field Mapping
Each entity in the connector should have the ability to dynamically create their own data layout/schema (please refer to the attached destination.html > ‘Get data layout’ web service). The layout will be requested from Dsync at the time a new system is added onto the canvas within the DSYNC application’s dashboard. Changes to the data layout of an entity should be monitored by the administrator and replicated in the DSYNC dashboard (eg. new data field added to a product entity).
Each entity will contain the entity name, an entity token, the endpoint url, a treekey value and data fields.
This will be the name of an entity (eg. ‘product’ or ‘order’)
An entity token is a unique identifier for an entity. It will need to be generated by the connector in a way which it will be different for every entity and any user of the connector. The recommended structure of the entity token is the combination of endpoint type (source or destination), entity name, and a md5 hash of microtime.
The endpoint url is a url that defines where requests will be sent from Dsync to the connector for a particular entity.
The treekey is an identifier for the entity within the structure of the data layout. It will usually be the name of the entity.
Each field within the data layout is broken down into the following: name, description, treekey, type, multiple, required, date_format, foreign_key, and primary_key.
The name is the name of the field.
The description is a written description of the field.
The treekey is a key identifier for the field within the structure of the entity. It will usually be the treekey of the entity with the name of the field separated by a period. An example would be product.name which would specifiy that it belongs to the “product” entity and has a field name of “name”.
Treekey is optional. If you don’t specify treekey, DSYNC will generate it for you based on the ‘name’ tag of each field.
The following field types will need to be assigned to a field within the connector despite their actual type:
- Text (string, varchar, etc)
- Number (integer, decimal, etc)
- Boolean (true/false)
Multiple is a boolean value that will indicate that there are multiple (repeating) values on a single field when it is true. An example of where this would be used is if the field was an array (eg. shipping and billing address inside ‘addresses’ multiple object field).
Required is a boolean value that will indicate whether the field is required or not.
Specifies the format for date, time, or datetime field within the data layout. Please refer to the moment.js documentation for all accepted formats.
Foreign key tag holds textual value (string) and indicates that the field is a primary key of another entity within the system. This usually applies to nested objects. The foreign_key value must reflect the name of the foreign entity to which it belongs as per the data layout specified.
Consider a system with the following entities each with its own data layout: product, customer, order. Order entity contains information about the customer as well as the products ordered so the order data layout includes the customer and product data layout as nested objects. Assuming the customer entity primary key is set on the ‘email’ field, we need to set the foreign_key of order.customer.email field to the value of the foreign entity which in this case is ‘customer’.
Primary key tag is a boolean tag (true/false) which indicates that give field is the primary key of an entity. See Primary Keys section above for more details. This tag is only required on one field within the data layout.
The following is a simple example for a single entity within a data layout. A full example is attached to this document:
Enable / Disable Synchronization
The connector must have the ability to enable and disable synchronization for all entities (enable/disable connector) and for each individual entity.