DrvREST

DrvREST is a driver for connecting and retrieving data from the REST API to Web Port. Currently only GET is supported, but this will be expanded in the future.

To use DrvREST, an IO device is created which is then used to communicate with REST APIs.

Installation

The installation of DrvREST is done by selecting DrvREST during the installation of Web Port.

See "Installation" for more information on the installation process.

IO-device

To use DrvREST, first create an IO device as described in chapter "IO-devices" of the manual. In addition to general settings (see "general settings" in IO-devices), the following settings are available for an IO device of type DrvREST:

Setting:	Description:
Base URL	Specifies URL for REST API
Authentication	Type of authentication to be used (None, URL, BASIC, OATH2) Used in combination with credentials.
Authentication details	Specified depending on the choice made for authentication. None: The field is left blank URL: The value is added to the url call. For example (token=xxxx) BASIC: Enter user and password on the form user:password OATH2: Enter oath2 access token.
Buffer time [s]	Specifies the time the response is buffered in Web Port to reduce the number of queries to the API.

Tags

For more information on how to create tag lists and tags, see chapter "Tags" of the manual.

Tag addresses:

Tag addresses can be specified in two formats:

• API call|JSON filter

That is, the API call part is added to the base URL set on the IO device, resulting in the full call. The response coming from the REST API is then filtered with a JSON filter to retrieve a single value. The two parts are separated by a "pipe" character (|). To make boolean comparisons, these are written after the address within{}(example:{0}).

• PARAMETER{rwscript#SCRIPT(param1=url, param2=data2)}

Where PARAMETER is any parameter that can be used in a read-write script (rwscript), which is a called script with the function to both read and write against web requests. This also gives the option to send optional parameters with optional names, here calledparam1andparam2. RWScript is used if you want to be able to both write and read, or only read with a function other than GET.

The RW script itself is a called script with four functions:

preprocessread(), postprocessread(), preprocesswrite() and postprocesswrite()

These are used to prepare requests for reading and writing, as well as manage the responses.

Function:	Description:
Preprocessread	Should return a JSON string with the following parameters. url, httpMethod, headers (optional), queryString
Postprocessread	Returns the value (as string) stored on the tag. The answer to the request is found in the string data
Preprocesswrite	The same input and output from preprocesswrite, but in addition the optional body parameter. !Note, need to check body here!
Postprocesswrite	Returns a bool, with true or false depending on whether the write was successful. The answer to the request is found in the string data

Example for API call|JSON filter:

The JSON filter now uses JavaScript's built-in JSON parsing and filtering functions, instead of Newtonsoft JSON'sSelectTokenfunction.

Examples of how it can be used:

JSON response

{
  "timeSeries": [{
    "validTime": "2015-10-12T04:00:00Z",
    "parameters": [{
      "name": "msl",
      "levelType": "hmsl",
      "level": 0,
      "values": [
        1031
      ]
    }]
  }]
}

How to use the JSON filter:

• To selectvalidTime:

  var obj = JSON.parse(response);
  var validTime = obj.timeSeries[0].validTime;
  

• To select the value (1031) in the parameter namedmsl:

  var obj = JSON.parse(response);
  var parameters = obj.timeSeries[0].parameters;
  var mslParam = parameters.find(function(p) { return p.name === "msl"; });
  var value = mslParam.values[0];

• Use JSON.parse() to convert the response string to a JavaScript object.
• Use standard JavaScript array functions such as .find() to filter arrays.
• All variable declarations must use var.

More information can be found on the newtonsoft website: 
https://www.newtonsoft.com/json/help/html/SelectToken.htm

Example for RW-Script:

The example below does the following:

function preprocessread() {
    debug(tag);
    // Get specific address from tag
    var address = Moldeo.WebPortCommon.TagManager.Manager.Tags[tag].Address;
    // Gets base-url from IO-device
    var urlAddress = baseurl;
    // Sets the httpMethod to use. Eg. get, put, post…
    var httpMethod = "get";
    // Adds some parameters to the address
    // In this example credentials are parameters that are added to url
    var queryString = getCredentials() + "&FN=read&ID=" + address;

    // Build request as a plain JS object
    var request = {
        url: urlAddress,
        httpMethod: httpMethod,
        queryString: queryString
        // headers and body can be added if needed
    };

    debug(JSON.stringify(request));
    return JSON.stringify(request);
}

function postprocessread() {
    var value = "";
    // Result from read-request is stored in data (as a JSON string)
    var result = JSON.parse(data);

    // This example reads out the result (tempValue) from the JSON response
    // If the response is an array, take the first element
    var res = Array.isArray(result) ? result[0] : result;
    if (res && res.tempValue !== undefined) {
        value = res.tempValue.toString();
    }
    return value;
}

// Build an object with everything that is required for the processing put/post webrequest
function preprocesswrite() {
    var urlAddress = baseurl + '/' + id + '/web/JSON.HTML';
    var httpMethod = "get";
    var address = Moldeo.WebPortCommon.TagManager.Manager.Tags[tag].Address;
    var queryString = 'FN=write&ID=' + address + ';' + value + '&' + getCredentials();

    var request = {
        url: urlAddress,
        httpMethod: httpMethod,
        queryString: queryString
        // headers and body can be added if needed
    };

    debug(JSON.stringify(request));
    return JSON.stringify(request);
}

// Check if the write status is indicating that it is ok
function postprocesswrite() {
    var result = JSON.parse(data);
    var response = true;

    // If result is an array, iterate over it
    var arr = Array.isArray(result) ? result : [result];
    for (var i = 0; i < arr.length; i++) {
        var res = arr[i];
        var state = res.state;
        if (state !== undefined && state !== null) {
            debug(state.toString());
            switch (state.toString()) {
                case "0":
                    break;
                case "1":
                default:
                    response = false;
                    break;
            }
        }
    }
    return response;
}

// Non-mandatory function that gets credentials from IO-device
function getCredentials() {
    if (Moldeo.WebPortCommon.TagManager.Manager.Tags.hasOwnProperty(tag)) {
        var devguid = Moldeo.WebPortCommon.TagManager.Manager.Tags[tag].Deviceguid;
        return Moldeo.WebPortCommon.SettingsManager.Manager[devguid + "|credentials"];
    }
    return "";
}