Creating a new Recipe
Precondition to create the Recipe​
The Recipe uses a Connector App previously created to implement the maping process, so, for creating a Recipe you need two Data Types defined in one or two Connector Apps. Then, a Recipe for implementing the mapping process between two Data Types A and B need these resources have been created in advance:
A Data Type A in a Connector App A where the import process have been defined for the Data Type A.
A Data Type B in a Connector App B (or even in the same Connector App A) where the export process have been defined for the Data Type B.
The picture above shows two Connector Apps we are going to use as an example to create a Recipe for mapping a User in the Connector App slack to a Contact in the Connector App zohocrm. Nevertheless, it's possible to use only one Connector App, for example we can create a Recipe for converting a Contact in zohocrm to a Lead in zohocrm. In this case, both Data Types are defined din the same Connector App zohocrm, we just need to guarantee the import process is implemented for the Data Type Contact and the export process is implemented for the Data Type Lead.
On the other hand, you mustn't understand this precondition as you will be forced to create the Connector App from scratch prior to creating the recipe. For example, if you access the Connector Factory in your tenant and the list of Connector Apps is empty as shown below:
the reason is there is no collection of type Connector App available in your tenant, as the screen below shows:
A solution to that issue could be creating one or more Connector Apps from scratch. However, you can also import one or more collections of type Connector App to your tenant:
So, after bringing the collections into your tenant:
the Connector Apps will be shown in the list of connectors and consequently available for being used in the Recipe.
Creating the Recipe​
For creating a new connector recipe, press the Add button as shown below
After pressing the Add button the edit view is shown and you can start entering the recipe information.
Introducing data to create the Recipe​
For creating a recipe you need to enter some information about the connector apps involved in the mapping process you want to implement. So the UI will guide you to enter:
The origin connector
The destination connector (could be the same connector selected as origin on the condition that it contains two or more Data Types)
For every mapping process you want to implement:
The origin data type
The destination data type
The mapping code
Let's see, in detail, how to create the recipe. We are using as an example the creation of a Recipe for mapping a Slack User to a Zoho CRM Contact.
At first you need to select the origin connector (Slack in the case of the example) and the destination connector (Zohocrm in the case of the example). The namespace (SlackToZohocrm in the case of the example) and the name of the collection (slack_to_zohocrm in the case of the example) are generated automatically from the origin and the destination connectors.
Then you need to press the + button in the section Parsers to define the mapping process.
After pressing the + button, a view like the one below is shown and you must select the origin Data Type (User in the case of the example) and the destination Data Type (Contact in the case of the example).
In the same view you can specify the mapping code or you can choose to keep the default code in order to modify it later, after the Recipe is generated. You should notice the mapping code will be available to be modified later in the algorithm parse_from_sourceNS_sourceDT_to_targetNS_targetDT (in the case of the example: parse_from_slack_user_to_zohocrm_contact)
For setting the mapping code you need to notice you need to convert the object stored in the property raw_data in the source to an object to be stored in the property raw_data in the target and you need to map any other property outside the raw_data in the case you need it. In the case of the example we need to map every property in the raw_data.profile object to a property in the raw_data object in the target. The sample code is shown below.
# Write here the mapping code
target = {
raw_data: {
Email: options[:source].raw_data[:profile][:email],
Last_Name: options[:source].raw_data[:profile][:last_name].present? ? options[:source].raw_data[:profile][:last_name] : '-',
First_Name: options[:source].raw_data[:profile][:first_name],
Full_Name: options[:source].raw_data[:profile][:real_name],
Skype_ID: options[:source].raw_data[:profile][:skype],
Phone: options[:source].raw_data[:profile][:phone]
}
}
target
After completing the mapping code you can press the save button for completing the definition of the mapping process as shown below.
The recipe may contain more than one mapping process. For adding a new mapping process you need to press the + button again (see 1 in the picture below). Since a connector might contain more than one data type, you would want to map more than one pair of data types between the same connectors. For example, The zohocrm connector app contains two data types: Contact and Lead. If we want to map the User in the slack connector app to the Lead in the zohocrm connector app, we may not create a new Recipe between the connectors slack and zohocrm because the recipe name would be the same: slack_to_zohocrm (see 2 in the picture below). So, cases like this one must be implemented as a single Recipe with multiples mapping processes.
After completing the definition of the mapping process, you can check the information of the recipe is completed and press the Save button in order to create the recipe as the picture below shows (You should notice we finally didn't add the mapping process between the Slack User and the Zohocrm Lead).
When the creation process completes, you will be notified in a view like the one in the picture below
Then you can press the Back button
And you will see the recipe in the list
Exploring the Recipe​
Once a recipe is created you can explore its content in the Recipe view in the Connector Factory by selecting the recipe and pressing the Details button.
After pressing the Details button a list of elements is shown. That list contains all the elements generated implicitly by the Connector Factory when the recipe was created.
When you explore the list of the recipe elements in the Conector Factory, you are able to select one element and see its details.
That action redirects the user to the show view in Cenit, so, the user will be able to manage that element the same way he can do with any other one in Cenit.
Since a recipe is a special kind of collection, the recipe can be managed not only from the Connector Factory Recipe view but also from the Collections Menu in Cenit.
As you can see in the picture above, a collection has been created in the current tenant and you can manage it as any other collection in Cenit. So, if you select the collection and press the Show button, you can explore its elements directly in the Cenit UI, for example, the algorithms.
You get the same result by accessing the menu Compute/Algorithms and list the elements in the corresponding namespace.
After the recipe is created, you might realize you missed to add some parsers or you had some mistake, etc. In those cases, you don't need to start creating the recipe from scratch, you can just press the Resume button, so you can edit the recipe starting from the previous version and after pressing the Save button, a new collection will be generated for the new version of the recipe.
As mentioned before, when a recipe is created in the Connector Factory, a complete set of resources is generated in order to enable the mapping processes of a group of records. The table below contains all the elements implicitly generated in the recipe slack_to_zohocrm that we used as an example.
Element Kind | Elements in the Connector | Observation |
---|---|---|
Data Types | ItemsMapped | One data type for storing information about every record mapped. |
Algorithms | do_convert_from_slack_user_to_zohocrm_contact, parse_from_slack_user_to_zohocrm_contact | The algorithms for mapping the records of type User to records of type Contact. Two algorithms for every mapping process defined in the recipe are generated. |
Other Algorithms | trigger_for_change_user, do_start_converters | This algorithms are actually generated when a Connector App is created. However they are closely related to the recipes, that's why we include them in this table. |
Data Event | handle_user | This Data Event is actually generated when a Connector App is created. However its closely related to the recipes, that's why we include it in this table. |