×

Please give details of the problem

Skip to content

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:

img1

In the Configuration tab:

img2

(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
 {"account_name":"${account_name}"}

(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:

img3

Login To Zoho

Click on the first yellow box, configure the Type as Connector:

img4

Go to the Call a connector tab:

img5

(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:

img6

(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.

img7

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:

img8

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":

img9

Go to the Call a connector tab:

img10

(1) Choose a provider

(2) Zoho CRM

After connecting the provider do as follow:

img11

(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.

img12

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:

img13

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
<#assign account_id ="">
<#assign account_owner ="">
<#list P_result.response.result.Accounts.row.FL as x>   
    <#switch x.val>
        <#case "ACCOUNTID">
            <#assign account_id = x.content>
         <#break>
        <#case "Account Owner">     
            <#assign account_owner = x.content>
    <!--#switch-->
<!--#list-->
<#assign hub>
{"account_id":"${account_id}","account_owner":"${account_owner}"}
<!--#assign-->
${hub}

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:

img14

(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
function load_data(account_id,account_owner){
var result="";
result = result + "Account ID = "+account_id+"<br>";
result = result + "Account Owner = "+account_owner+"<br>";
id_html.setHtml(result);
id_spinner.setVisible(false);
}

(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
RMPApplication.set("variables_defined",Math.random());
id_spinner.setVisible(true);

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:

img15

(1) Click on Choose a composite API

(2) Choose the API you have created before

Then do as follow:

img16

(1) Choose Listened variable changed

(2) Listen to variables : variables_defined

(3) Check the Completed box

(4) Insert the following code:

1
load_data(P_computed.account_id,P_computed.account_owner);

Now test your web interface, enter your account name and wait, you'll have a similar result:

img17

Second Method

Insert the following code in your JS:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
function ok(P_computed){
    load_data(P_computed.account_id,P_computed.account_owner);
}

function ko(P_error){
    alert(JSON.stringify(P_error));
    id_spinner.setVisible(false);
}

var input = {"account_name":RMPApplication.get("account_name")};
var options = {};

id_spinner.setVisible(true);
id_get_account_info.trigger(input,options,ok,ko);

After entering your account name,the variable will trigger the script above and by that triggers the composite API.

info_1 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.

info_2 Synchronous requests are not available for web interfaces that do not have JQuery library.

info_3 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:

img15

(1) Click on Choose a composite API

(2) Choose the API you have created before

Then do as follow:

img30

(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:

img17

Process

Create a new process and design as follow:

img18

Click on the yellow box, configure the Type as "Connector":

img19

Go to the Call a connector tab:

img20

(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:

img21

(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.

img22

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:

img23

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
contentType : "application/json"
Accept : "application/json"
Body: {"account_name" : "y3b"}

That's what you'll see in the dev console:

img24

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:

img25

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.

img26

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':

img27

This will create a custom log in the Logs Application with a level FINEST.

1
2
3
4
5
6
Date : "2015-04-06 12:00:01"
Log Level : FINEST
Message : 12345678910
Process ID / Composite API ID : xxxx
Project ID : xx
Request ID : xxxxxx-xx-xxxx-xxxx-xxxxxx

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
<#if account_id=="1253648513589">
    ${throw("The id of the chosen account name won't be given for security reasons, please try another account name.")}
<!--#if-->

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:

img329

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.