The Open Integration Hub (OIH) provides an asynchronous way of integrating applications and services. Modelling data which is processed by an OIH instance must always consider this fact!
One consequence is, that it must be possible to send data records to and receive them from an OIH without the need or even possibility for the receiver to eagerly fetch referenced further records of any kind through an API or data store (like the (optional) OIH Data Hub).
This is where the OIH's Master Data Models come into play:
There is not the one canonical data model for the OIH as such a canonical data model would result in massive communication effort, idle times and workarounds. Instead a model for each context (domain) is defined:
- An OIH Master Data Model (OMDM) describes the data of a certain domain in a depth which is sufficient enough to map and synchronize the specific data of multiple applications in that domain.__
In other words, an OMDM is a generic data model in the context of a specific domain, which is designed to cover, if possible, all content-related requirements of the applications integrated with the model. It should be designed with following criteria in focus:
- All use cases for the different integration scenarios between the involved applications can be matched and the data of all those applications can be mapped to the model.
- The model is generic and it can be extended on the application level.
Using the OIH's (optional) Data Hub, an OMDM enables a Master Data Management for the respective domain by centrally storing the data of the integrated applications.
A data model representing a certain professional domain normally consists of numerous entities. Hence, it is necessary to split such a data model into smaller parts to enable the transfer of optimized amounts of data through an OIH:
- Every OMDM consists of one or multiple loosely coupled sub-models.
Although it is necessary to split (especially big) data models into smaller sub-models, it often does not make sense to send each entity on its own, when there is a high cohesion between certain entities. Hence,
- each sub-model of an OMDM can consist of one or more entities.
- In case a sub-model consists of multiple entities, it must be modeled as an aggregate:
Aggregate is a pattern in Domain-Driven Design. A DDD aggregate is a cluster of domain objects that can be treated as a single unit. An example may be an order and its line-items, these will be separate objects, but it's useful to treat the order (together with its line items) as a single aggregate.
An aggregate will have one of its component objects be the aggregate root. Any references from outside the aggregate should only go to the aggregate root. The root can thus ensure the integrity of the aggregate as a whole.
To enable the OIH to follow its purpose, the data records being processed have to fulfill some criteria and follow some rules. Some of these rules have to be applied already on the modelling level.
An OIH expects and needs, depending on the scenario and the involved components (e.g. with or without a Data Hub involved), more or less meta data on a data record to integrate two or more applications. This is achieved by modelling each sub-model of an OMDM as a so called OIH Data Record. The OIHDataRecord defines a superset of mandatory and optional (meta) data for records processed by an OIH instance:
Each of the the sub-models of an OMDM has to be marked as an OIHDataRecord.
I.e., the root of an OMDM's sub-model must inherit from / extend OIHDataRecord, no matter whether it is modeled as an aggregate or as a single entity.
The OIHDataRecord contains...
- the datasets identifier within the OIH
- its creation and last modification dates within the OIH.
- an array of modification objects to track the modification history
Every record passed into an OIH instance must at least be provided with a reference to the record of the application or service being the source of the record,
called an ApplicationDataRecord containing ...
- the OIH's identifier for the application,
- the record's ID within the application (both mandatory) and
- its creation and last modification dates within the application.
- an array of modification objects to track the modification history
When receiving such a record from an OIH, there might also be entries of other applications being part of the integrations scenario with the same OMDM in the same OIH.
Additionally, depending on the scenario and the involved components again, the OIH itself or a connector may also provide an OIH-internal UID for the record, along with the creation and last modification dates of the record within the OIH.
The OIH specifies JSON as the format that data is processed with. Accordingly,
- JSON Schema is the given format to describe OMDMs
in a way an OIH instance is able to validate data at runtime. And, as OMDMs are split into sub-models and the records of those sub-models must be processable independently,
- for every sub-model of an OMDM there must be a seperate JSON schema describing the entity or aggregate.
As there are situations where entities are reused in (i.e. are part of) two or more aggregates, it is of course adequat to encapsulate those entities in an additional schema file and reference them from the several sub-models to avoid redundancy.
There is a predefined JSON-Schema defining the OIHDataRecord (s. /src/main/schema/oih-data-record.json).
- Every sub-model of an OMDM must reference the OIHDataRecord schema and "inherit" from the defined type.
This is done by adding an allOf-element to every sub-model's schema:
{
"$schema": "http://json-schema.org/schema#",
"$id": "http://example.com/schemas/oih/my-model.json",
"title": "MySubmodelAggregate",
"allOf": [
{
"$ref": "http://openintegrationhub.org/schemas/oih-data-record.json"
}
],
"properties": {
...For a sales application, one could split the data model at least into the following sub-models, each of which built as an aggregate:
- Order
- Address
- Article
- ...
As an example to model an aggregate capable of being processed of an OIH instance, the following diagram shows a simplified order with its line items:
The Order's root defines the model as an OIH Data Record by extending it. This way, the Order entity is the one and only entry point to the aggregate.
The JSON schema for this example is accessible under /src/examples/schema/order.json.