> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Johnson Controls Metasys

> Connect Johnson Controls Metasys to KODE OS for equipment, points, trends, alarms, audits, and commands

> Connect Johnson Controls Metasys REST API v6 to KODE OS

## Overview

Use this integration to connect Metasys through the Telus SDF gateway. You can discover equipment and points, collect current and historical values, monitor alarms and audits, and run supported point commands.

| Property            | Value                   |
| ------------------- | ----------------------- |
| **System Type**     | Controllers             |
| **Communication**   | REST                    |
| **Collection**      | Pull                    |
| **Collection Mode** | SNAPSHOT and HISTORICAL |
| **Actions**         | Supported when enabled  |

## Supported capabilities

* Discover devices and points
* Collect current point values
* Collect historical point data
* Collect alarms and audit logs
* Invoke supported point commands

## Prerequisites

* Access to Metasys REST API v6 through the Telus SDF gateway
* A Telus SDF developer key
* Metasys permissions for the required equipment and activities
* Monitoring and Commanding licensing when you need point actions
* KODE OS access to `Data Sources`

## Configure the connector in KODE OS

1. Open `Data Sources` for your building.
2. Select `API Catalog`, then search for `Johnson Controls Metasys`.
3. Select `+ Add Datasource`.
4. Complete the connector fields.

| Field       | Required | Type     | Description                                     |
| ----------- | -------- | -------- | ----------------------------------------------- |
| **Name**    | Yes      | text     | Name that identifies this connection in KODE OS |
| **URL**     | Yes      | text     | Telus SDF gateway URL for Metasys               |
| **API Key** | Yes      | password | Telus SDF developer key                         |
| **Notes**   | No       | text     | Additional connection details                   |

KODE OS sends the developer key in the `X-TELUS-SDF-Developer-Key` header. Native Metasys login and refresh-token endpoints are not used.

## Discover devices and points

After you save the connector, select `Discover`. KODE OS reads the equipment hierarchy and keeps equipment-class nodes as devices. It then loads each device's points and schema details.

Review the returned devices and points, then save the records you want in KODE OS.

For more details, see the [Discovery guide](/products/integrations/capabilities/discovery).

## What data you get

### Point history

The connector batches current-value requests and stores values independently for each point. It also collects historical samples for trended attributes.

* **Current values** — Default polling: 10 minutes
* **Historical values** — Collected in bounded date windows

### Alarms and audit logs

KODE OS collects Metasys activities and separates them by activity type:

* `alarm` records become KODE OS alarms
* `audit` records become KODE OS audit logs

The connector polls activities every five minutes with an overlapping window. Vendor-specific details remain available in custom fields.

<Note>
  Audit activity depends on the logging and permissions configured in your Metasys environment.
</Note>

## Available actions

KODE OS can expose commands reported by Metasys, including:

* Adjust
* Override and temporary override
* Release override and release all
* Change default value

Command availability depends on Metasys role-based access, Monitoring and Commanding licensing, and gateway support. KODE OS displays a permission error when the current credential cannot invoke a command.

For more details, see the [Actions guide](/products/integrations/capabilities/actions).

## Use cases

Once connected, you can:

* Monitor equipment and point values across a building
* Analyze historical trends for performance issues
* Review alarms and audit activity in KODE OS
* Adjust supported setpoints and overrides remotely

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication or connection error">
    Verify the gateway URL and Telus SDF developer key. Confirm the gateway accepts Metasys REST API v6 requests.
  </Accordion>

  <Accordion title="Point values return a permission error">
    Confirm the Metasys account can read the object. The connector uses batch object requests because direct point-attribute routes may be blocked.
  </Accordion>

  <Accordion title="Commands are unavailable">
    Confirm Metasys role permissions, Monitoring and Commanding licensing, and gateway support for command requests.
  </Accordion>

  <Accordion title="Audit logs are empty">
    Verify that audit logging is enabled and the developer key can access audit activities in the target environment.
  </Accordion>
</AccordionGroup>