Getting Started with Management Set Hierarchy
Management Sets are only available to Utility or EMS accounts.
Introduction
To associate thermostats to an EMS or Utility, a web-based portal is created for the company. Thermostats must be added to a portal first before they can be addressed by the ecobee API with the privileges granted to the EMS or Utility account type. Thermostats associated with a company portal can be organized into folder-like groupings called a management set.
Management sets can be given a human-readable name, and can be nested into other management sets to create a hierarchy. Management sets are recursive, meaning that a parent node also contains all the thermostats assigned to all of its child nodes.
Assigning thermostats to a management set – and where they are organized
in the hierarchy – can be managed through the GUI of the web-based Utility or EMS portal, or
through the /hierarchy endpoints of the ecobee API.
Addressing Management Sets Through the API
Management sets may be used to indicate groupings of thermostats during API operations when available
through the Selection object.
To be more specific, when an API endpoint allows for a selectionType target of managementSet,
the management set path string can be used as the parameter value.
For example, given a management set named "Test Stats" created as a child of the root node, the unencoded HTTP request
to /thermostatSummary would look like the following:
https://api.ecobee.com/1/thermostatSummary?json={"selection":{"selectionType":"managementSet","selectionMatch":"/Test Stats"}}
Using a management set can be more convenient than passing in a CSV-delimited list of thermostats (as required when
using a selectionType target of thermostats) since management sets are not restricted to a list
size limit of 25 thermostats.
For performance, it is highly recommended that the maximum
number of thermostats in a management set stay under 1000 thermostats. While management sets may be nested to
create larger groupings for organizational purposes, only the child management set with under 1000 thermostats in it should be
used as the value for selectionMatch in an API request. Targeting a set above 1000 thermostats may result in a
server timeout before the results can be returned to your application.
Management Set Paths
By default, two system management sets are automatically created for every portal: a root management set named "My Sets" in which all other additional sets must be added to, and a special "Unassigned" set. Default system management sets cannot be renamed, moved, or removed.
In the web-based portal GUI, these default sets appear as the following:
Similar to operating system file folders, a string defines the path to the management set using forward slashes to delimit hierarchy
where / indicates the root set. In the ecobee API, this string is referred to as the setPath.
The following table is a summary of the two default system management sets:
| Web Portal Representation | Set Path String | Description |
|---|---|---|
| My Sets | / | The root set. User permissions may be assigned here but thermostats may not. Create management sets as children of My Sets, then assign thermostats to these sets. All user-defined set paths will be prefixed by a leading '/'. |
| Unassigned | Unassigned | A special set which represents all the thermostats registered with a portal but not currently
assigned to any set. Outside of /hierarchy API requests, API operations cannot be made on unassigned
thermostats, and the Unassigned set cannot be used as a target for selectionMatch. |
As previously mentioned, management sets can be added to the root node and nested into other management sets to create a hierarchy. Examples of set paths with nesting would look like the following:
"/" "/Location 1" "/Location 1/Group 1" "/Location 1/Group 2" "/Location 2" "/Location 2/Group 1"
User Privileges
Read/write privileges assigned to a Utility or EMS user are on a per-node basis. Child nodes recursively inherit the privileges assigned to its parent node.
The API user making the request may not elevate privileges above what the user already has, make changes to their own privileges, nor unregister themselves from the hierarchy.