Package com.ebasetech.xi.api.connectors

Interface DataConnectors

public interface DataConnectors
The DataConnectors API provides the functionality to create, namespace and configure RESTDataConnectors.

The RESTDataConnector are wrapped inside a JavaScript object that are namespaced into one of two locations:

  1. connectors.verjio.: The namespace location to store Data Connectors that have been downloaded from the Verj.io Materials and downloaded from the Resource Hub
  2. connectors.dataconnectors.: The namespace location to store customized Data Connectors that have been created in the workspace
Namespacing the Data Connector allows the RESTDataConnector to be used in any JavaScript event, for example, a button click.

The DataConnectors API provides a function to retrieve the Data Connector configuration from the Server Administration Application

Further documentation.

Since:
V5.13
See Also:
RESTDataConnector

  • Method Summary

    Modifier and Type Method Description
    RESTDataConnector createRESTDataConnector​(java.lang.String baseUri)
    Creates a RESTful Data Connector constructed with a base URI that provides the following functionality: Direct communication with a REST service without having to call RestServices API helper functions. Customisable headers are sent with all REST calls. Authentication can be sent with all REST calls. Error handling for typical HTTP error codes. Response handling for Data Connector REST calls.
    java.util.Map<java.lang.String,​java.lang.Object> getConfig​(java.lang.String name)
    Returns the Data Connector Configuration configured using the Server Administration Console.
    java.util.Map<java.lang.String,​java.lang.Object> getDataconnectors()
    Namespaced map of REST Data Connectors prefixed with connectors.dataconnectors.
    Errors getErrors()
    The Errors is a server side JavaScript object that contains functions that allows the creation of customizable error handling functionality specifically for the HTTP error response status returned from the server, for example a 404 Not Found error.
    java.util.Map<java.lang.String,​java.lang.Object> getVerjio()
    Namespaced map of REST Data Connectors prefixed with connectors.verjio.

  • Method Details

    • createRESTDataConnector

      RESTDataConnector createRESTDataConnector​(java.lang.String baseUri)
      Creates a RESTful Data Connector constructed with a base URI that provides the following functionality:
      • Direct communication with a REST service without having to call RestServices API helper functions.
      • Customisable headers are sent with all REST calls.
      • Authentication can be sent with all REST calls.
      • Error handling for typical HTTP error codes.
      • Response handling for Data Connector REST calls.

      The RESTDataConnector is constructed with a base URI that is used to construct calls to a specific endpoint when calling the appropriate RESTful web service call.

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

      Further documentation.

      JavaScript example: 

       const restDataConnector = connectors.createRESTDataConnector("https://jukeboxapi.example.com/");
 // Build the URI for the /playlists endpoint
 const uri = restDataConnector.get("playlists");

 // Call the endpoint using the HTTP GET method
 var response = restDataConnector.get(uri);

 // Iterate through the playlists array in the response object
 response.playlists.forEach(function(playlist) {
    tables.playlists.insertRow();
    tables.playlists.name.value = playlist.playlist_name;
 });

      Parameters:
      baseUri - - the URI to call, typically this should be used with RESTDataConnector.createUri(String) to concatenate the base URI with the endpoint
      Returns:
      RESTDataConnector object used for RESTful data connector calls
      Since:
      v5.13.0
      See Also:
      RESTDataConnector

    • getVerjio

      java.util.Map<java.lang.String,​java.lang.Object> getVerjio()
      Namespaced map of REST Data Connectors prefixed with connectors.verjio.

      The namespace location to store Data Connectors that have been downloaded from the Verj.io Materials and downloaded from the Resource Hub

      Further documentation.

      Using the Data Connector example:

      On Click Event: 

       function checkMOTValid() {
    var valid;

    try {
       var resp = connectors.verjio.dvla.getVehicleInfo('HA58 TAG');
       valid = resp.motStatus;
    } catch (e) {
       if (e instanceof HttpNotFoundError) {
          // Registration number was not found
          valid = null;
       }
    }

    return valid;
 }
      Returns:
      Map of data connectors stored within the namespace connectors.verjio
      Since:
      v5.13.0

    • getConfig

      java.util.Map<java.lang.String,​java.lang.Object> getConfig​(java.lang.String name)
      Returns the Data Connector Configuration configured using the Server Administration Console.

      The properties are accessed using the name of the property using standard Java Object notation.

      Further documentation.

      JavaScript example: 

       var config = connectors.getConfig("OpenAI");
 var apiKey = config.apikey;
 var organisationId = config["org"];
      Parameters:
      name - connector configuration name
      Returns:
      data connector configuration map of configuration properties
      Since:
      v5.13.0

    • getDataconnectors

      java.util.Map<java.lang.String,​java.lang.Object> getDataconnectors()
      Namespaced map of REST Data Connectors prefixed with connectors.dataconnectors.

      connectors.dataconnectors.: The namespace location to store customized Data Connectors that are been created in the workspace and have not been downloaded from the Resource Hub

      Further documentation.

      Data Connector example: 

       if (!connectors.dataconnectors.myservice) {   
    connectors.dataconnectors.myservice = new MyService();
 }

 // MyService Data Connector 
 function MyService() {
    const restDataConnector = new RESTDataConnector("https://my.service.example.com/api/2.1/");

    this.authorize = function (params) {
       const uri = restDataConnector.createUri("authorise");
       const body = { "user" : fields.user.value, "password" : fields.password.value };
       const options = { parameters: params };
       return restDataConnector.post(uri, body, options);
    }
 }

      On Click Event: 

       try {
    var response = connectors.dataconnectors.myservice.authorize();
    log(response.authorised);
 }
 catch(e) {
    event.owner.addErrorMessage("Unable to authorize user");
 }
      Returns:
      Map of data connectors stored within the namespace connectors.dataconnectors
      Since:
      v5.13.0

    • getErrors

      Errors getErrors()
      The Errors is a server side JavaScript object that contains functions that allows the creation of customizable error handling functionality specifically for the HTTP error response status returned from the server, for example a 404 Not Found error. The error handlers are created using a description string and an error code. The errors are as follows:
      • HttpRequestError - This is typically used to create HTTP response failure errors, for example the server responds with a 400 Bad Request code
      • HttpAuthorisationError - This should be used when generating Authentication errors, for example the server responds with a 401 Unauthorized code
      • HttpNotFoundError - This should be used when generating not found errors, for example the server responds with a 404 Not Found code
      • HttpServerError - This should be used when generating generic server errors, for example the server responds with a 500 Server Error code
      • HttpUnknownError - This should be used when generating an unknown or unrecognized error, for example the HTTP code is not recognized
      When an error occurs the errorHandler function is called to handle errors. The default error handler throws the errors described above as exceptions that can be caught from the RESTDataConnector RESTFul web service call.

      The error handler can be overidden. The error handler is set by calling the RESTDataConnector.setErrorHandler(Function) function.

      Further documentation.

      JavaScript example: 

       // Define a custom error handler
 function handleError(response) { 
    switch(response.code) {
       case 401:
          // Send an email stating that the service is authorized
          fields.unauthorizedError.value = response.body;
          resources.sysAdmin.sendMail();
          throw connectors.errors.createAuthorisationError("Unauthorized", response.code);
       
       default:
          throw connectors.errors.createRequestError("Request error", response.code);
    }
 };

 try {
    const restDataConnector = connectors.createRESTDataConnector("https://jukeboxapi.example.com/");

    // Override the default error handler
    restDataConnector.setErrorHandler(errors);

    // Call an endpoint
    const uri = restDataConnector.get("playlists");
    var response = restDataConnector.get(uri);

    // ...
 } catch(e) {
    // Show the user the error message
    event.owner.addErrorMessage(e);
 }

      Returns:
      Errors an interface containing functions to create the HttpError errors
      Since:
      v5.13.0