NAV
cURL JavaScript

Authentication

Once you have retrieved your keys, you can verify whether your keys and the REST server work E2E by issuing the following command:

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/ping"

Before you can start using the REST API, you must visit your profile page in the waylay application and fetch your API keys:

enter image description here

Task related calls

In waylay terminology, tasks are instantiated rules. There are two ways tasks can be instantiated:

Create a task

There are mainly 2 ways to create a task, either by specifying the rule in the request, or by specifying the template with which the task needs to be instantiated.

Create a task with rule defined in the request

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
  "sensors": [
    {
      "label": "currentWeather_1",
      "name": "currentWeather",
      "version": "1.0.3",
      "sequence": 1,
      "properties": {
        "city": "Gent, Belgium"
      },
      "position": [173, 158]
    },
    {
      "label": "isWeekend_1",
      "name": "isWeekend",
      "version": "1.0.3",
      "sequence": 1,
      "position": [179, 369]
    }
  ],
  "actuators": [
    {
      "label": "TwitterDM_1",
      "name": "sendTwitterDM",
      "version": "1.0.1",
      "properties": {
        "screenName": "pizuricv",
        "message": "Great weekend!"
      },
      "position": [600, 199]
    }
  ],
  "relations": [
    {
      "label": "ANDGate_1",
      "type": "AND",
      "position": [353, 264],
      "parentLabels": ["currentWeather_1", "isWeekend_1"],
      "combinations": [["Clear", "TRUE"]]
    }
  ],
  "triggers": [
    {
      "destinationLabel": "TwitterDM_1",
      "sourceLabel": "ANDGate_1",
      "statesTrigger": ["TRUE"],
      "invocationPolicy": 1
    }
  ],
  "task": {
    "type": "periodic",
    "start": true,
    "name": "Rule created on 12/8/2015, 1:38:56 PM by veselin@waylay.io",
    "pollingInterval": 900,
    "tags" : {
      "myRef" : "d8933cd4-7c70-11e9-8f9e-2a86e4085a59"
    }
  }
}' "https://sandbox.waylay.io/api/tasks"

You can create a task without a need to create a template first. In order to create a task you will need to specify the following in the request:

Sensor settings are:

Actuator settings are:

Trigger settings are:

If neither statesTrigger nor stateChangeTrigger is specified when the destination is a sensor, this means that the destination sensor will be triggered after successful execution of the source sensor.

Relations express logical gates that can be defined between sensors. There are 3 types of relations: AND, OR and GENERAL.

Relations settings are:

Task settings are:

Create a task from a template

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
  "name": "test1",
  "template": "internet.json",
  "start": false,
  "type": "scheduled",
  "cron": "0/30 * * * * ?",
  "tags" : {
     "myRef" : "d8933cd4-7c70-11e9-8f9e-2a86e4085a59"
  },
  "variables" : {
    "a" : "resourceA",
    "b" : "resourceB"
  }
}' "https://sandbox.waylay.io/api/tasks"

In order to start a task from the template, you need to provide the following inputs:

Cron task

Cron specific input settings:

Periodic task

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
  "name": "test2",
  "template": "internet.json",
  "resource": "hello",
  "start": false,
  "type": "periodic",
  "frequency": 1000
}' "https://sandbox.waylay.io/api/tasks"

Periodic specific input settings:

Onetime task

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
  "name": "test3",
  "template": "internet.json",
  "resource": "hello",
  "type": "onetime"
}' "https://sandbox.waylay.io/api/tasks"

Onetime specific input settings:

Task tags

When creating a task, it is possible to specify tags for the task by which you can, later on, find the task back. You can specify this data in the tags object of the task settings. Any valid json is accepted. However, you can only search for task based on the toplevel tag keys with string, number or boolean values.

Create a task with sensor properties in the request

In this example, we change addresses of the Ping sensors and the resource of node Ping_2:

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
"name": "test4",
"template": "internet.json",
"resource": "hello",
"start": false,
"type": "scheduled",
"cron": "0/30 * * * * ?",
"nodes": [{
  "name": "Ping_1",
  "properties": {
    "sensor": {
      "name": "Ping",
      "version": "1.0.1",
      "label": "Ping_1",
      "requiredProperties": [
        {"address": "www.waylay.io"}
      ]
    }
  }
}, {
  "name": "Ping_2",
  "properties": {
    "resource": "newresource"
    "sensor": {
      "name": "Ping",
      "version": "1.0.1",
      "label": "Ping_2",
      "requiredProperties": [
        {"address": "sandbox.waylay.io"}
      ]
    }
  }
}]}' "https://sandbox.waylay.io/api/tasks"

You can also override node/sensor/actuator settings of the template before starting the task. These are the fields you can override:

Update a task

This allows you update the task configuration. See also the documentation on getting a task’s configuration.

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X PUT -d '{
  "name": "test1",
  "template": "internet.json",
  "resource": "hello",
  "start": false,
  "type": "scheduled",
  "cron": "0/30 * * * * ?"
}' "https://sandbox.waylay.io/api/tasks/1"

Delete a task

Delete a task

curl --user apiKey:apiSecret -X DELETE "https://sandbox.waylay.io/api/tasks/1"

Start a task

curl --user apiKey:apiSecret -X POST "https://sandbox.waylay.io/api/tasks/1/command/start"

Stop a task

curl --user apiKey:apiSecret -X POST "https://sandbox.waylay.io/api/tasks/1/command/stop"

Getting a single task by id

Get information about a single task. Response will include template definition and task’s type and settings.

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/tasks/{taskID}"

Getting the configuration of an existing task

Using this resource you can get the original task configuration that was posted to /api/tasks. Useful if you want to:

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/tasks/{taskID}/conf"

Query multiple tasks

This call gives first 10 tasks (default behaviour), and if you need to filter your tasks, you can use a query language.

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/tasks"

Query task by name. For instance in this call you can retrieve all tasks that start with taskName.

curl --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/tasks?name=taskName*"

Query to match tasks for resources with exactly the name

curl --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/tasks?resource=resource1"

Query tasks which have tag myRef equal to d8933cd4-7c70-11e9-8f9e-2a86e4085a59

curl --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/tasks?tags.myRef=d8933cd4-7c70-11e9-8f9e-2a86e4085a59"

Query tasks which have tag myRef equal to ‘building1’ or ‘building2`

curl --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/tasks?tags.myRef=building1&tags.myRef=building2"

Query tasks which have tag myRef

curl --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/tasks?tags.myRef"

You can also query for tasks.

Task querying filtering

Query parameters are:

Query parameters are combined with logical AND operator. That means that if you combine more than one parameter together you will only receive tasks that match all conditions.

You query task by a name using * characters to get a list of tasks that matches the input string.

If you query task by resource, input must match the resource name exactly. You can still receive more tasks in case they all have the same resource name.

If you specify a tags key multiple times, logical OR is applied for that key. If you don’t specify a value for a tags.<x> query parameter, all tasks which have a value for x in their tags are returned.

Quering tasks and paging

curl --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/tasks?startIndex=1"

Default number of returned results is 10, and you can change this using hits parameter. For instance, this call will retrieve maximum 50 tasks, starting search from the task index 50. (second page of 50-per-page results)

curl --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/tasks?startIndex=50&hits=50"

Paged result

If you want to retrieve the list as a paged list, add Accept header with value application/vnd.waylay.paged+json. The response will contain a JSON object with values, skip, limit and total fields.

To retrieve the next page, use skip+limit as startIndex and limit as hits

Get the total count of tasks

In order to retrieve the total task count, check the X-Count header of the response.

If you use the Accept: application/vnd.waylay.paged+json header, you will get the total count in the total field

In order to retrieve the total task count, check the header of the response (X-Count). In this example, we receive back 27 tasks:

curl --user apiKey:apiSecret -I "https://sandbox.waylay.io/api/tasks"

HTTP/1.1 200 OK
Server: nginx/1.6.2
Date: Wed, 07 Jan 2015 10:50:32 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
X-Count: 27
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, PUT
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Expose-Headers: X-Count
Strict-Transport-Security: max-age=31536000; includeSubdomains

Example: get the total count of running tasks

curl --user apiKey:apiSecret -I \
  "https://sandbox.waylay.io/api/tasks?status=running"

HTTP/1.1 200 OK
Server: nginx/1.6.2
Date: Wed, 07 Jan 2015 10:50:32 GMT
Content-Type: application/json
Content-Length: 0
Connection: keep-alive
X-Count: 5
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, PUT
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Expose-Headers: X-Count
Strict-Transport-Security: max-age=31536000; includeSubdomains

Note on tasks and resources

Tasks and task nodes can be linked to a resource. There are some special node-related values you should know about:

As an example if you have 3 nodes with resource $ and the task has resource foo, all three node-sensors will be triggered when data is injected for resource foo.

Batch tasks operations

There are 2 ways to perform batch operations on tasks.

Batch operation queue

List the queue

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/batch"

[
  {
    "id":"f7fa8b2a-f7be-403c-9af7-e95c654b399f",
    "time":"2017-10-05T13:21:10.389Z",
    "operation":"Modify tasks by query: REMOVE"
  },
  {
    "id":"310282dd-377a-4a32-b1ed-599d0a1e9011",
    "time":"2017-10-05T13:21:10.388Z",
    "operation":"Modify tasks by query: REMOVE",
    "result":{"successful":[1,2],"failed":[]}
  }
]

List the queue

You get back an array with all queued and a history of max 20 batch operations ordered descending by time submitted.

Post a batch operation

POST a remove operation

curl --user apiKey:apiSecret -X POST "https://sandbox.waylay.io/api/batch?resource=testResource"
-H "Content-Type:application/json" -d '{ "operation": "command", "command": "remove" }'

{
  "id":"f7fa8b2a-f7be-403c-9af7-e95c654b399f",
  "time":"2017-10-05T13:21:10.389Z",
  "operation":"Modify tasks by query: REMOVE"
}

This api is the same as the direct batch operations api but:

Direct operations (deprecated)

All the batch operations work with the same filters as querying for tasks, except the filter parameter which is not allowed because it’s not exact.

Delete multiple tasks

curl --user apiKey:apiSecret
-X PATCH "https://sandbox.waylay.io/api/tasks?ids=1,3,9"
-H "Content-Type:application/json"
-d '{ "operation": "command", "command": "remove" }'

or

curl --user apiKey:apiSecret
-X DELETE "https://sandbox.waylay.io/api/tasks?ids=1,3,9"

Modify existing tasks

curl --user apiKey:apiSecret -X PATCH "https://sandbox.waylay.io/api/tasks?ids=1,3,9"
-H "Content-Type:application/json" -d '{"operation": "xxx", ...}'

These calls will modify existing tasks in-place. Below an example of what such a request looks like:

Commands

This allows to start or stop a bunch of tasks. Valid commands are [start, stop, remove, reload]

The body should look like this

{
  "operation": "command",
  "command": "stop"
}

Reload tasks

This is mainly for applying template updates to existing tasks

{
  "operation": "command",
  "command": "reload"
}

Plugin updates

This will apply plugin version updates and re-instantiate the tasks.

The body should look like this (fromVersion can be an exact version or any)

{
  "operation": "updatePlugins",
  "updates": [
    {
      "name": "myActuator",
      "fromVersion": "1.0.1",
      "toVersion": "1.0.3"
    },
    {
      "name": "mySensor",
      "fromVersion": "1.1.0",
      "toVersion": "1.3.2"
    },
    {
      "name": "mySensor",
      "fromVersion": "any",
      "toVersion": "2.0.0"
    }
  ]
}

Modify task properties

This allows you to modify sensor / actuator properties while keeping the task Id.

The format used to modify properties is the same as when you create a task from a template. Updates will be merged with any previously provided properties.

{
  "operation" : "updateProperties",
  "nodes" : [ {
    "name" : "node1",
    "properties" : {
      "sensor" : {
        "requiredProperties" : [ {
          "prop1" : "updatedValue"
        }, {
          "prop1" : "updatedValue"
        } ]
      }
    }
  }, {
    "name" : "node2",
    "properties" : {
      "actions" : [ {
        "label" : "actuator1",
        "requiredProperties" : [ {
          "prop1" : "updatedValue"
        } ]
      } ]
    }
  } ]
}

Templates

Templates are generic rules that have not yet been associated to a particular device/devices or instance. The same template can be instantiated many times as tasks, by associating device specific parameters to a specific template. This mechanism is operationally very efficient in the sense that templates only need to be developed once, but can then be instantiated many times. As an example, assume you generate a template for an appliance and in the field, you have 100k appliances deployed: then you would have one template and 100k tasks running on the waylay platform.

Create a new template

You can create a template using “simplified” logic representation (without Bayesian Network):

Template with sensors, actuators and relations

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
  "name" : "testSimpleJSON",
  "sensors": [
    {
      "label": "currentWeather_1",
      "name": "currentWeather",
      "version": "1.0.3",
      "sequence": 1,
      "properties": {
        "city": "Gent, Belgium"
      },
      "position": [173, 158]
    },
    {
      "label": "isWeekend_1",
      "name": "isWeekend",
      "version": "1.0.3",
      "sequence": 1,
      "position": [179, 369]
    }
  ],
  "actuators": [
    {
      "label": "TwitterDM_1",
      "name": "sendTwitterDM",
      "version": "1.0.1",
      "properties": {
        "screenName": "pizuricv",
        "message": "Great weekend!"
      },
      "position": [600, 199]
    }
  ],
  "relations": [
    {
      "label": "ANDGate_1",
      "type": "AND",
      "position": [353, 264],
      "parentLabels": ["currentWeather_1", "isWeekend_1"],
      "combinations": [["Clear", "TRUE"]]
    }
  ],
  "triggers": [
    {
      "destinationLabel": "TwitterDM_1",
      "sourceLabel": "ANDGate_1",
      "statesTrigger": ["TRUE"],
      "stateChangeTrigger": {
        "stateFrom": "*",
        "stateTo": "FALSE"
      },
      "invocationPolicy": 1
    }
  ]
}' "https://sandbox.waylay.io/api/templates"

Sensor settings are:

Actuator settings are:

Trigger settings are:

If neither statesTrigger nor stateChangeTrigger is specified when the destination is a sensor, this means that the destination sensor will be triggered after successful execution of the source sensor.

Relations express logical gates that can be defined between sensors. There are 3 types of relations: AND, OR and GENERAL.

Relations settings are:

Create a new template using BN

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST
-d '{
    posterior: [ {
                    nodes: [ "CONNECTION", "Ping_1", "Ping_2", "Ping_3" ],
                    function: [ 0, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0 ]
                  } ],
    nodes: [ {
                states: [ "OK", "NOK" ],
                name: "CONNECTION",
                properties: {
                    position: [ 497, 235 ],
                    comment: "created by waylay",
                    cost: 1
                },
                type: "discrete",
                mode: "nature"
              },
              {
                states: [ "Not Alive", "Alive" ],
                name: "Ping_1",
                properties: {
                  position: [ 214, 317 ],
                  comment: "created by waylay",
                  cost: 1,
                  sensor: {
                    name: "Ping",
                    version: "1.0.1",
                    label: "Ping_1",
                    requiredProperties: [ { address: "www.google.com" } ] }
                },
                type: "discrete",
                mode: "nature",
                priors: [ 0.5, 0.5 ]
              },
              {
                states: [ "Not Alive", "Alive" ],
                name: "Ping_2",
                properties: {
                  position: [ 144, 163 ],
                  comment: "created by waylay",
                  cost: 1,
                  sensor: {
                    name: "Ping",
                    version: "1.0.1",
                    label: "Ping_2",
                    requiredProperties: [ { address: "www.waylay.io" } ] }
                },
                type: "discrete",
                mode: "nature",
                priors: [ 0.5, 0.5 ]
              },
              {
                states: [ "Not Alive", "Alive" ],
                name: "Ping_3",
                properties: {
                  position: [ 359, 62 ],
                  comment: "created by waylay",
                  cost: 1,
                  sensor: {
                    name: "Ping",
                    version: "1.0.1",
                    label: "Ping_3",
                    requiredProperties: [ { address: "www.yahoo.com" } ] }
                  },
                type: "discrete",
                mode: "nature",
                priors: [ 0.5, 0.5 ]
              } ],
            name: "internet2.json"
          }' "https://sandbox.waylay.io/api/templates"

You can also create a new template that is defined as a Bayesian Network. Compared to previous call, this call allows you to define gates as a Conditional Probability Table (CPT) and also allows you to attach actuators to the likehood of a node being in a given state:

List all templates

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/templates"

Template listing filtering

Query parameters are:

All query parameters are combined with logical AND operator. That means that if you combine more than one parameter together you will only receive tasks that match all conditions.

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/templates?plugin=mySensor"

Get a template

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/templates/internet.json"

Will return the template properties, including the name, user and the Bayesian Network (nodes and posterior). If the template was created using simplified format, the simplified graph will be return in the simplifiedGraph property.

If the template uses multiple templated resources (using the $<variablename> format), the variablenames are returned in the variables property.

Update a template

Templates can be updated using the http PUT method. This however will not update any tasks using the template. You will need to do a batch reload operation on the tasks to accomplish that.

curl --user apiKey:apiSecret -X PUT "https://sandbox.waylay.io/api/templates/mytemplate"
-H "Content-Type:application/json" -d '{"name": "mytemplate", ...}'

Delete template

curl --user apiKey:apiSecret -X DELETE "https://sandbox.waylay.io/api/templates/internet.json"

Modifying existing templates (batch)

curl --user apiKey:apiSecret -X PATCH "https://sandbox.waylay.io/api/templates?plugin=myActuator"
-H "Content-Type:application/json" -d '{"operation": "xxx", ...}'

All the batch operations work with the same filters as querying for templates, except the filter parameter which is not allowed because it’s not exact. Some examples:

Plugin updates

This will apply plugin version updates to the templates. Optionally you combine this with a reload of all tasks instantiated from the updated templates. (reloadTasks optional boolean property that defaults to false)

The body should look like this (fromVersion can be an exact version or any)

{
  "operation": "updatePlugins",
  "updates": [
    {
      "name": "myActuator",
      "fromVersion": "1.0.1",
      "toVersion": "1.0.3"
    },
    {
      "name": "mySensor",
      "fromVersion": "1.1.0",
      "toVersion": "1.3.2"
    },
    {
      "name": "mySensor",
      "fromVersion": "any",
      "toVersion": "2.0.0"
    }
  ],
  "reloadTasks": true
}

Running a template over a batch dataset

curl --user apiKey:apiSecret -X POST "https://sandbox.waylay.io/api/templates/mytemplate/run" \
 -H "Content-Type:application/json" \
 -d '{
      "data": [
        [{
           "resource": "resource1",
           "temperature": 20
         },
         {
           "resource": "resource2",
           "co2": 100,
           "humidity": 0.4
         }],
        [{
           "resource": "resource1",
           "temperature": 21
         }
        ]
      ],
      "conf": {
        "resetObservations": false,
        "executeActuators": false,
        "resource": "resource1",
        "nodes":[
          {
            "name": "temp",
            "properties": {
              "resource":  "resource1"
            }
          }
        ]
      }
    }'

You can run a template without creating a task by providing it with groups of resource-based data to inject. This allows running a template on a backlog of data while getting the results back as a stream while they are being produced.

These are the options you can set:

The request contains 2 parts, the data which is an array of arrays and conf for providing the template overrides like you do when instantiating a task from a template. Data is provided as an array of arrays where the outer array will control the number of invocations performed on the task. The resulting stream will have as many items as this array. The inner array constitutes of all messages that should arrive at the task during that invovation. They will be mapped to nodes using the resource property.

The results are returned as a application/x-ndjson stream. Whenever an invocation ends you will receive a new json concatenated with a newline. The request will end once all data has been worked through. In case of a single invocation this response can also be parsed as application/json

{
  "nodes": {
    "alarm": {
      "state": "OK",
      "probability": 1
    },
    ...
  },
  "sensors":{
    "alarm": {
      "executed": true,
      "result": true,
      "state": "OK",
      "rawData": {},
      "log": []
    },
    ...
  },
  "actuators": {
    "alarm": {
      "sms_send": {
          "executed": true,
          "result": true,
          "message": "SMS sent",
          "log": []
        }
      },
      ...
    },
    ...
  }
}
\n
{
... second result here ...
}
\n

Running a batch dataset through a graph/BN

curl --user apiKey:apiSecret -X POST \
  https://sandbox.waylay.io/api/templates/run \
  -H 'Content-Type: application/json' \
  -d '{
    "graph": {
       "sensors": [
          {
             "label": "streamingDataSensor_1",
             "name": "streamingDataSensor",
             "version": "1.1.3",
             "dataTrigger": true,
             "resource": "$",
             "properties": {
                "parameter": "temperature",
                "threshold": "22"
             }
          }
       ],
       "actuators": [
          {
             "label": "debugDialog_1",
             "name": "debugDialog",
             "version": "1.0.5",
             "properties": {
                "message": "Temperature above threshold {{streamingDataSensor_1.threshold}} : {{streamingDataSensor_1.data.temperature}}"
             }
          }
       ],
       "triggers": [
          {
             "destinationLabel": "debugDialog_1",
             "sourceLabel": "streamingDataSensor_1",
             "invocationPolicy": 0,
             "statesTrigger": [
                "Above"
             ]
          }
       ]
    },
    "data": [
        [
            {
                "resource": "inside",
                "temperature": 20
            }
        ],
        [
            {
                "resource": "inside",
                "temperature": 30
            }
        ]
    ],
    "conf": {
        "resetObservations": false,
        "executeActuators": false,
        "resource": "inside"
    }
}'

Similarly to running a template over a batch dataset, you can also run a batch dataset through a graph or baysian network by POSTing a similar datastructure to /templates/run. Next to the data element and the optional conf element, the body should also contain a graph element which either contains a Simplified graph or a Bayesian network

The results are returned also as application/x-ndjson stream.

Discovery template

One (and only one) template can be marked as discovery template. This template will be run using the running a template over a batch dataset on any new discovered resource, i.e. the first time data is injected in the engine for this resource. This can be used to associate metadata (e.g. a resource type) to the newly discovered resource. Any actuators that are triggered in the template will be executed. A discovery template cannot have multiple templated resources.

Get the discovery template

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/discoveryTemplate"

This will return with status code 200 (OK) with the template in the body if there is a discovery template and with status code 204 (NoContent) if there is no discovery template

Set the discovery template

curl --user apiKey:apiSecret -X PUT \
   "https://sandbox.waylay.io/api/discoveryTemplate?name=<templateName>"

To mark a template as the discovery template, execute this PUT call with the template name as the name query parameter. If the call was successfull, the template templateName will be returned in the body of the response.

To unmark the discovery template (set no discovery template), execute this PUT call without specifying the name query parameter.

Plugs (Sensors, Actuators and Transformers)

Note: More about how to write plugs can be found here

Plug types

Sensors

Sensors can be considered a generalized form of input connector for the waylay platform. You can create sensors to acquire data from physical devices, databases, applications or online services. You do this by means of writing Javascript and defining metadata. Waylay provides many examples which you can use as a baseline to create your own sensors, specific to your application. On a technical level, a sensor can be considered as a function that, when called, returns the state it is in.

Actuators

Based on the outcome of the logic, you may want to take action, such as sending an alert, writing something in a database or acting on a physical system. You can take action based on any node being in a particular state, by attaching actuators to the particular node. As for the sensors, the waylay framework allows you to add your own definitions of actuators.

Transformers

Transformers can be used to transforming incoming messages, like decoding, transforming or validation.

Get list of all sensors

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/sensors"

Execute sensor

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
    "properties": {
      "city": "Gent"
    }
  }' \
  "https://sandbox.waylay.io/api/sensors/weatherSensor/versions/1.0.1"

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
    "properties": {
      "city": "Gent"
    }
  }' \
  "https://sandbox.waylay.io/api/sensors/weatherSensor"

You can sensor specific parameters in the call, like in this example where we provide city name to the weather sensor. If the version is omitted, the latest version of the sensor will be called.

Get list of all actuators

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/actions"

Execute actuator

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
    "properties": {
      "address": "veselin@waylay.io",
      "subject": "test",
      "message": "hello world"
    }
  }' \
  "https://sandbox.waylay.io/api/actions/Mail/versions/1.0.1"

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
    "properties": {
      "address": "veselin@waylay.io",
      "subject": "test",
      "message": "hello world"
    }
  }' \
  "https://sandbox.waylay.io/api/actions/Mail"

You can provide actuator specific parameters in the call, like in this example where we provide e-mail address and message to mail actuator. If the version is omitted, the latest version of the actuator will be called.

Get list of all transformers

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/transformers"

Execute a specific transformer version

The payload to transform should be provided as string in properties.data

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
    "properties": {
      "data": "{\"temperature\": 123.4}",
      "resource": "resource1"
    }
  }' \
  "https://sandbox.waylay.io/api/transformers/transformTemperatureFloat/versions/1.2.1"

Execute the latest transformer version

The payload to transform should be provided as string in properties.data

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
    "properties": {
      "data": "{\"temperature\": 123.4}",
      "resource": "resource1"
    }
  }' \
  "https://sandbox.waylay.io/api/transformers/transformTemperatureFloat"

Node related calls

In waylay terminology, sensor is it attached to the node. During the runtime of the tasks, you can either inspect the node, or set the state, or execute attached sensors.

Get current states

Get current states(posteriors) and raw data for the node

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/tasks/759/nodes/Ping_1"

Get supported states

curl --user apiKey:apiSecret "https://sandbox.waylay.io/api/tasks/759/nodes/Ping_1/states"

Set the state

curl --user apiKey:apiSecret -X POST  -d 'state=Alive' "https://sandbox.waylay.io/api/tasks/759/nodes/Ping_1"

Execute attached sensor

In this call below, we will execute Ping sensor on the task 759:

curl --user apiKey:apiSecret -X POST  -d 'operation=start' "https://sandbox.waylay.io/api/tasks/759/nodes/Ping_1"

At any time you can execute a sensor attached to the node. Please be aware that the state change will be inferred in that task right after the sensor execution.

Provisioning API

Resource type provides link to set of tasks that can run on the group of resources. It can also be used to define metrics interface (which is linked to the sensory information) and command interface which allows you to abstract actual actuators implementation (see later). With most of the IoT platforms, you would find a ResourceType called a “template”, since they refer to this sort of modeling as a way to model different device categories using the same JSON template. In our case, we use a template in the rules context. More importantly, our abstraction allows to model both “object templating” together with rules associations, as described further.

Provisioning API allows you to associate metadata with resource. Resources are either discovered by Waylay (as soon as data is pushed towards Waylay Broker) or you can as well create them using REST call.

Next to the resource CRUD related calls, Waylay allows you to create ResourceType entities, and let you link resource to a type using metadata (please see example below). As soon as a resource is linked to the resource type, all metadata values of that type are inherited for that resource. Resource can still overwrite any specific attribute in its metadata model.

Waylay also allows you to associate a resource to a parent resource (by setting the parentId). Using this feature, you can organise your resources in a hiërarchical structure. Currently waylay does NOT check for cyclic references. Also parentId can NOT be inherited from the linked resource type.

Let’s see how api works in practice:

Create resource

In this example, we create a resource mydevice_id and add two additional attributes: customer and label:

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST \
    -d '{"id":"mydevice_id", "customer":"tenant1", "label": "helloWorld"}' \
    "https://sandbox.waylay.io/api/resources"

Example of creating a resource and immediately linking it to the resource type:

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "id": "myDevice_id",
    "resourceTypeId": "resourceType_Id",
    "customer": "tenant1",
    "name": "helloWorld"
  }'
  "https://sandbox.waylay.io/api/resources"

Reserved keywords for metadata:

Symbol Type Meaning
resourceTypeId optional[String] id of the linked resource type
parentId optional[String] id of the parent resource
name optional[String] name of the resource, like testresource
owner optional[String] owner of the resource
provider optional[String] LoRA, Sigfox..
providerId optional[String] provder_123
customer optional[String] customer tenant name
tags optional[List[String]] (sequence of strings) // example [“Proximus”, “myTag”, “locationC”]
location optional [Location type] see below
firmware optional[String] 1.2_1234
lastMessageTimestamp optional[Integer] (epoch time of the last contact)
metrics optional[list[ResourceMetric]] see below
commands optional[Commands] see Commands
sensors optional[Sensors] see Sensors

Example of creating a resource with location:

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST \
  -d '{
    "id": "mydevice_id4",
    "customer": "tenant1",
    "label": "helloWorld",
    "location" : {
      "lat" : 51,
      "lon": 3.71
    }
  }' \
  "https://sandbox.waylay.io/api/resources"

Reserved keywords for Location type

Symbol Type
lat Double
lon Double

Reserved keywords for ResourceMetric

Symbol Type Example
name String Temperature
valueType String integer, double, boolean, string, enum
valueChoices optional[list[String]] [“OK”, “NOK”]
metricType String count / gauge / counter / timestamp (for events) default gauge
unit optional[String] SI units or non-SI units like Fahrenheit…
maximum optional[Double] 0
minimum optional[Double] 60

Example of creating a resource with a metric in the request:

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST
-d '
    {
      "id":"mydevice_id3",
      "customer":"tenant1",
      "label":"helloWorld",
      "metrics" : [
        {
          "name" : "Temperature",
          "unit":"C",
          "valueType": "double",
          "metricType": "counter" }]
      }' "https://sandbox.waylay.io/api/resources"

Reserved keywords for Metric type:

Symbol Meaning
rate a number per second (implies that unit ends on ‘/s’)
count a number per a given interval (such as a statsd flushInterval)
gauge values at each point in time
counter keeps increasing over time (but might wrap/reset at some point) i.e. a gauge with the added notion of “i usually want to derive this to see the rate”
timestamp value represents a unix timestamp. so `sically a gauge or counter but we know we can also render the “age” at each point.

More about metric types you can find here metric20org

Commands for resource

Commands feature allows you to specify generic set of actuators for a resource, which at runtime get resolved to a specific actuator.

‘Create a resource with a SayHi command’

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST
  -d '{
    "id" : "my_friendly_device",
    "greeter" : "Friendly device",
    "commands" : [{
       "SayHi" : {
         "actuator" : {
            "name": "debugDialog",
            "version": "latest",
            "properties" : {
              "message": "Hello, says the {{greeter}} !"
            }
         }
       }
    }]
  }' "https://sandbox.waylay.io/api/resources"

The commands property must be an array of objects. Each object must have one property which is the name of the command. The value must be an actuator definition with following properties:

Property Value
name Name of an actuator
version Exact version of the actuator or latest
properties Json object with default values for the properties of the actuator

When a command is sent to the broker for the resource and with name SayHi, the engine will check the commands property of the resource’s metadata and see if there is a command SayHi mapped to an actuator. If there is such a property and the mapped actuator could be found, the properties for the actuator are merged with the actual message sent to broker and the actuator is executed for the resource and the merged properties.

It is possible, in the properties of the actuator, to reference the metadata properties of the resource. They will be resolved to the actual value of the property at the moment of command execution. You can reference a metadata property by enclosing it’s name with {{ and }}. This is especially useful if you define commands at the resource type level, but need resource specific values

‘Send a SayHi command for resource testresource’

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST
  -d '{
    "name": "SayHi",
    "message": "Hello from this friendly resource"
  }' "https://data.waylay.io/resources/testresource/commands"

An interesting thing to note is that commands are sent over the broker and they are queued by the broker. That means that you can easily fan out all actuations this way, in case you need to send a lot of actuations in short period of time, without a worry whether sandbox can follow that sudden high load. Broker will make sure that they are all delivered with fastest pace, while at the same time, making sure they all have a chance to get executed by the sandbox.

Sensors for resource

You can also specify set of sensors that are applicable for a given resource. Please note that there is no explicit action taken by waylay platform on this meta key, unlike for commands, where waylay platform resolves a particular actuator for a given command call. Idea behind this abstraction is to assist integrations where an architect of the digital twin can specify which sensors from waylay library are applicable for a given resource (or resource type). For instance, you may have one sensor per metric, or multiple sensors for a given metric, or one sensor that is using multiple metrics. When calling a REST interface for meta, UI can be dynamically built based on set of capabilities for a resource both for actuations (using commands) and also associate set of sensors, next to supported metrics.

Create a resource with events sensor (which represents GoogleCalendar sensor)

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST
  -d '{
    "id" : "my_friendly_device",
    "sensors" : [
      {
        "name": "events",
        "sensor": {
          "name": "GoogleCalendarStreamSensor",
          "version": "0.1.5"
        }
      }
    ]
  }' "https://sandbox.waylay.io/api/resources"

The sensors property must be an array of objects. Each object must have a name property that describes the sensor along with a sensor property which is an object containing following properties:

Property Value
name Name of a sensor
version Exact version of the sensor or latest
properties Json object with default values for the properties of the sensor

Sensor properties in meta

[
  {
    "name": "<custom-name-for-sensor>",
    "sensor": {
      "name": "<sensor-name>",
      "version": "<sensor-version>",
      "properties": {
        "<some-sensor-property>": "<property-value>",
        "<another-sensor-property>": "<property-value>"
      }
    }
  }
]

Update resource

In order to update a resource, you need to put your resource Id in the path

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X PUT \
    -d '{"resourceTypeId":"resourceType_Id", "customer":"tenant1", "name": "helloWorld"}' \
    "https://sandbox.waylay.io/api/resources/myDevice_id"

Partial resource update

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X PATCH \
    -d '{"resourceTypeId":"resourceType_Id"}' \
    "https://sandbox.waylay.io/api/resources/myDevice_id"

Partial updates allow you to add/modify individual fields on a resource.

Delete resource

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X DELETE \
    "https://sandbox.waylay.io/api/resources/mydevice_id"

In order to delete a resource, you need to put your resource Id in the path

Retrieve resource

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources/[resourceId]"

This would return something like

{
  "id": "testresource",
  "resourceTypeId": "SampleResourceType",
  "metrics":[{
    "name": "Temperature",
    "valueType": "double",
    "metricType": "counter",
    "unit": "C"
  }],
  "customField": "value"
}

In order to get a resource, you need to put your resourceId in the path

This will give you a denormalized view of a resource where properties that are inherited from the resourceType are merged with the properties specified at resource level.

HAL representation

curl -i --user apiKey:apiSecret -H "Accept: application/hal+json" \
  "https://sandbox.waylay.io/api/resources/[resourceId]"

This would return something like

{
  "id": "Ground floor",
  "name": "Ground floor",
  "#desks": 0,
  "_links": {
    "self": {
      "href": "/api/resources/Ground%20floor"
    },
    "children": {
      "href": "/api/resources/Ground%20floor/children"
    },
    "parent": {
      "href": "/api/resources/Office",
      "id": "Office"
    },
    "resourceType": {
      "href": "/api/resourcetypes/4539e0c2-578e-4470-8f14-2ed81d576e3a",
      "id": "4539e0c2-578e-4470-8f14-2ed81d576e3a"
    }
  }
}

To retrieve a more “enriched” representation of the resource, specify the Accept header as application/hal+json

The _links property provides hyperlinks to api endpoints to retrieve more information about the resource. Following are provided:

Retrieve normalized resource

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources/[resourceId]?denormalized=false"

This would return something like

{
  "id": "testresource",
  "resourceTypeId": "SampleResourceType"
}

In order to get the normalized view of a resource, i.e. get only the properties that are specified on the resource level and not the ones inherited from the resource type level, set the query parameter denormalized to false.

This endpoint also supports the HAL resource representation by specifying the Accept: application/hal+json request header.

Query resources

Filtered resource list request

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources?filter=car"

Paging is handled by skip and limit parameters. If you have a large volume of resources, you can iterate of them like this:

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources?limit=1&skip=0"
curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources?limit=1&skip=1"
curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources?limit=1&skip=2
  etc

Resources can be queried by doing a GET request, if needed you can filter on these fields using the query string:

This endpoint also supports the HAL resource representation by specifying the Accept: application/hal+json request header. Resources will be returned in HAL format in the _embedded.values member. The result will next to the paging information (count, total, limit and skip) and the _embedded member, also contain a _links member that contains the links to

Geo distance query

Find all resources within 10km from point (51.05,3.73)

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources?lat=51.05&lon=3.73&distance=10km"

If your resources have coordinates specified in the location property (see Create resource), you find all resources within a specified distance from a point (specified by a lat and lon). See Distance units for the specification of distance

Retrieve resource change log

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources/[resourceId]/changes"

This returns a history of all changes to a resource sorted by change time descending.

If you want to page the list, you can do so by setting the Accept header to application/vnd.waylay.paged+json and using the skip and limit query parameters

Retrieve resource’s children

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources/[resourceId]/children"

Retrieves the child resources of the specified resource, i.e. all resources that have the specified resource as (direct) parent.

Page with skip and limit query parameters. Use ?denormalized=false to retrieve the normalized representation of the children.

This endpoint also supports the HAL resource representation by specifying the Accept: application/hal+json request header.

Retrieve resource command log

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resources/[resourceId]/commands"

will return something like

{
  "values": [
    {
      "name": "Say hi",
      "executionTime": "2018-09-24T13:59:10.377Z",
      "actuator": "debugDialog:LATEST",
      "result": {
          "success": true,
          "message": "Hi from resourcetype",
          "rawData": {}
      }
    },
    {
      "name": "Say his",
      "executionTime": "2018-09-24T13:58:56.075Z",
      "errorMessage": "Command 'Say his' not found"
    },
    {
      "name": "Say hi",
      "executionTime": "2018-09-24T10:47:59.739Z",
      "actuator": "debugDialog:LATEST",
      "result": {
          "success": true,
          "message": "resource brunocommand says hi",
          "rawData": {}
      }
    },
    ...
  ],
  "skip": 0,
  "limit": 10,
  "total": 16
}

This returns a paged list with the command exectutions. Page with skip and limit query parameters

Create resource type

In this example, we create a resource type and at the same time, we define metric types:

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST \
  -d '{"id":"resourceType_Id", "customField":"value", "metrics" : [{"name" :"Temperature", "unit":"C", "valueType": "double", "metricType": "counter" }]}' \
   "https://sandbox.waylay.io/api/resourcetypes"

Reserved keywords for resource type:

Symbol Type Example
id String D12345 or UUID
name optional[String] device_123
provider optional[String] Proximus
providerId optional[String] 123
customer optional[String] customer1
metrics optional[List[ResourceMetric]] list of metrics
commands optional[Command] Definition of commands
templates optional[List[templates]] Automatically create tasks by associating a template with a resource type

Update resource type

In order to update a resource type, you need to put your resource type Id in the path

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X PUT \
    -d '{"resourceTypeId":"resourceType_Id", "customer":"tenant1", "name": "myResourceType"}' \
    "https://sandbox.waylay.io/api/resourcetypes/resourceType_Id"

Partial resource type update

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X PATCH \
    -d '{"customer":"tenant2", "customField":"value"}' \
    "https://sandbox.waylay.io/api/resourcetypes/resourceType_Id"

Partial updates allow you to add/modify individual fields on a resource type.

Delete resource type

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X DELETE \
   "https://sandbox.waylay.io/api/resourcetypes/resourceType_Id"

Retrieve resource type

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resourcetypes/[resourceType_Id]"

In order to get a resource type, you need to put your resource type Id in the path

Query resource types

Paging is handled by skip and limit parameters

curl -i --user apiKey:apiSecret \
  "https://sandbox.waylay.io/api/resourcetypes?filter=car"

Resources can be queried by doing a GET request, if needed you can filter on these fields using the query string:

Retrieve resource type change log

curl -i --user apiKey:apiSecret \
 "https://sandbox.waylay.io/api/resourcetypes/[resourceType_Id]/changes"

This returns a history of all changes to a resource type sorted by change time descending.

If you want to page the list, you can do so by setting the Accept header to application/vnd.waylay.paged+json and using the skip and limit query parameters

Automatically create tasks by associating a template with a resource type

The waylay task engine can automatically provision tasks for each new resource. This is configured in the metadata of the resource type. All you need to add is a field templates that contains what templates should be used and what task configuration should be applied to these managed tasks.

Resource type definition:

{
    "id": "4b80d00a-89f0-41a0-b6e5-d4423caca844",
     ...
     "templates": [
        {
            "templateName": "templatex",
            "type": "periodic",
            "frequency": 60000
        },
        {
            "templateName": "templatey",
            "type": "scheduled",
            "cron": "0 0 12 * * ?"
        }
     ]
}

If for example an existing resource’s type is set to the above type type then 2 tasks will be created.

In general these managed tasks are created/removed for these actions:

Streaming (Real-time) data

Streaming data is data that is periodically updated and injected into a task so it can update it’s state. Injection of streaming data can happen directly to the api as shown below or by sending a message to the WaylayBroker which will then automatically be forwarded to the engine nodes linked to the same resource.

Streaming data is linked to a resource, this is a unique identifier that for example could be linked to a device or sensor. You can create as many tasks as you want that listen to this resource identifier.

Push Streaming (real-time) data

Below a direct REST call that pushes temperature:

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST -d '{
        "resource": "home_X_room1",
        "data":{
          "type": {
            "unit": "C",
            "dataType": "double",
            "collectedType": "instant"
          },
          "parameterName": "temperature",
          "value": 23.0,
          "collectedTime": 1420629467,
        }
      }' "https://sandbox.waylay.io/api/data"

If you need to process data in your sensors (like location, temperature etc.), you have two options:

In the case that streaming data is injected into the sensor that is linked to the same resource (option 1), the sensor will be executed. It can then access the injected data using waylayUtil.

When making use of this API call, you must use the resource parameter as the identifier of your device (or any other “thing”). This is the same resource identifier that is associated with the task/node when you create it. In this way, the waylay framework can link the pushed raw data and the tasks(and sensors) that require this data.

Here is the app view where you can test this feature(designer in debug mode):

Injected data view

You can also push several parameters at once, and you can as well skip most of the parameter’s attributes. For instance, with this call, we are pushing geolocation to the waylay platform, by specifying only longitude and latitude values. By default, waylay puts the collectedTime to the time the data was received:

curl --user apiKey:apiSecret -H "Content-Type:application/json" -X POST
-d '{
  "resource": "datasource",
  "data": [ {
            "parameterName": "latitude",
            "value": 51
          },
          {
            "parameterName": "longitude",
            "value": 3.73
          }
        ]
  }' "https://sandbox.waylay.io/api/data"

For related information also see the Plugin SDK documentation

Pushing states to the task

You can inject the state directly to the particular node in the task (as described before in the node section).

curl --user apiKey:apiSecret  --data "state=OPEN" -X POST https://sandbox.waylay.io/api/tasks/4/nodes/Door

For example, if you have a door with two states OPEN/CLOSED, you can push a state change from an external system to the task.

Alarms

Alarms on the Waylay platform are a way of tracking/following up on a condition/state of a resource.

Create an alarm

curl -i --user apiKey:apiSecret -H "Content-Type: application/json"
  -X POST
  -d '{
          "type" : "io.waylay.alarm.test",
          "timestamp" : "2011-09-06T12:03:27.845Z",
          "text" : "Some alarm documentation",
          "status" : "ACTIVE",
          "severity" : "MAJOR",
          "source" : { "id" : "12345", "self" : "..." }
          "task" : 3425,
          "myRef" : "902d4191-d1ab-47ae-8405-c33bb237f1d5"
        }'
   "https://alarms.waylay.io/alarm/alarms"

To create an alarm, you need to provide the following mandatory inputs:

Optional parameter :

Any property in the creation json payload, that is not in the above mandatory or optional parameters will be saved in the additionalProperties field of the created alarm

If an ACTIVE or ACKNOWLEDGED alarm with the same source.id and type exists, no new alarm is created. Instead, the existing alarm is updated by incrementing the countproperty and a new audit record of type io.waylay.alarm.EventOccuredAgain is added to the history. Only the latest 1000 io.waylay.alarm.EventOccuredAgain audit records are kept in the history.

Update an alarm

curl -i --user apiKey:apiSecret -H "Content-Type: application/json"
  -X PUT
  -d '{
        "severity" : "minor",
        "status" : "acknowledged",
        "assignee" : "user/385bfb40-cb4d-4ad7-a306-fa6dc7152150"
      }'
  "https://alarms.waylay.io/alarm/alarms/02eee99c-cd32-4fd0-9a35-89fa15570ccc"

Only severity, status and assignee can be updated. At least one field must be specified.

You can only update an ACTIVE or ACKNOWLEDGED alarm. Updating a CLEARED alarm will result in a response code 412 Precondition Failed

Clearing the assignee can be done by either setting it to the empty string ("") or null

Please notice that if the update actually doesn’t change anything (i.e. request body contains data that is identical to already present data in the database), there will be no audit record added.

Deletion of a single alarm

curl --user apiKey:apiSecret
  -X DELETE "https://alarms.waylay.io/alarm/alarms/02eee99c-cd32-4fd0-9a35-89fa15570ccc"

Deletion of alarms in bulk

curl --user apiKey:apiSecret
  -X DELETE "https://alarms.waylay.io/alarm/alarms?source=..."

You can delete multiple alarms by specifying at least one filter in the query string. The possible filters are the same as the filters for quering the alarms (see below): type, status, severity, source, dateFrom, dateTo, assignee

Automatic deletion of alarms

Alarms (even alarms in ACTIVE or ACKNOWLEDGED status) are only kept in the system for one year after creation. Any alarm older then 1 year is automatically deleted.

Get an alarm

curl --user apiKey:apiSecret "https://alarms.waylay.io/alarm/alarms/02eee99c-cd32-4fd0-9a35-89fa15570ccc"

Will return something like

{
    "id": "02eee99c-cd32-4fd0-9a35-89fa15570ccc",
    "self": "/alarm/alarms/02eee99c-cd32-4fd0-9a35-89fa15570ccc",
    "creationTime": "2017-09-12T15:23:33.075Z",
    "type": "io.waylay.alarm.test",
    "text": "Some alarm documentation",
    "timestamp": "2017-09-12T15:23:33.074Z",
    "source": {
        "id": "bruno"
    },
    "severity": "MAJOR",
    "status": "CLEARED",
    "count": 1,
    "assignee": "user/385bfb40-cb4d-4ad7-a306-fa6dc7152150",
    "history": [
        {
            "id": "02114638-5d25-4031-b22a-40c883eb4c79",
            "type": "io.waylay.alarm.AlarmRaised",
            "text": "Alarm raised",
            "timestamp": "2017-09-12T15:23:33.076Z"
        },
        {
            "id": "03bd1347-6d2b-4d90-bdb1-1b44972af3d1",
            "type": "io.waylay.alarm.AlarmUpdated",
            "text": "Alarm updated",
            "timestamp": "2017-09-23T11:18:56.358Z",
            "changes": [
                {
                    "attribute": "status",
                    "oldValue": "ACTIVE",
                    "newValue": "CLEARED",
                    "type": "io.waylay.alarm.change.status"
                }
            ]
         }
    ],
    "additionalProperties": {
        "task" : 3425,
        "myRef" : "902d4191-d1ab-47ae-8405-c33bb237f1d5"
    }
}

An alarm has following fields:

Name Type Description
id UUID Uniquely identifies an alarm.
self URI Link to this alarm.
creationTime ISO date string Time when alarm was created in the database.
type String Identifies the type of this alarm.
timestamp ISO date string Time of the alarm.
text String Text description of the alarm
source JSON Object The resource that the alarm originated from, as object containing the “id” property.
status String The status of the alarm: ACTIVE, ACKNOWLEDGED or CLEARED.
severity String The severity of the alarm: CRITICAL, MAJOR, MINOR or WARNING.
count Long The number of times this alarm has been sent.
assignee String The assignee of the alarm, will not be present if there is no assignee
history List of AuditRecord History of modifications tracing property changes.
additionalProperties JSON object Additional properties that were present in the alarm creation JSON payload

The history keeps a record of changes that have happened to the alarm. There are 3 different types of changes:

Query multiple alarms

curl --user apiKey:apiSecret "https://alarms.waylay.io/alarm/alarms"

This above call gives the first 50 alarms. If you need to filter the alarms, you can use a query language

curl --user apiKey:apiSecret
  "https://alarms.waylay.io/alarm/alarms?source=6&status=ACTIVE&status=CLEARED"

This would give you a result like

{
    "self": "/alarm/alarms?status=ACTIVE&status=CLEARED&source=6",
    "next": "/alarm/alarms?status=ACTIVE&status=CLEARED&source=6&page=2",
    "total": 361,
    "alarms": [
        {
            "id": "586ac2f2-fbec-426a-b696-d63d6cb153ac",
            "self": "/alarm/alarms/586ac2f2-fbec-426a-b696-d63d6cb153ac",
            "creationTime": "2017-08-23T11:16:37.856Z",
            "type": "alarmtest",
            "text": "Another test alarm",
            "timestamp": "2017-08-23T11:16:08Z",
            "source": {
                "stuff": "blabla",
                "id": "6"
            },
            "severity": "MINOR",
            "status": "CLEARED",
            "count": 1,
            "history": [
                {
                    "id": "54597bdb-7409-4c47-b7ba-f08922b67ca2",
                    "type": "io.waylay.alarm.AlarmRaised",
                    "text": "Alarm raised",
                    "timestamp": "2017-08-23T11:16:37.856Z"
                },
                {
                    "id": "03bd1347-6d2b-4d90-bdb1-1b44972af3d1",
                    "type": "io.waylay.alarm.AlarmUpdated",
                    "text": "Alarm updated",
                    "timestamp": "2017-08-23T11:18:56.358Z",
                    "changes": [
                        {
                            "attribute": "status",
                            "oldValue": "ACTIVE",
                            "newValue": "CLEARED",
                            "type": "io.waylay.alarm.change.status"
                        }
                    ]
                }
            ]
        },
        {
            "id": "df036bf8-4b32-4bd8-8ee7-42800ab26bf5",
            "self": "/alarm/alarms/df036bf8-4b32-4bd8-8ee7-42800ab26bf5",
            "creationTime": "2017-08-18T15:54:51.180Z",
            "type": "alarmType",
            "text": "Another test alarm",
            "timestamp": "2009-02-13T23:31:30.128Z",
            "source": {
                "id": "6"
            },
            "severity": "MAJOR",
            "status": "ACTIVE",
            "count": 2,
            "history": [
                {
                    "id": "e64de65c-e3ef-482d-9eb7-32ca17d1e147",
                    "type": "io.waylay.alarm.AlarmRaised",
                    "text": "Alarm raised",
                    "timestamp": "2017-08-18T15:54:51.183Z"
                },
                {
                    "id": "b708f1e2-9da4-442b-ac6c-0120b0b11c08",
                    "type": "io.waylay.alarm.EventOccuredAgain",
                    "text": "Alarm event occured again",
                    "timestamp": "2017-08-21T07:26:47.209Z"
                }
            ]
        },
        ...
}

You can also query for alarms

Query criteria can be specified in the query string. Available criteria:

Different query parameters are combined with logical AND operator. Specifying the same query parameter (only for type, status, severity and source) more then once, will be handled with a logical OR operation.

That means that if you combine e.g. status and source parameter, you will get only alarms on the specified source with the given status, but if you specify e.g. status twice (like status=ACTIVE&status=ACKNOWLEDGED) you will get all ACTIVE and ACKNOWLEDGED alarms

Paging is also supported through the query string with following options (results are sorted by descending timestamp):

The response does contain total number of alarms that fullfill the criteria. Also the response contains links to the current page self, to the next page if there is a next page and the previous page if there is one.

Query for ACTIVE alarms with additional property task=3425

curl --user apiKey:apiSecret
  "https://alarms.waylay.io/alarm/alarms?status=ACTIVE&task=3425"

To query the alarms based on the value of an additional property of the alarm, you can add the key of the additional property as query parameter with value the value you expect the alarm to have.

Alarm events

Get application/x-ndjson stream of alarm events

curl --user apiKey:apiSecret
     "https://alarms.waylay.io/alarm/events"

{
  "eventtype": "io.waylay.alarm.AlarmRaised",
  "eventtime": "2019-03-01T10:07:58.772962Z",
  "alarm": {
    "id": "f8c692cf-80f7-4ade-a0e2-3d3586b64ba0",
    "creationTime": "2019-03-01T10:07:58.772958Z",
    ...
  }
}
\n
{
  "eventtype": "io.waylay.alarm.EventOccuredAgain",
  "eventtime": "2019-03-01T10:07:55.960860Z",
  "alarm": {
    "id": "9f2b01b4-5932-4d43-b7fe-e18aae47a93d",
    "creationTime":
    ...
  }
}
\n
{
  "eventtype": "io.waylay.alarm.AlarmUpdated",
  "eventtime": "2019-03-01T10:07:55.963025Z",
  "alarm": {
    "id": "ab4d4695-82c6-4eb5-9615-80d9f7cdbd68",
    ...
  },
  "changes": [
    {
      "attribute": "status",
      "oldValue": "ACTIVE",
      "newValue": "CLEARED",
      "type": "io.waylay.alarm.change.status"
    }
  ]
}
\n
...

You can listen for events on alarm.

Each event contains the eventtype, an eventtime and the alarm (with reduced properties) on which the event happened.

Possible eventtypes:

In case the event is a io.waylay.alarm.AlarmUpdated event, the event will also contain a changes property that indicates what properties of the alarm changed.

Vault

The Vault allows a user to store secret values, encrypted at rest. Performing operations on the Vault require you to be authenticated.

Vault uses a 256-bit Advanced Encryption Standard (AES) cipher in the Galois Counter Mode (GCM) with 96-bit initialization vectors. The initialization vector is randomly generated for every encrypted object.

When data is read the GCM authentication tag is verified during the decryption process to detect any tampering.

Creating / updating a secret

Creating a secret requires the following:

Vault supports the following MIME types:

Text

Structured

Binary

Any other unrecognized MIME type is stored as a binary buffer, and will be returned as such.

$ curl -X PUT "https://vault.waylay.io/vault/my-secret" \
  -H "Content-Type: text/plain" \
  -d "this is a test"

$ curl -X PUT "https://vault.waylay.io/vault/my-json-secret" \
  -H "Content-Type: application/json" \
  -d '{ "hello": "world" }'

Retrieving a secret

If you”ve used the correct Content-Type header, you will receive your content exactly how Vault received it.

$ curl "https://vault.waylay.io/vault/my-secret"

Removing a secret

Simply send a DELETE request to the key you want to remove.

$ curl -X DELETE "https://vault.waylay.io/vault/my-secret"

Listing all secrets

$ curl "https://vault.waylay.io/vault"
[
  { "key": "my-text-secret" },
  { "key": "my-secret" }
]
cURL JavaScript