Actions

Schema Actions handle the functions that the devices can carry out.

Actions can manipulate properties, mandate changes in the state of the device, set timings for those states and trigger different activities on the device. In other words, Actions are an interface for operating the entity according to what the entity is supposed to do. These are added, like Properties and Events, to the Thing schema.

For example, you can see two potential actions (volumeChange and togglePower) for a stereo here:

{
    ...
    "actions": {
        "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"
                    }
                }
            }
        },
        "togglePower": {
            "title": "Turn On/Off",
            "description": "This action turns the stereo on or off, depending on the stereos current state."
        }
    }
}

As you can see, 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" - the togglePower Action above is like this. However, other times, actions require parameters in the command. volumeChange is like this, where the Action command needs to specify not just that the volume should change but what it should change to and how long it should take to get to that volume.

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 displayed in a UI	No	`string`
`description`	Additional content to tell the user what the action input is for.	No	`string`
`type`	Primitive data type for validation of the input	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."
        },
        "changeGroupId": {
            "description": "Removes group id",
            "input": {
                "maximum": 65535,
                "minimum": 0,
                "type": "integer"
            },
            "title": "RemoveGroupId"
        },
        "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"
                    }
                }
            }
        },
        "updateMode": {
            "title":"Switch the operating mode",
            "description": "This manually changes the operating mode of the asset.",
            "input": {
                "type":"string"
            }
        },
        "updateAlarmState": {
            "title":"Update the current state of the audible alarm",
            "description": "This can trigger or disable the alarm",
            "input": {
                "type":"boolean"
            }
        }
    }
}

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.
In the Title field, enter a title for the Action.

Figure 1.
If desired, enter any optional descriptors for this Action.
Click Create.
The information is added to the schema.

Figure 2.
Once the Action has been created, you can click on the Edit icon to make further changes to this Action.

Figure 3.