Composite API Example
A composite API is a sequence of tasks that runs synchronously and which execution path is not persisted. (@see Composite API Technical Description)
This tutorial will show you how to configure a composite API within a web interface or within a process with a precise example : a composite API that retrieves Accounts Id's And Owners' Name from ZohoCRM on a given Account Name.
Inputs and Outputs
Here's what we will need as input data to use in the API composite:
- account_name (The name of the account we want to get its details).
And here's what the composite will return as a result:
-
account_id (the id matching with the account_name).
-
account_owner (the owner matching with the account_name).
Import Connectors
Before creating the Composite API, we will need to import two connectors into our project. The First one will allow us to login to ZohoCRM and the second one to retrieve the accounts details.
You will find the two connectors in the library under:
1. Zoho CRM (Provider's name)
- Get Accounts From Matching Account Name (Connector's name)
2. Zoho API Login (Provider's name)
- Login ZohoCRM (Connector's name)
More details on how to import a connector.
Create The Composite API
Now in the project, click on New => Composite API as follow:
In the Configuration tab:
(1) Choose application/json as Accept media type. That means Input validation field must be a json
(2) Add in the Input Validation the following code:
1 |
|
(3) Choose application/json as Result media type.
Do not forget to add a description of the input and output of your composite API to make it easier for you to remember them once you need to use this composite API again later.
NOTE: All of the secured variables will not figure in the result of the composite API, therefore in this example, we'll check the secured checkbox for all of the variables except for the ${account_id} and ${account_owner} as we need their value in the output.
Go to the design tab. Your final composite API will look like follow:
Login To Zoho
Click on the first yellow box, configure the Type as Connector:
Go to the Call a connector tab:
(1) Choose a provider
(2) Choose the provider you've imported. In this case its called Zoho API Login
After connecting the provider do as follow:
(1) Click on the Search connector in the directory
(2) Choose your connector
Once your connector is connected, you will see in the input variables tab that two variables were automatically generated : login and password.
That means that the connector needs to be provided values for these variables in order to work. Replace ${login} and ${password} with your own login and password.
Now go to the output variables tab and add the following variable:
This variable "authtoken" will contains the authentication generated after the login.
Get Accounts Details
Click on the second yellow box, configure the Type as "Connector":
Go to the Call a connector tab:
(1) Choose a provider
(2) Zoho CRM
After connecting the provider do as follow:
(1) Click on the Search connector in the directory
(2) Choose your connector
Once your connector is connected, you will see in the input variables tab that two variables were automatically generated : account_name and authtoken.
That means that the connector needs to be provided values for these variables in order to work.
Now go to the output variables tab and add a variable:
Leave the name of the variable empty, then enter the following code for its value:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
Leaving the variable name empty will allow us to directly inject the ${account_id} and ${account_owner} variables.
Trigger The Composite API
Web Interface
Create a new Web interface. In the design tab do as follow:
(1) Add a text input:
- Label 'Account Name'
- Variable account_name
(2) Add a spinner widget:
- identifier : id_spinner
(3) Add an HTML widget :
- identifier : id_html
(4) Add a hidden split widget
(5) Add a JS widget containing the following code:
1 2 3 4 5 6 7 |
|
(6) Add a JS widget that listens to the variable account_name and contains the code that will trigger your composite API:
Therefore, RunMyprocess gives you two different ways to trigger the composite API:
First Method
Insert the following code in your JS:
1 2 |
|
After entering your account name,the variable it will set the variable "variables_defined" will be set and will trigger the composite API.
Now go to the API call tab:
(1) Click on Choose a composite API
(2) Choose the API you have created before
Then do as follow:
(1) Choose Listened variable changed
(2) Listen to variables : variables_defined
(3) Check the Completed box
(4) Insert the following code:
1 |
|
Now test your web interface, enter your account name and wait, you'll have a similar result:
Second Method
Insert the following code in your JS:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
After entering your account name,the variable will trigger the script above and by that triggers the composite API.
By default, all composite APIs are triggred asynchronously. If you need synchronous requests, set the option asynchronous to false;
var options = {"asynchronous":false}
. However, asynchronous requests should be preferred to synchronous requests for performance reasons.Synchronous requests are not available for web interfaces that do not have JQuery library.
Synchronous requests have been deprecated by some browser vendors, their support may be completely removed in next releases.
Now go to the API call tab:
(1) Click on Choose a composite API
(2) Choose the API you have created before
Then do as follow:
(1) Choose Manually Via JavaScript
(2) Identifier : id_get_account_info
Now test your web interface, enter your account name and wait, you'll have a similar result:
Process
Create a new process and design as follow:
Click on the yellow box, configure the Type as "Connector":
Go to the Call a connector tab:
(1) Choose a provider
(2) Click on RunMyProcess Server. This provider is hidden in the project tree but exists in every project and contains all of the composite API of your project.
After connecting the provider do as follow:
(1) Click on the Search connector in the directory
(2) Choose your composite API
Once your connector is connected, you will see in the input variables tab that the variable you have defined earlier in your composite API as an input variable was automatically generated : account_name.
That means that the connector needs to be provided value for this variable in order to work.
Now go to the output variables tab and add the following variable:
Third Party
In order to trigger a composite API from a third party system, you need to be first of all authenticated : use a basic authentication (login/password). In this example, you will need to do a POST on the url of your composite API. You'll find this url in the configuration tab of your composite API under "connector url".
Here's the needed configuration:
1 2 3 |
|
That's what you'll see in the dev console:
Debugging and Maintenance
Since the composite API execution path is not persisted, the test and debug should be thought very differently from what is done with processes.
Testing your Composite API
In order to test the composite API you need to add the variables used in input for the composite API. In the example above, the input variable was account_name:
Once you've configured your variables, click on the launch test button. If the Composite API is successful, the result will be shown on the left panel in the Result
and Processed Result
tabs.
To be sure that the variables account_id
and account_owner
are successfully injected, you should be able to see your variables in the Processed result tab as shown in the picture above.
If the Composite API fails, the error code and the error message can be retrieved in the Processed Result
tab.
Debugging your Composite API
If you want to track the result of account_id
variable, you can also add the following output variable on the second box 'Get Accounts Ids From Account Name':
This will create a custom log
in the Logs Application with a level FINEST
.
1 2 3 4 5 6 |
|
Retrieving errors
Unhandled errors can be retrieved in account logs, whatever the trigger used to launch the Composite API (Tester, Web Interface, Process task) or the execution mode (LIVE
, ACCEPTANCE
, TEST
). When the execution of a composite API fails, the error is logged and can be searched for in the Composite API Logs
tab of the Logs Application
(@see Composite API).
The platform also provides a freemarker methods throw
that enables you to throw an error and stop the execution.
Let's imagine that we want to abort the execution of the composite API described above when the retrieved account_id is equal to 1253648513589
and throw the following message to the user :
The id of the chosen account name won't be given for security reasons, please try another account name.
To do this, all you'll need to do id add a new variable as an output of the second box with the following code:
1 2 3 |
|
In order to test this error, launch your composite API by clicking on the launch test button as shown above. The execution will return an error code 400
and the error message you've configured in the throw
method:
Depending on trigger of the Composite API, the error can also be retrieved in the execution context.
- If the composite API is called as a listener in a web interface, the error message will be returned in a
P_error
variable. - If the composite API is triggered by a process task, the error message will be returned to the request
P_message
variable.
Please give details of the problem