Name of the thermostat in SmartBuildings vs. name on the physical thermostat

Overview

Starting with v1.4.0 of the API, we're adding a new distinction in the API and the SmartBuildings applications between the name displayed in SmartBuildings and on the physical thermostat.

This is a feature many of our integrators have requested, so that they can allow the individual thermostat users to set a display name for themselves, while still allowing the property/building managers to set a name that makes sense to them in the context of a manager.

This is most relevant when a thermostat is in Tenant Mode. In that case the resident of the unit with the thermostat could be expected to change the name on the thermostat themselves either directly or after registering it in the ecobee Residential Portal.

Implementation Details

We've implemented this change of behavior in 2 areas.

1. Name as set and returned via the SmartBuildings API
2. Name as set and displayed in SmartBuildings

Name as returned via the SmartBuildings API

As of this release, the base thermostat route, GET /api/v1/thermostats/{thermostatId} will return an extra field: thermostatName.

This field indicates the name that will be shown on the thermostat itself, and the name that will be shown in the ecobee Residential Portal if the thermostat is in tenant mode and the tenant has registered the thermostat themselves.

The name field now indicates what will be shown in the SmartBuildings applications.

As a SmartBuildings API user, you now have the ability to set these names together or separately as desired. One or both of the fields may be set at the same time.

If an API user wishes to keep them in sync when setting the name, just pass in both fields with the same value in a single PATCH request.

Name as displayed in SmartBuildings

In the SmartBuildings web portal or mobile application, the display name of the thermostat will always be either the value from the name field in the API, or the thermostatId.

The thermostatId will be displayed only when the name field contains an empty string.

When a user changes the name of the thermostat in one of the SmartBuildings applications, one of two outcomes will happen:

1. If the thermostat is currently in tenant mode, i.e., isTenantMode is true, then the name will only be set for the SmartBuildings applications. Only the name field in the API will be updated.
2. If the thermostat is not in tenant mode, then the name will be set both for SmartBuildings and on the physical device. Both the name and the thermostatName fields in the API will be updated.

This behavior is different from the behavior when setting the name through the API, as the API user has full control of both the name and thermostatName fields and can set them independently.