RESTDataConnector

RESTDataConnector provides integration with a non-UI, external data service, for example a REST Service.

A Data Connector is a Server Side JavaScript entity that provides the following functionality:

• A pure JavaScript API to communicate to a specific REST service such as a third-party API.
• Direct communication with a REST service without having to call com.ebasetech.xi.services.RestServices API helper methods.
• Methods and definitions for interacting with the REST service.

A new Data Connector is automatically added to the one of following namespaces:

• connectors.verjio.<connectorname> - When the Data Connector is downloaded from the Verj.io Resource Hub.
• connectors.dataconnectors.<connectorname> - When a new Data Connector is created in your workspace.

The HTTP header Content-Type: application/json is set as default. This can be overridden by calling the com.ebasetech.xi.api.connectors.RESTDataConnector#setDefaultHeader(String, Object) function.

A Data Connector contains custom JavaScript functions used to call the remote service directly. These functions should be appropriately named to reflect the intention of the call, for example:

JavaScript example: Data Connector functions

  function ExampleWeatherStation(stationId) {
     const restDataConnector = connectors.createRESTDataConnector("https://weather.example.com/api/");

     // Set the station identifier as a header for all requests
     restDataConnector.setDefaultHeader('station', stationId);
   
     // Submit a weather station temperature reading
     // Defaults to centigrade ("c") for the units
     this.submitTemperatureReading = function (temperature, unit) {
        const uri = restDataConnector.createUri("submit/temperature");
        const body = {
             temp: temperature,
             unit: unit || 'c',
        };
        return restDataConnector.post(uri, body);
     }
  }
  
  

The DataConnectors properties should be configured using the Verj.io Server Administration Console, for example an API key or application identifier. JavaScript example: Creating a new data connector.

  // Get the "ExampleWeatherStation" Data Connector configuration from the server
  
  function ExampleWeatherStation(stationId) {
     const restDataConnector = connectors.createRESTDataConnector("https://weather.example.com/api/");

     // Get the configuration
     const config = connectors.getConfig("ExampleWeatherStation");

     // Use the stationId parameter or fall back to the value configured on the server
     // The double underscore prefix indicates that the variable is internal to the Data Connector
     const __stationId = stationId || config.stationId; 

     // Set the station identifier as a header for all requests
     restDataConnector.setDefaultHeader('station', __stationId);
  }

  

The DataConnectors is added to the Form and it can be accessed via a server side JavaScript event, for example a Button Control onClick event.

JavaScript example: button click event

  // The ExampleWeatherStation Data Connector is available in the connectors.dataconnectors namespace
  try {
     connectors.dataconnectors.ExampleWeatherStation.submitTemperatureReading(22);
  } catch (e) {
     log(`Error submitting temperature reading: ${e}`);
     event.owner.addErrorMessage('Unable to submit temperature reading.');
  }

  event.owner.addInfoMessage('Temperature reading submitted successfully!');
  

Further documentation