API Listener

In a web interface you can retrieve data or perform action by executing API listeners. An API Listener is both a resource that you can launch from a web interface and how this resource is launched. This page will present the various options that you can use to add complex interactivity in your web interfaces.

Table of Contents

• API Listener
  • API Listener configuration
    • API listeners types
    • Launch events
    • Retrieving and making good use of the listener's result
  • Process Listener Example
    • Step 1 : Create the process that will be triggered as a process listener
    • Step 2 : Create the list of currencies and the web interface

API Listener configuration

API listeners types

In a web interface, you can trigger and launch

• Composite APIs
• Connectors
• Processes

Composite APIs and connectors are executed synchronously whereas processes are executed asynchronously. Composite APIs and connectors should be configured with their Accept-type equals to application/json otherwise triggering them will fail.

Launch events

The following launch process events are available

• Screen initialized : the listener is triggered at the web interface opening.
• Listened variable changed : the listener is triggered when one of the specified variable is changed (separator is coma, e.g: currency,variable1,variable2)
• Application closed : the listener is triggered when the web interface is closed (e.g : submission of a webform that triggers a workflow process, validation of a manual task)
• Manually via JavaScript : the listener is triggered by the execution of the trigger javascript function. In this case you should also configure an identifier which will be used as the WidgetID on which to call the trigger function.

Retrieving and making good use of the listener's result

Configuring an API listener in a web interface implies configuring the behaviour of the interface when the listener succeeds or fails.
To do so, you should fill in respectively the Completed and Failed scripts.

In those scripts, you can use the following variables :

• P_computed : this variable contains the output of the listener (e.g : the computed parameters of a composite API) and is only available if the listener has succeeded.
• P_error : this variable contains the potential error generated during the listener execution and therefore can only be accessed in the Failed script.

The "Manually via JavaScript" trigger excepts as both scripts are replaced by the definition of callback functions.

Process Listener Example

This example will show you how to configure a process listener. We will design a web interface that displays a list of currencies. When selecting a particular currency, the exchange rate of the currency against the € will be retrieved from the European Central Bank and displayed in the web interface.

In the web interface design environment, the Process Listeners tab is now called API call :

Step 1 : Create the process that will be triggered as a process listener

• Import the connector from library : European Central Bank > Daily Euro Rate Exchange

• As output variable of the activity, create fx_rate = ${P_result.rate[currency]} with currency the name of the variable to configure in your webform

• Need a more step by step connector configuration? read this tutorial

Let's test the process by injecting an input parameter :

After the process is completed, you should see fx_rate in the computed parameters :

Step 2 : Create the list of currencies and the web interface

Create the list of currencies by configuring a custom list.

Design the web interface :

• add a spinner, put an identifier (e.g : id_spinner in the rest of the example), then go to Rules tab and untick Visible (4)

• Add the list widget (1), name the value variable currency (2), label variable is optional (3), choose type custom list (4) and select your list (5).

• Add a number input (1), name the variable my_fx_rate (2) and select type "Number" (3)

• Go to Process listeners tab

• Click on "Add process listener" (1), then "Choose a process" and select get fx rate (2), choose "Listened variable changed" for the Launch process event (3) and currency for the listened variable (4).

• Then enter the following scripts (5 - 6 -7 above):

  • Started : tick the box (1), click on Script (2), enter your script (3) and click on Ok (4)

id_spinner.setVisible(true);

This code will get executed when the process is launched and will display the spinner.

• Completed : put the following script

  RMPApplication.setVariable("my_fx_rate",P_computed.fx_rate);  
  id_spinner.setVisible(false);
  

This code will get executed when the process is completed. It will retrieve the computed parameter fx_rate from the completed process and assign the web interface variable my_fx_rate with this retrieved value. It will also hide the spinner.

• Aborted : put the following script

  alert("Error while retrieving fx rate. Contact your administrator");  
  id_spinner.setVisible(false);
  

This code will get executed when the process fails. It will display an error message and hide the spinner.

Save your web interface and preview it :

If you select a currency, the following scenario will get executed :

• The spinner appears which means that the process has been launched.
• The My fx rate input is filled with the retrieved value and the spinner is disappears : the process has completed and the "Completed" associated script has been executed.