As already mentioned the transformer transforms one JSON object into another. Prior to this transformation a semantic mapping has to take place where the entities of the source model are mapped against the entities of the Open Integration Hub master data model.
As can be seen in the connector overview a transformer should transform data in both directions:
- From source model to Open Integration Hub master data model
- From Open Integration Hub master data model to source model
A transformer expects a JSON object as an input. Depending on the direction of the transformation the input either represents the structure of the proprieraty data model (flow direction 1) or the structure of the Open Integration Hub master data model (flow direction 2). Afterwards it transforms the incoming JSON object into another JSON object e.g. via a transformation language (We suggest JSONata for the transformation). Depending on the transformation direction, the transformer’s output is then send either to the Open Integration Hub and is validated against a deposited JSON schema or to the corresponding adapter.
Note: As the Open Integration Hub is feasible of storing different data models, it is also possible that the mapping of the source model is done against another model than the Open Integration Hub master data model. An example of how an implementation with individually uploaded data models could look like is presented under the section possible implementations.
One way of transforming the JSON objects is the usage of a transformation language. As already mentioned our suggested transformation language is JSONata as it is especially built to transform one JSON object into another.
For detailed information on transformation language and JSONata as well as a general example please have a look at TransformationLanguage
Sometimes there is a need to change the existing data model to adjust to different requirements. In this case, a transformer needs to be adjusted/updated in order to be compatible with the newest version of the data model.
Some changes do not affect existing mappings/transformations and transformers can still be used (although they are not reffering to the newest model version). Thus, backward compatibility is automatically given. According to the OData specification (shortened/modified list) the following changes do not require a change within a transformer:
- Adding an attribute that is nullable
- Adding an object to the model
- Adding a new complex type to the model
- Adding an option to an enumeration
Apart from this various changes require transformer adjustments as they break existing mappings/transformations. Thus, backward compatibility is not automatically given (in case the Open Integration Hub operator does not run both model versions in parallel). The following list provides an overview of changes that require a transformer adjustment:
- Renaming an existing attribute
- Changing the type of an existing attribute
- Changing the properties of an existing attribute from nullable to not nullable
- Deleting an existing attribute
- Renaming an existing object
- Deleting an existing object
- Adding an attribute that is not nullable
If a new version of a model is created, two options exist to create a transformer that is compatible with the newest model version:
- The existing transformer is adjusted/updated according to the structure of the new data model.
- A completely new transformer is built.