WEGnology API Node

The WEGnology API Node allows a workflow to make requests (allowing both querying and modification) against the WEGnology API easily for any resource under the current application.

Node Properties

There are four configuration sections for the WEGnology API Node: selecting the application, choosing the request to make, configuring the parameters for that request, and determining where to store the result.

Application Scope

By default the actions performed by this node will take place on the current application. Optionally, you may select A different application... to perform cross-application actions. This will require an Application ID and an Application Token. Both fields are templatable.

Resource and Action

Once the application is chosen you must select the request to make-specifically the resource and action. Any resource under the current application or under the scope of your Application Token is available. The dropdown has the list of all resources and their possible actions, as well as short descriptions for each one. In the above case, Device: Get is selected, which means the Get action on the Device resource (i.e. this returns the information about a specific device).

Parameters

Next up is configuring the parameters for the selected resource and action. There are a few requests that have no parameters, and some others that have no required parameters, but most have at least one required parameter. In the above example, the request has one required parameter - the ID of the device that the request should get. There are two types of parameter fields: string templates like the device ID example above, and more complex parameters that are JSON objects. For parameters that are JSON objects, you can either create a JSON template or specify a payload path to pull the desired object off the current payload.

Response

Finally, we can configure a place to put the result of the API request. This is optional, but most of the time you will probably want the result. In the above example, the result will be stored at the payload path data.apiResult. There are two kinds of results that could be returned - a successful response (with a root key of result), or an error response (with a root key of error) if there was something wrong with the request.

After a successful response for the above request, the payload might look like the following:

{
  "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST),
  "data": {
    ...
    "apiResult": {
      "result": {
        "name": "Widget Alpha",
        "description": "Device For Bob",
        "tags": [ ],
        "attributes": [
          { "name": "button", "dataType": "boolean" },
          { "name": "tempF", "dataType": "number" },
        ],
        "deviceClass": "standalone",
        "applicationId": "569ff47597b69c01001e230f",
        "creationDate": "2016-03-09T17:04:02.451Z",
        "lastUpdated": "2016-03-10T21:51:06.223Z",
        "_etag": "\"271-VfsBPHq+u0aBucK+bRNgw\"",
        "deviceId": "56e05782b3867f0100814dad",
        "connectionInfo": {
          "connected": 0,
          "time": "2016-08-26T17:41:06.686Z"
        },
        "id": "56e05782b3867f0100814dad",
        "_type": "device"
      }
    }
  },
  ...
}

Node Errors

After an error response for the above request, the payload might look like this instead:

{
  "time": Fri Feb 19 2016 17:26:00 GMT-0500 (EST),
  "data": {
    ...
    "apiResult": {
      "error": {
        "type": "NotFound",
        "statusCode": 404,
        "message": "Device not found"
      }
    }
  },
  ...
}

Edge Workflow Usage

The WEGnology API Node is available in Gateway Edge Agent v1.23.0 or higher. The API endpoints available on the edge are a much smaller set compared to the API Node in application or experience workflows; the API node in edge workflows is restricted to only API endpoints a device is allowed to access. For example, an application workflow is allowed to call the Application: Get endpoint, but an edge workflow would not be able to.

Behind the scenes, the API node for the edge authenticates as the edge device itself against the WEGnology API, and so can only perform actions that are allowed for that device. For a general overview of how device API authentication works, you can read more here.