Creating a new Connector App
For creating a new connector app, press the Add button as shown below
After pressing the Add button the edit view is shown and you can start entering the connector app information.
Introducing data to create the Connector App
For creating a connector app you need to enter some information about the remote platform you want to access. So the UI will guide you to enter:
- The connector app name: a lower-case identifier
- Authorization type: the type of authorization.
- Authorization data: the parameters needed in the authorization process depending on the kind of authorization
- Connection data: the connection base URL and the connection parameters and headers
- Resource Data: For every type of record you want to handle you must enter its name, its primary key and the kind of process you want to conduct: import, export or both.
- Import Process Data: For every type of record you want to import, you need to enter the webhooks for importing one record and all the records.
- Export Process Data: For every type of record you want to export, you need to enter the webhooks for creating one new record and updating an existing record.
Let's see, in detail, how to create the connector.
At first you need to enter the connector app name, so a namespace will be generated from that name. Then you need to select the authorization type, and enter the authorization parameters according to the selected type. For example, in case of a basic authorization, you need to enter username and password as shown below
If you select an Oauth2 Authorization you must enter the header prefix to be used with the access token, the authorization endpoint, the access token endpoint, the client ID, the client secret and the list of comma-separated scopes. The picture below shows the authorization data of a connector app for accessing the Zoho CRM API.
Then you need to set the connection data. You need to enter the base URL for accessing the API resources and pairs name/value to be used as parameters or headers, if they are needed. The picture below shows the connection data of a connector app for accessing the Zoho CRM API.
After setting the authorization and connection, you must start editing the resources information, so you need to press the Add button in the Resources/Flows section
For every type of record you want to manage, you need to enter the resources information. For example, in the connector for accessing the Zoho CRM API, we want to manage records of type Contact and Lead. Let's see how to enter that information. After pressing the Add button, a view like the one below is shown and you must enter the data associated with one type of record, then press the Save button and you can repeat the process for every resource you need to add to the connector app.
At first you need to enter the resource name, the primary key name and the kind of process you want to conduct with that type of record: Import-Flow, Export-Flow or both. As you can see in the example below, a Data Type name will be generated according to the resource name.
Then you need to enter the webhook's details for the import and export process. In case of the import process (if it was selected in the kind of processes) you must set the http method (usually GET) and the resource path for requesting a single record and the http method and resource path for requesting multiple records. The resource path doesn't start nor end with the slash symbol, as shown below
In case of the export process (if it was selected in the kind of processes) you must set the http method (usually POST) and the resource path for exporting a new record and the http method (usually PUT) and resource path for exporting an existing record to be updated. The resource path doesn't start nor end with the slash symbol, as shown below
The picture above shows the Save button you need to press for finishing editing the resource data. After saving the resource data for the record of type Contact you can see it in the list as shown in the picture below.
Then you can repeat the process for adding new resources, for example Lead. After the Add button you can enter the resource name, its identifier, and the import process details
And if it was selected in the kind of processes, you must enter the details of the export process and press Save.
After completing the resource data input, you can press the Save button in order to create the connector app as shown below.
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 connector app in the list
Exploring the Connector App
Once a connector app is created you can explore its content in the Connector Factory by selecting the connector app 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 connector app was created.
When you explore the list of the connector app 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 connector app is a special kind of collection, the connector app can be managed not only from the Connector Factory main 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 webhooks.
You get the same result by accessing the menu Gateway/Resource Paths and list the elements in the corresponding namespace.
After the connector app is created, you might realize you missed to add some resource or some process type for a resource, etc. In those cases, you don't need to start creating the connector app from scratch, you can just press the Resume button to add new resources or edit the existing ones, so you can edit the connector app starting from the previous version and after pressing the Save button, a new collection will be generated for the new version of the connector app.
As mentioned before, when a connector app is created in the Connector Factory, a complete set of resources is generated in order to enable the import and export processes of a group of records. The table below contains all the elements implicitly generated in the connector app of the Zoho CRM API that we used as an example.
Element Kind | Elements in the Connector App | Observation |
---|---|---|
Security | default_authorization, default_client, default_provider | The authorization, the authorization client and the authorization provider for getting access to the remote platform. |
Connection | default_connection | The connection to the remote platform |
Data Types | Contact, Lead | One data type for every resource which was added to the connector app. |
Data Events | handle_contact, handle_lead | One data event for every resource which was added to the connector app. |
Resources for Contact | get_contact, get_contacts, create_contact, update_contact | The webhooks for importing and exporting records of type Contact |
Resources for Lead | get_lead, get_leads, create_lead, update_lead | The webhooks for importing and exporting records of type Lead |
Algorithms for Contact | do_import_contact, do_import_contacts, do_get_contacts, do_get_contact, parse_from_api_response_contacts, trigger_for_change_contact, do_export_contact, do_create_contact, do_update_contact, parse_2_api_request_contact | The algorithms for importing and exporting records of type Contact |
Algorithms for Lead | do_import_lead, do_import_leads, do_get_leads, do_get_lead, parse_from_api_response_leads, trigger_for_change_lead, do_export_lead, do_create_lead, do_update_lead, parse_2_api_request_lead | The algorithms for importing and exporting records of type Lead |
Algorithms | do_check_error_response, do_generate_hmac | The algorithm for processing errors in the response and the algorithm for generating the hmac of a record. |
Applications | default_app | An application where the incoming webhooks can be defined. Its details are explained in the section understanding_the_incoming_webhooks_elements |
Algorithms | action_hook, action_check_hook | The action algorithms to be used in the incoming webhooks. Their details are explained in the section understanding_the_incoming_webhooks_elements |
Algorithm for Contact | do_start_converters | The algorithm used by the Recipes to find the existing algorithms for mapping a Contact record to records of other Data Types. Its details are explained in the section understanding_the_recipe_elements |
Algorithm for Lead | do_start_converters | The algorithm used by the Recipes to find the existing algorithms for mapping a Lead record to records of other Data Types. Its details are explained in the section understanding_the_recipe_elements |