Actions

Actions are an interface for operating the entity according to what the entity is supposed to do.

Actions handle the communication with the device to manipulate properties, mandate changes in the state of the device, set timings for those states and trigger different activities on the device.

Add Actions to a Thing

  1. In the Overview panel of a Thing, click the plus icon next to Actions.
    The New Action dialog opens.
  2. Enter the Action Key value. This should be a descriptor of the Action.
  3. If desired, enter a Title, any optional descriptors for the Action and the input type.


    Figure 1.
  4. Click Create.
    The information is added to the schema.
    actions": {
        "ToggleOn": {
          "description": "Turn the lamp on ",
          "input": {
            "type": "boolean"
          }
        }
    },
  5. Once the Action has been created, you can click on the Edit icon to make further changes to this Action.


    Figure 2.

Actions Detailed Information

Actions follow a very similar format to Properties (and indeed, to Events). AnythingDB provides a schema for defining Actions, and metadata keys for describing them in detail.

Table 1. All Actions can use the following metadata keys
Metadata Definition Description Required? Type
title Title of the action displayed in the UI No string
description Additional content to tell the user what the action is for. No string
input Defines the expected format of the action body. No object
Note: You may see additional metadata keys for actions in the W3C specification. These are not supported yet. These include "safe", "output", and "idempotent".

Many Actions are a simple command like "turn on" or "turn off". However, other times, Actions require parameters in the command like "Change Volume", where the Action command needs to specify not just that the volume should change but what it should change to.

These Action command parameters are defined in the input metadata key, in the Action description. This input key follows the same rules as a property - it can be defined by a primitive type and then, based on the type, further defined by other metadata keys.

The primitive types which can define these inputs are:
array
Expects a list of results
boolean
Expects a true/false
number
Expects any real number
integer
Expects any whole number
object
Expects a JSON object with additional properties defined.
Note: Using Object type properties, you can nest properties within properties to create rich structures.
string
Expects a series of letters and/or numbers
null
Expects no value
Each of these primitive types can be further defined by any or all of the following metadata keys.
Table 2. All input types can use the following metadata keys
Metadata Definition Description Required? Type
title Title of the action input No string
description Additional content to tell the user what the action input is for. No string
unit Provides a reference unit, especially for numbers and integers. No string
readOnly Validates that a value should not be written to. Yes (default is false) boolean
Note: In the Web of Things specification from W3C, many more metadata keys are allowed. Those are not yet supported. These include "enum", "titles", "descriptions", "@type", "const", "oneOf", "writeOnly", and "format". Nor do we support "items", "minItems" or "maxItems" on Arrays, as well as "properties" or "required" on Objects yet.
Table 3. Number input types can also use the following metadata keys (plus those in "All")
Metadata Definition Description Required? Type
minimum Minimum value. Used for validation. No number
maximum Maximum value. Used for validation. No number
Table 4. Integer input types can also use the following metadata keys (plus those in "All")
Metadata Definition Description Required? Type
minimum Minimum value. Used for validation. No integer
maximum Maximum value. Used for validation. No integer
Note: "String", "boolean" and "null" Action input types do not offer any additional definition beyond what is allowed in "all"
Below, you can see examples of these actions together:
{
    ...
    "actions": {
        "toggleOn": {
            "title": "Turn On/Off",
            "description": "This action turns the stereo on or off, depending on the stereos current state."
        },
      
        "volumeChange": {
            "title": "Change the volume",
            "description": "Change the volume of the Sound Stereo System over a set interval",
            "input": {
                "type": "object",
                "properties": {
                    "level": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                    },
                    "volumeLevelDuration": {
                        "type": "integer",
                        "minimum": 0,
                        "unit": "seconds"
                    }
                }
            }
        },
        
    }
}