Converters
When implementing a basic integration, we usually need to transform data from one type A to a type B. Converter translators create records of a data type B inside Cenit from records of a data type A which were already stored in Cenit. So, It deals with two data types, the type A, which is referred in the converter as source data type, and the data type B, also known as target data type.
You can manipulate converters via CENIT IO API V2. In order to do that, see specifications for this API in the section Converters.
Add New​
The submenu Transformations/Converters allow to create a new converter translator by clicking the New button (+) in the Generic Menu and selecting the type of converter you want to define, for example, Ruby Converter, which refers to a converter written in a DSL based on the Ruby Programming Language, so the logic of the converter translator is described in ruby style. When creating the converter translator, you may select the most suitable Converter Model depending on the data format you need to handle.
After selecting the kind of parser you can start filling every field.
Source Data Type:
It defines the type of the records to be transformed. You can select a data type previously defined or define one by pressing the + button. This field is required.
Target Data Type:
It defines the type of the records to be created. You can select a data type previously defined or define one by pressing the + button. This field is required and it may be equal to the source data type, which could be useful in those cases when you are not intended to change the data structure but only the information.
Discard Events:
Set discards events false in order to make the translator available to be executed when an event triggers a flow execution. When it is set true all the events are ignored and it could be executed only by processing the flow manually.
Source Handler:
Set source handler true in order to enable the processing of multiple records. When it is false the converter is able to handle only one record.
Code:
Define the algorithm to receive the requested data and store it in Cenit. In case of a Ruby Converter, it is written in a DSL based on the Ruby Programming Language. Other formats are available depending on the type of converter created. The code of a converter is handled by Cenit as a Snippet. It doesn't mean you are forced to create or edit a snippet when coding, you may just modify the code field and Cenit implicitly updates the linked snippet.
The main goal of a transformation is to manipulate data. The objective of a converter translator is to transform data from one type to another. In order to facilitate the data management, some pre-defined variables are available to access data from the translator code. The most important pre-defined variables are described in the table below.
Pre-defined variables​
| Variable | Semantics | Pre-conditions to use it |
|---|---|---|
| source | If the field Source Handler is false, the variable "source" allows to access to the record to be transformed, in other words, before executing the converter translator, Cenit implicitly fill the variable "source" with the record sent to the converter flow and make it available in the translator. | The field Source Handler is false |
| sources | If the field Source Handler is true, the variable "sources" contains the enumeration of records to be transformed, in other words, before executing the converter translator, Cenit implicitly fill the variable "sources" with an array which contain all the records sent to the converter flow and make it available in the translator, so by iterating over the variable "sources" we can transform every record in the enumeration. | The field Source Handler is true |
| target | If the field Source Handler is false and the converter is able to handle only one record, this variable allows to configure the new record to be created from the source record, that means you don't need to explicitly use a statement of type create_from_json to create a record for the target data type, by setting the properties to the object "target", Cenit implicitly creates the record. | The field Source Handler is false |
| target_data_type | This variable allows to access to the type of the records to be created in a easy way. So, if we set the field Target Data Type of the converter as Test|SlackMessage, in the code we can refers to it as: target_data_type instead of: Cenit.namespace('Test').data_type('SlackMessage') | The target data type was set, it's required in the converter definition |
When these variables are used together, the code becomes simpler. For example:
target.full_name = source.name
target.birthday = source.bday
target.age = "#{source.age} years old"
This code creates a new record with properties full_name and birthday instead of name and bday. In case of the age, the property has the same name but now is a string containing the original age value followed by "years old". You should notice the Source Handler field should be set false in order to access the variable source and also notice a statement of type create_from_json is missing because it's optional when using the pre-defined variable "target".
When processing several records, the Source Handler field should be set true in order to access the variable sources in the code which would be like the one below:
sources.each do |source|
    target.full_name = source.name
    target.bithday = source.bday
    target.age = "#{source.age} years old"
   target_data_type.create_from_json!(target)
end
The code may vary not only because the transformation we need to implement can be complex, but also due to the different kinds of converters we are able to create, so you should know the Converter Models which are available to be used when defining converter.
After completing the converter declaration and pressing the save button, you can see the new converter translator on the list of converters and you can manage it as well as you can do with other elements in Cenit.
Converter Models​
When creating a converter translator, you are able to select the most suitable kind of converter according to the format of the data you need to transform.
Regardless what you model you choose, you need to notice the result format should be JSON or XML, on the contrary Cenit will try to use an EDI Parsing Algorithm to fill the target record properties.
Ruby Converter​
The logic of the converter translator in a Ruby Converter is described in ruby style. It is written in a DSL based on the Ruby Programming Language.
When coding the transformation, both variables: source and target, allow to access the current record and the new record to be created, respectively. For example:
When processing is finished, a new record is created from the target variable and no statement of type create-from_json is required.
You should notice the pre-defined variable sources is used instead of source. The pre-defined variable target is not available either. Unlike the previous example where a single record is created automatically from target, in case of iterating, you need to explicitly create the record by using a statement of type create_from_json. By specifying the primary_field you guarantee same records could be updated instead of creating new ones.
Liquid Converter​
When using transformations such as Liquid templates, you should consider they are just template engines and so they can be used to produce any kind of content type, for example, JSON content. So if you define a Liquid Converter with the code below, the converter will detect the produced content has a JSON format and will parse it to create or update a record. The variable "source" is also available to access the current record.
Learn more about liquid templates in Introduction – Liquid template language
Handlebars Converter​
When using transformations such as Handlebars templates, you should consider they are just template engines and so they can be used to produce any kind of content type, for example, JSON content. So if you define a Handlebar Converter with the code below, the converter will detect the produced content has a JSON format and will parse it to create or update a record. The variable "source" is also available to access the current record.
Than code looks similar to the liquid template code shown above, however it's a handlebar one. Learn more about handlebar templates in Introduction | Handlebars
XSLT Converter​
When using transformations such as XSLT templates, you should consider they are just template engines and so they can be used to produce any kind of content type, for example, JSON content.
Even if records are not stored in XML format an XSLT transformation is possible for Cenit by following the steps below:
Format the source record into XML if necessary.
Applies the XSLT transformation to the XML formatted record.
Create a target data from the transformed XML document.
Of course, is simpler to use for this case a template like Liquid or Handlebars.
Mapping Converter​
The Mapping Converter provides an attractive way to define the translation through a table which allow to set a value for every property defined in the target data type. You should notice that the access to the source record can be done by using the {{ }} tags as in a liquid template; however the variable source is not available, so you may access the property name directly.
The Mapping Converter makes easy the transformation; nevertheless you should notice it may be used only for achieving simple transformations.