Johnson Controls Objects API

This section describes the operations you can perform on objects. Objects are self-contained functional items in the Metasys system, for a full definition refer to the [Metasys System Glossary](https://docs.johnsoncontrols.com/bas/r/Metasys/en-US/Metasys-System-Glossary/11.0/O). Use objects operations to list, create, edit, and delete objects. Apply filters, sorting, and paging to further refine the results. Some operations accept subscriptions, see [Change of Value Subscriptions](#change-of-value-subscriptions). ## Batch Subscriptions And Async Operations ### Change of Value Subscriptions Subscribe for change of value (COV) events to receive updates when attribute values change. Currently, subscriptions are available for [Get attribute value](#operation/getObjectAttribute) operations (individual and batch). #### Subscribing To subscribe for COV events, complete the following steps: 1. Obtain a stream ID using the workflow outlined in the [Streaming](#tag/streaming) section. 2. Use one of the following operations and include a `METASYS-SUBSCRIBE` header with the stream ID: - Single attribute: [Get attribute value](#operation/getObjectAttribute) - Multiple attributes: [Batch object operations](#operation/postObjectsBatch) **Note:** Any filters added to the original `GET` operation also apply to the event subscription. #### Unsubscribing To unsubscribe from a COV event, complete the following steps: 1. Get the `METASYS-SUBSCRIPTION-LOCATION` from the subscribe operation response. 2. Issue a [Delete COV subscription](#operation/deleteCOVSubscription) request to `METASYS-SUBSCRIPTION-LOCATION`. **See also:** - [Get a stream](#operation/getStream) - [Streaming](#tag/streaming) #### Events COV Events : There are four event types sent by the COV subscription: heartbeat, heartbeatImproved, update, and notification. ##### Heartbeat `object.values.heartbeat` - A heartbeat event is sent to show that the subscription is still alive. A heartbeat is a JSON string with the current UTC date time in ISO 8601 format and is sent every 30 seconds. ##### Heartbeat Improved `object.values.heartbeatImproved` - Similar to `object.values.heartbeat` but includes an array of all active subscription ids. ##### COV Update `object.values.update` - The client receives an update event when an attribute value changes. This payload is similar in structure as the payload returned by _Get attribute value_, but also includes `id` and `itemReference` of the object to provide context for the attribute in question. The overall schema for this payload is identical to the _Get an object_ schema (except this payload has no `effectivePermissions` property). The payload excludes the `schema` for the attribute by default, but it can be optionally included by using the `includeSchema` flag on the initial subscription request. ##### COV Notification `object.values.notification` - A notification event is sent when a value has changed but the value is not included in the payload. This happens for some values that are not simple scalar values. You can use this event as a trigger to reread the attribute. In the example, even though the payload does not include the current value, you know which object this is for (based on `id` and `itemReference`), and you know it is the `overrideExpirationTime` attribute based on the `attribute` property.