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

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

Figure 1.

Click Create.

The information is added to the schema.

actions": {
    "ToggleOn": {
      "description": "Turn the lamp on ",
      "input": {
        "type": "boolean"
      }
    }
},

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"
                    }
                }
            }
        },
        
    }
}