×

Please give details of the problem

Docs

Find

    Developer Guide

    1. Composite API Example
      1. Scripted Lanes
      2. Compound Organization Hierarchy
      3. Dynamic Lanes
      4. Delegation
      5. Access Rights
      6. Runtime Lanes
        1. Todo Validation
      1. Release Your User Login
      1. Collections To Array
      2. Collections To List
      3. Collections BackOffice
      4. Collection JS Freemarker
          1. Composite API Design Tab
          2. Composite API Configuration Tab
          1. Providers
          2. Connectors
          3. Processes
          1. Roles entities
          2. Organization
        1. Collections
          1. Project Files Tab
          2. Project Definition Tab
          3. Project Versioned Files Tab
          4. Project Version Tab
          5. Project Description Tab
          6. Version
          7. Project Rights Tab
          8. Project Collection Tab
          1. Web Interface JS Tab
          2. Web Interface Design Tab
            1. Image Widget
            2. FileUpload Widget
            3. StaticText Widget
            4. ProgressBar Widget
            5. TextInput Widget
            6. JavaScript Widget
            7. Section Widget
            8. Geolocation Widget
            9. Checkbox Widget
            10. RadioButton Widget
            11. Tree Widget
            12. Spinner Widget
            13. History Widget
            14. URLInput Widget
            15. Tab Widget
            16. List Widget
            17. Array Widget
            18. HTML Editor Widget
            19. Report Widget
            20. Button Widget
            21. Custom Widget
            22. Captcha Widget
            23. HTML Widget
            24. Multi Checkbox Widget
          3. Web Interface Analytics Tab
          4. Web Interface Collection Tab
          5. Web Interface Implementation Tab
          6. Web Interface API Tab
          7. Web Interface Stylesheet Tab
        2. Revision
        3. Custom Lists
          1. Process Variables Tab
          2. Process Measures Tab
              1. Process Timer Event
              2. Process Start Event
              3. Process Intermediary Event
            1. Gate
              1. Process Task Loop Tab
              2. Process Task Manual Tab
              3. Process Task Email Tab
              4. Process Task Connector Tab
              5. Process Task SubProcess Tab
              6. Process Task Functional Tab
              7. Process Task Script Tab
            2. Process Step Output Variables
            3. Process Step Testing Variables
            4. Process Step Input Variables
          3. Process General Tab
          4. Process Design
          5. Process Input Tab
        1. Home
        2. My Applications
        3. Files
      1. Customer Management
        1. Messages
        2. Scheduled Process
        1. Process Examples
        2. Connectors
        1. Users
        2. Configuration
        3. Usage
        1. Web Interface Reports
          1. Measuring
          2. Runtime Users
          3. Execution Path
          4. Parameters
        1. CSS Examples
        2. CSS Personalization
      1. Performance
        1. Logout
        2. Redirection ExecutionMode
        3. Information Tags
        4. Basket
        5. Menu Bar
        6. Header
        7. Custom Login Page
        8. Mobile Devices
          1. homepage.css
          2. homepage.js
        1. Inject JSONObject
        2. Google Tables
        3. ArrayJSON to JSONArray
        4. Label Modification
        5. Number Currency Format
        6. Launch Process JQuery
        7. Date
        8. JQuery
        9. Round
        10. Holidays
        11. Array From WS
        12. Column Inactivation
        13. Print JSONObject
        14. Initialization Widget Date
        15. Invalid Fields
        16. List Reinitialization
        1. Tags
        2. Dialog Window
        3. Dynamic List
        4. User Lane Picker
          1. Report Chart
          2. Google Visualization
          3. Chart Dashboard
          4. Chart Dashboard Collection
        5. API Listener
        6. JavaScript Report
        7. Retrieving Variables Values
        8. Collection
        9. File Preview
        10. Autocomplete Widget
        11. Summing Array
      1. Trigger
      2. Markdown Template
        1. Task Reminder Email
        2. JavaScript Inclusion
        3. PDF
        4. SubProcess
        5. Backloop
        6. Variable Mapping
        1. Salesforce Computation
        2. Number Currency Format
        3. List Hash Sequence
        4. JSONObject Creation
        5. Freemarker Container Test
        6. JSONObject Concatenation
        7. Metadata
        8. Special Freemarker Characters
        9. List 1000+ Objects
        10. Dynamic Variable
        11. File Visibility
        12. Number Test
        13. JSONObject Keys Values
        14. Lock
        15. JSONArray Conversion
        16. Error Handling
        17. Loop
        18. Array To List
      1. Process Reporting API
      1. Offline
      2. Mobile

    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.