Discover templating point groups

curl --request POST \
  --url https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating/point-groups/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "deviceIds": [
    "<string>"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({deviceIds: ['<string>']})
};

fetch('https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating/point-groups/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating/point-groups/query"

payload = { "deviceIds": ["<string>"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

$headers=@{}
$headers.Add("Authorization", "Bearer <token>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating/point-groups/query' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
  "deviceIds": [
    "<string>"
  ]
}'

{
  "data": [
    {
      "groupKey": "pg1.Yz3kR1a2B3c4D5e6F7g8H9",
      "name": "SA-T",
      "kind": "Number",
      "writable": false,
      "unitSymbol": "°F",
      "pointEnum": [
        "Off",
        "On"
      ],
      "pointsCount": 212,
      "templateStatus": "NOT_TEMPLATED",
      "enumStatus": "N_A",
      "currentFields": [
        {
          "field": "dischargeAirTemp",
          "pointsCount": 12
        }
      ]
    }
  ],
  "page": 123,
  "limit": 123,
  "pageCount": 123,
  "itemCount": 123
}

POST

https://api.kodelabs.com/kodeos

api

buildings

{buildingId}

templating

point-groups

query

Discover templating point groups

curl --request POST \
  --url https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating/point-groups/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "deviceIds": [
    "<string>"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({deviceIds: ['<string>']})
};

fetch('https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating/point-groups/query', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating/point-groups/query"

payload = { "deviceIds": ["<string>"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

$headers=@{}
$headers.Add("Authorization", "Bearer <token>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://api.kodelabs.com/kodeos/api/v1/buildings/{buildingId}/templating/point-groups/query' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
  "deviceIds": [
    "<string>"
  ]
}'

{
  "data": [
    {
      "groupKey": "pg1.Yz3kR1a2B3c4D5e6F7g8H9",
      "name": "SA-T",
      "kind": "Number",
      "writable": false,
      "unitSymbol": "°F",
      "pointEnum": [
        "Off",
        "On"
      ],
      "pointsCount": 212,
      "templateStatus": "NOT_TEMPLATED",
      "enumStatus": "N_A",
      "currentFields": [
        {
          "field": "dischargeAirTemp",
          "pointsCount": 12
        }
      ]
    }
  ],
  "page": 123,
  "limit": 123,
  "pageCount": 123,
  "itemCount": 123
}

A point group holds the points of the selected devices that share the same connector name, kind, writable flag, and unit (for Number points) or enum values (for Bool and Str points). Points in one group can take the same ontology field, so you map one field to the whole group. Only real points are grouped. Virtual and metadata points are left out. Each group has a groupKey that the server derives from those values. Send it in the match of a mapping when you apply a plan. The body selects the devices with deviceIds (1 to 2,000) and can filter the groups:

templateStatuses: NOT_TEMPLATED or TEMPLATED.
kinds: Number, Bool, or Str.
enumStatuses: N_A, UNMAPPED, PARTIALLY_MAPPED, or MAPPED. N_A means the group has no enum to map, as with Number points.

Within a filter, a group matches any listed value. Across filters, a group must match every filter. The q parameter keeps only groups whose connector name contains the text. currentFields lists the fields already applied to the group’s points, with a point count for each. Remove it from fields if you do not need it, because it costs extra work on the server.

The body is the same selection you use for List points in a point group and for Apply a templating plan. Your service account needs the permission to view device and point templating. Applying and clearing need the permission to manage it.

Authorizations

Authorization

string

header

required

Paste an access token from Create an access token. Tokens expire, so request a new one if you receive 401.

Path Parameters

buildingId

string

required

Building identifier from List buildings.

Query Parameters

asc

string

Sort ascending. name sorts by connector name.

dsc

string

default:_id

Sort descending. name sorts by connector name.

fields

string

Comma-separated fields to return for each group. One or more of groupKey, name, kind, writable, unitSymbol, pointEnum, pointsCount, templateStatus, enumStatus, and currentFields. The default is every field. An unknown name returns 400.

limit

integer<int32>

default:50

Maximum number of groups to return, from 1 to 200. The default is 50.

Required range: 1 <= x <= 200

page

integer<int32>

default:1

Page number to return. The first page is 1.

Required range: x >= 1

string

Return only groups whose connector name contains this text.

Body

application/json

deviceIds

string[]

required

Explicit device ids to scope this discovery to.

Required array length: 1 - 2000 elements

Maximum string length: 255

Pattern: [^\p{C}\p{Z}]{1,128}

templateStatuses

enum<string>[]

Filter by template status(es).

Maximum array length: 10

Available options:

TEMPLATE_STATUS_UNSPECIFIED,

NOT_TEMPLATED,

PARTIAL,

TEMPLATED

Example:

["NOT_TEMPLATED"]

kinds

string[]

Filter by point kind(s), as stored: Number, Bool or Str.

Maximum array length: 3

Pattern: Number|Str|Bool

Example:

["Number"]

enumStatuses

enum<string>[]

Filter by enum-mapping status(es).

Maximum array length: 10

Available options:

ENUM_STATUS_UNSPECIFIED,

N_A,

UNMAPPED,

PARTIALLY_MAPPED,

MAPPED

Example:

["UNMAPPED"]

Response

A page of point groups.

data

object[]

Show child attributes

page

integer<int32>

limit

integer<int32>

pageCount

integer<int32>

itemCount

integer<int32>

Get started

Guides

API reference

Discover templating point groups

Authorizations

Path Parameters

Query Parameters

Body

Response