{"_id":"5b53a7ff0dc83e000377f72d","project":"568bdc1483d2061900d86cdc","version":{"_id":"59a72290d61777001b6c42c3","project":"568bdc1483d2061900d86cdc","__v":31,"createdAt":"2017-08-30T20:39:44.453Z","releaseDate":"2017-08-30T20:39:44.453Z","categories":["59a7236e3fe4d90025117c10","59a72eb6cb0db3001b84cfe2","59a734eb757d030019b85af8","59c0243b1b2d07001a9d2b76","59c035e42126e10028effb12","59c06c40df5b3c0010584a13","59c1a5852cabe5002641a3e7","59c2fb00b2b45c0010b7a3d7","59c32ceb9aea850010ac4130","59c32e6e190c90003cb0d12f","59c33affb2b45c0010b7aa23","59c7dfa457bd8200105444dc","59c7e975c50cf30010d712a0","59cffdef0cd4dd0010294d54","59d0622ca91a810032c8f60c","59d06733c1aec60026253065","59d174d44ac471001a07b123","59d5a5e323e6e800103defb2","59ecf1d8ed507c001c52b255","59f76fef8581dc0010593e6f","5a0c003680a35b0012c35db0","5a8358722e78660075e45f42","5a846645b5ec3a001203517e","5b258091bc7a6700033b9cb5","5b26e48e024807000315a740","5b44edff3306680003663f5c","5b468abd3d4a9e0003789111","5b468d8f3dcb6a0003c6e374","5b47b0b93d4a9e000378a33a","5b538d114ea24f00033c726f","5b6a0efe402b32000336c33f"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.0.0","version":"0"},"category":{"_id":"5b47b0b93d4a9e000378a33a","project":"568bdc1483d2061900d86cdc","version":"59a72290d61777001b6c42c3","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2018-07-12T19:49:13.569Z","from_sync":false,"order":12,"slug":"features","title":"Features"},"user":"5a6a26281895510045b2cd40","githubsync":"","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-07-21T21:39:11.291Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"# Overview\n\nDevices can perform several tasks, such as dimming a light or adjusting the volume of a speaker. Behaviors enable several tasks to be scheduled into routines that can be performed either manually or in response to triggers, such as service events. Behaviors can be used to simplify the execution of complex procedures, allow for expedient transitions between personal settings, and perform acts when certain conditions are met.\n\n# API Index\n\n## Behaviors\n\n* List the behaviors in an [ecosystem](doc:list-behaviors-2), [environment](doc:list-behaviors), or [zone](doc:list-behaviors-1).\n* Get a particular behavior in an [ecosystem](doc:get-a-behavior-2), [environment](doc:get-a-behavior-1), or [zone](doc:get-a-behavior). \n* Create a behavior in an [ecosystem](doc:create-a-behavior-2), [environment](doc:create-a-behavior), or [zone](doc:create-a-behavior-1).\n* Update a behavior in an [ecosystem](doc:update-a-behavior-2), [environment](doc:update-a-behavior-1), or [zone](doc:update-a-behavior).\n* Delete a behavior from an [ecosystem](doc:delete-a-behavior-2), [environment](doc:delete-a-behavior), or [zone](doc:delete-a-behavior-1).\n* Start a behavior in an [ecosystem](doc:start-a-behavior-2), [environment](doc:start-a-behavior), or [zone](doc:start-a-behavior-1).\n* List the behaviors enabled in an [environment](doc:list-enabled-behaviors-1) or [zone](doc:list-enabled-behaviors).\n* Enable a behavior in an [environment](doc:enable-a-behavior-1) or [zone](doc:enable-a-behavior).\n* Disable a behavior in an [environment](doc:disable-a-behavior-1) or [zone](doc:disable-a-behavior).\n\n## Actions\n\n* List the actions of a behavior in an [ecosystem](doc:list-actions), [environment](doc:list-behavior-actions), or [zone](doc:list-behavior-actions-1).\n* Get a specific action of a behavior in an [ecosystem](doc:get-an-action-1), [environment](doc:get-an-action), [zone](doc:start-behavior-action).\n* Start an action of a behavior in an [ecosystem](doc:start-an-action-1), [environment](doc:start-an-action), or [zone](doc:start-a-behavior-action).\n* Stop an action of a behavior in an [ecosystem](doc:stop-an-action-1), [environment](doc:stop-an-action), or [zone](doc:stop-a-behavior-action).\n* Stop all actions of a behavior in an [ecosystem](doc:stop-actions), [environment](doc:stop-all-actions-1), or [zone](doc:stop-all-actions).\n\n# Actions\n\nActions are the individual duties that the behavior is asked to execute. Actions are capable of updating the service properties of several devices either all at once, or over a period of time. The latter is a special type of action, an animation, wherein the individual device state changes are spread out over a defined timeline.\n\nEach behavior has one main action that is initially invoked in order to kickstart the behavior. Each action, however, may be executed individually.\n\nActions may be executed immediately after one another, or they may be asked to wait for a trigger event before executing.\n\n# Schedules\n\nSchedules define when, and how often, an animation action is executed. A schedule determines the start time of the animation, and the frequency with which it reoccurs. \n\n# Triggers\n\nTriggers are hooks that listen for service notifications, such as service events, changes in device service properties, or other API calls. Actions may wait for trigger events to occur before executing.\n\n# Creating a Behavior\n\nA behavior is defined within a behavior file. This file contains all the configuration information for the behavior, and it is this file that is included in API requests to create or update behaviors. While a behavior file may be of any type, JSON and JSON5 are natively supported.\n\nA behavior file contains several primary properties:\n* **name**: the unique name of the behavior\n* **engine**: the version number of the behavior engine to be used\n* **description**: a brief description of the behavior\n* **main**: the name of the default action to initially execute\n* **parameters**: uniquely named variables for use within _constants_, _schedules_, and _actions_ \n* **constants**: uniquely named constants for use within _schedues_ and _actions_\n* **schedules**: definition for when an animation action executes\n* **actions**: tasks for the behavior to execute\n\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"WARNING\",\n  \"body\": \"The name of the behavior cannot be changed once it is made.\"\n}\n[/block]\n## `parameters`\n\nThe values of the properties of the `parameters` object are initialized when the behavior is enabled with the inclusion of a `parameters` object in the body of the request. Parameters must be uniquely named, and it is convention to prefix them with `:::at:::`. Individual parameters may optionally be made required.\n\nThere are three types of parameters:\n* **device**: the ID of a particular device\n* **group**: either a single device ID or an array of device IDs\n* **value**: any type of traditional data, including:\n  - `null`\n  - `boolean`\n  - `string`\n  - `number`\n  - `object`\n  - `array`\n\nIt is necessary that each parameter contain a `type` property, to indicate the kind of data to expect, and a boolean `required` property, to indicate if the particular parameter is required for the operation of the behavior.\n\n## `constants`\n\nConstants are used for storing static configuration information. It is convention to prefix them with `$`.\n\n## `actions`\n\nActions contain several tasks to be performed, such as service property updates and service method calls. These tasks are organized into either `sequences`, which perform all the included tasks sequentially, or `timelines`, which perform the tasks according to a defined itinerary. Actions also include `triggers` that use hooks to listen for relevant service notifications that, when detected, will initiate the execution of the action.\n\n### Timelines\n\nTimelines allow tasks to be performed according to a specified itinerary of events. A task may be placed on a point along the timeline to be performed at a certain time relative to the other tasks. \n\nWithin the `timeline` object, time objects, whose names are of the format `hh:mm:ss`, are placed. These time objects include tasks to be performed at the specified time. \n\nTimelines may also contain a `repeat` object, which contains the `period` and `iterations` properties. `period` specifies the total length, in seconds, of the timeline. If the period specified is less than the longest time object, the value of `period` will be silently changed to the time designated by that object. `iterations` specifies how many times the timeline will be repeated during a single execution of the animation action.\n\n## `schedules`\n\nSchedules determine the start time, the start offset, and the reoccurrence frequency of a behavior's actions. The start time is given in ISO 8601 format `yyyy-mm-ddT00:00:00.000Z`, and determines the time at which an action is to be executed. The start offset is where in an animation action's timeline the action is to begin; an animation may be initialized at any point, not just the beginning. An action may be set to repeat at a set interval or until certain conditions, such as when a number of repetitions are made or an end time is reached, have been met.\n\n## Sample Behavior File\n\n```\n{\n    \"name\": \"sample\",\n    \"engine\": \"1.0\",\n    \"description\": \"Sample behavior file to demonstrate the behavior engine\",\n    \"main\": \"\",\n    \"parameters\": {\n        \"@device1\": {\n            \"type\": \"device\",\n            \"required\": true\n        },\n        \"@device2\": {\n            \"type\": \"device\",\n            \"required\": true\n        },\n        \"@group\": {\n            \"type\": \"group\",\n            \"required\": false\n        },\n        \"@sonos\": {\n            \"type\": \"device\",\n            \"required\": true\n        }\n    },\n    \"constants\": {\n        \"$brightness\": 100,\n        \"$onFull\": {\n            \"BinarySwitch.switch\": \"on\",\n            \"DimmableSwitch.brightness\": \"$brightness\"\n        },\n        \"$off\": {\n            \"BinarySwitch.switch\": \"off\"\n        }\n    },\n    \"schedules\": {\n        \"schedule1\": {\n            \"enabled\": false,\n            \"startOffset\": 0,\n            \"startTime\": \"2018-04-04T00:32:54.813Z\",\n            \"reoccurence\": {\n                \"secondly\": {\n                    \"interval\": 2\n                }\n            }\n        }\n    },\n    \"actions\": {\n        \"turnOn\": {\n            \"sequence\": {\n                \"@device1\": \"$onFull\",\n                \"@device2\": \"$onFull\"\n            }\n        },\n        \"turnOff\": {\n            \"sequence\": {\n                \"@device1\": \"$off\",\n                \"@device2\": \"$off\"\n            }\n        },\n        \"groupOn\": {\n            \"sequence\": [\n                {\n                    \"@group\": \"$onFull\"\n                }\n            ]\n        },\n        \"animation\": {\n            \"timeline\": {\n                \"repeat\": {\n                    \"period\": 4,\n                    \"iterations\": 7\n                },\n                \"0\": {\n                    \"/invoke\": \"turnOff\"\n                },\n                \"0:01\": {\n                    \"@device1\": \"$onFull\"\n                },\n                \"0:02\": [\n                    {\n                        \"@device2\": \"$onFull\"\n                    }\n                ]\n            }\n        },\n        \"animation2\": {\n            \"schedules\": \"schedule1\",\n            \"timeline\": {\n                \"0:0\": {\n                    \"/invoke\": \"turnOff\"\n                },\n                \"0:01\": {\n                    \"@device1\": \"$onFull\",\n                    \"@device2\": \"$onFull\"\n                }\n            }\n        },\n        \"triggerd\": {\n            \"triggers\": {\n                \"hooks\": {\n                    \"@sonos\": {\n                        \"BinarySwitch.switch\": {\"/changed.to\": \"on\"}\n                    }\n                }\n            },\n            \"sequence\": {\"/invoke\": \"animation2\"}\n        }\n    }\n}\n```","excerpt":"Choreograph device actions.","slug":"behaviors","type":"basic","title":"Behaviors"}

Behaviors

Choreograph device actions.

# Overview Devices can perform several tasks, such as dimming a light or adjusting the volume of a speaker. Behaviors enable several tasks to be scheduled into routines that can be performed either manually or in response to triggers, such as service events. Behaviors can be used to simplify the execution of complex procedures, allow for expedient transitions between personal settings, and perform acts when certain conditions are met. # API Index ## Behaviors * List the behaviors in an [ecosystem](doc:list-behaviors-2), [environment](doc:list-behaviors), or [zone](doc:list-behaviors-1). * Get a particular behavior in an [ecosystem](doc:get-a-behavior-2), [environment](doc:get-a-behavior-1), or [zone](doc:get-a-behavior). * Create a behavior in an [ecosystem](doc:create-a-behavior-2), [environment](doc:create-a-behavior), or [zone](doc:create-a-behavior-1). * Update a behavior in an [ecosystem](doc:update-a-behavior-2), [environment](doc:update-a-behavior-1), or [zone](doc:update-a-behavior). * Delete a behavior from an [ecosystem](doc:delete-a-behavior-2), [environment](doc:delete-a-behavior), or [zone](doc:delete-a-behavior-1). * Start a behavior in an [ecosystem](doc:start-a-behavior-2), [environment](doc:start-a-behavior), or [zone](doc:start-a-behavior-1). * List the behaviors enabled in an [environment](doc:list-enabled-behaviors-1) or [zone](doc:list-enabled-behaviors). * Enable a behavior in an [environment](doc:enable-a-behavior-1) or [zone](doc:enable-a-behavior). * Disable a behavior in an [environment](doc:disable-a-behavior-1) or [zone](doc:disable-a-behavior). ## Actions * List the actions of a behavior in an [ecosystem](doc:list-actions), [environment](doc:list-behavior-actions), or [zone](doc:list-behavior-actions-1). * Get a specific action of a behavior in an [ecosystem](doc:get-an-action-1), [environment](doc:get-an-action), [zone](doc:start-behavior-action). * Start an action of a behavior in an [ecosystem](doc:start-an-action-1), [environment](doc:start-an-action), or [zone](doc:start-a-behavior-action). * Stop an action of a behavior in an [ecosystem](doc:stop-an-action-1), [environment](doc:stop-an-action), or [zone](doc:stop-a-behavior-action). * Stop all actions of a behavior in an [ecosystem](doc:stop-actions), [environment](doc:stop-all-actions-1), or [zone](doc:stop-all-actions). # Actions Actions are the individual duties that the behavior is asked to execute. Actions are capable of updating the service properties of several devices either all at once, or over a period of time. The latter is a special type of action, an animation, wherein the individual device state changes are spread out over a defined timeline. Each behavior has one main action that is initially invoked in order to kickstart the behavior. Each action, however, may be executed individually. Actions may be executed immediately after one another, or they may be asked to wait for a trigger event before executing. # Schedules Schedules define when, and how often, an animation action is executed. A schedule determines the start time of the animation, and the frequency with which it reoccurs. # Triggers Triggers are hooks that listen for service notifications, such as service events, changes in device service properties, or other API calls. Actions may wait for trigger events to occur before executing. # Creating a Behavior A behavior is defined within a behavior file. This file contains all the configuration information for the behavior, and it is this file that is included in API requests to create or update behaviors. While a behavior file may be of any type, JSON and JSON5 are natively supported. A behavior file contains several primary properties: * **name**: the unique name of the behavior * **engine**: the version number of the behavior engine to be used * **description**: a brief description of the behavior * **main**: the name of the default action to initially execute * **parameters**: uniquely named variables for use within _constants_, _schedules_, and _actions_ * **constants**: uniquely named constants for use within _schedues_ and _actions_ * **schedules**: definition for when an animation action executes * **actions**: tasks for the behavior to execute [block:callout] { "type": "warning", "title": "WARNING", "body": "The name of the behavior cannot be changed once it is made." } [/block] ## `parameters` The values of the properties of the `parameters` object are initialized when the behavior is enabled with the inclusion of a `parameters` object in the body of the request. Parameters must be uniquely named, and it is convention to prefix them with `@`. Individual parameters may optionally be made required. There are three types of parameters: * **device**: the ID of a particular device * **group**: either a single device ID or an array of device IDs * **value**: any type of traditional data, including: - `null` - `boolean` - `string` - `number` - `object` - `array` It is necessary that each parameter contain a `type` property, to indicate the kind of data to expect, and a boolean `required` property, to indicate if the particular parameter is required for the operation of the behavior. ## `constants` Constants are used for storing static configuration information. It is convention to prefix them with `$`. ## `actions` Actions contain several tasks to be performed, such as service property updates and service method calls. These tasks are organized into either `sequences`, which perform all the included tasks sequentially, or `timelines`, which perform the tasks according to a defined itinerary. Actions also include `triggers` that use hooks to listen for relevant service notifications that, when detected, will initiate the execution of the action. ### Timelines Timelines allow tasks to be performed according to a specified itinerary of events. A task may be placed on a point along the timeline to be performed at a certain time relative to the other tasks. Within the `timeline` object, time objects, whose names are of the format `hh:mm:ss`, are placed. These time objects include tasks to be performed at the specified time. Timelines may also contain a `repeat` object, which contains the `period` and `iterations` properties. `period` specifies the total length, in seconds, of the timeline. If the period specified is less than the longest time object, the value of `period` will be silently changed to the time designated by that object. `iterations` specifies how many times the timeline will be repeated during a single execution of the animation action. ## `schedules` Schedules determine the start time, the start offset, and the reoccurrence frequency of a behavior's actions. The start time is given in ISO 8601 format `yyyy-mm-ddT00:00:00.000Z`, and determines the time at which an action is to be executed. The start offset is where in an animation action's timeline the action is to begin; an animation may be initialized at any point, not just the beginning. An action may be set to repeat at a set interval or until certain conditions, such as when a number of repetitions are made or an end time is reached, have been met. ## Sample Behavior File ``` { "name": "sample", "engine": "1.0", "description": "Sample behavior file to demonstrate the behavior engine", "main": "", "parameters": { "@device1": { "type": "device", "required": true }, "@device2": { "type": "device", "required": true }, "@group": { "type": "group", "required": false }, "@sonos": { "type": "device", "required": true } }, "constants": { "$brightness": 100, "$onFull": { "BinarySwitch.switch": "on", "DimmableSwitch.brightness": "$brightness" }, "$off": { "BinarySwitch.switch": "off" } }, "schedules": { "schedule1": { "enabled": false, "startOffset": 0, "startTime": "2018-04-04T00:32:54.813Z", "reoccurence": { "secondly": { "interval": 2 } } } }, "actions": { "turnOn": { "sequence": { "@device1": "$onFull", "@device2": "$onFull" } }, "turnOff": { "sequence": { "@device1": "$off", "@device2": "$off" } }, "groupOn": { "sequence": [ { "@group": "$onFull" } ] }, "animation": { "timeline": { "repeat": { "period": 4, "iterations": 7 }, "0": { "/invoke": "turnOff" }, "0:01": { "@device1": "$onFull" }, "0:02": [ { "@device2": "$onFull" } ] } }, "animation2": { "schedules": "schedule1", "timeline": { "0:0": { "/invoke": "turnOff" }, "0:01": { "@device1": "$onFull", "@device2": "$onFull" } } }, "triggerd": { "triggers": { "hooks": { "@sonos": { "BinarySwitch.switch": {"/changed.to": "on"} } } }, "sequence": {"/invoke": "animation2"} } } } ```