logo
API docs by Redocly

Metasys REST API (Version 5)

Download OpenAPI specification:Download

Introduction

The Metasys REST API is the exposed interface for accessing data from a Johnson Controls® Metasys system. This spec documents v5 of the API first released as part of Metasys 13.0. This documentation was last updated on October 8, 2024 at 6:36 PM (UTC) and is assigned the revision identifier dad37a1b.

Note
The Metasys REST API is only supported on the following Metasys products: ADS, ADX, and OAS. The REST API is not supported on Metasys for Validated Environments (MVE) sites. Do not attempt to use the REST API on an MVE site.

Metasys is a network-based building automation system (BAS) that operates the mechanical and electrical equipment in your building. For an introduction to Metasys, refer to Metasys System in Metasys System Configuration Guide. For a glossary of Metasys terms, refer to Metasys System Glossary. For additional information on Metasys, search the Johnson Controls documentation site Knowledge Exchange.

This specification defines the operations you can use to retrieve data through the API. For further information on the Metasys API, including tutorials, see the Metasys API home page.

© 2022 Johnson Controls Tyco IP Holdings LLP.

Base URL

This documentation is for Metasys 13.0 which ships with version 5 of the Metasys Server.

The base path for the API is https://{hostname}/api/v5 where {hostname} is the host name of your Metasys server.

API Version Notes

Multiple versions of this API may be supported on one release of Metasys. At Metasys 13.0, the supported versions are v4 and v5. (However, v4 is deprecated and may be removed in a future release.)

Note: Versions earlier than v4 are not available on Metasys 13.0.

You must specify which version you intend to use in the URL, using the format v[#].

For example, https://localhost/api/v5/spaces for version 5 of spaces.

Documentation for v3 and earlier can be found here.

Version Response Behavior

The Content-Type header of the response will always contain (in part) the version of the API that was used to serve the request. This allows you to identify which version of the API was utilized.

For example, Content-Type: application/vnd.metasysapi.v5+json for version 5.

Licensed Operations

You must obtain an additional license to access some operations. For more information, refer to the Licensing information and Software information sections in Metasys System Software Purchase Options Product Bulletin (LIT-12011703).

Monitoring and Commanding API license

The Monitoring and Commanding API enables reading, writing, and commanding one or more Metasys objects/properties, including Present Value. This API succeeds the Metasys System Secure Data Access dynamic link library (MSSDA DLL).

The following operations require the Monitoring and Commanding API license:

Case Sensitivity Rules

In general, you should assume that all URLs, parameter names, parameter values, payload property names and payload property values are case sensitive. For example:

  • All attributes of objects are case sensitive. For example, many objects have an attribute named presentValue. It is case sensitive and must always be spelled presentValue.
  • Enumeration set names and set members are case sensitive (for example, reliabilityEnumSet.reliable, displayPrecisionEnumSet.displayPrecision1, and writePriorityEnumSet.priorityDefault).

Pagination

For operations where page and pageSize is allowed, the default page number will be 1 and is 1-based for all paths while the default pageSize will vary between paths. The page parameter indicates the page number of items to return from the path. The pageSize parameter indicates the maximum number of items in the response from the path.

Payloads returned by pagination-enabled paths have a similar structure. A total property indicates the total number of items included in all pages. A next and previous property supplies a link to the next and previous page of data, respectively. These properties can be empty if irrelevant (for example, if it is the first/last page, or there is only one page of data). The items property contains the data included in the page.

Sorting Rules

For operations where a sort query parameter is allowed, the supplied value should be in the format of a single attribute name, optionally prefixed with - to indicate descending sort order (ascending order is used if no prefix is supplied).

DateTimes

All date-times in the alarms, audits, activities, and samples operations are ISO-8601 encoded strings in UTC. Other operations, such as objects, use a proprietary structure further described in supporting documentation.

Validation and Common Error Codes

There are some general rules that apply across all operations. If certain provided inputs are invalid or preconditions are not met, the API will respond with an appropriate error to indicate what went wrong.

Condition Error Details
Invalid request body 400 (Bad Request) A body is provided which does not adhere to the expected format and/or schema
Missing required parameter 400 (Bad Request) A parameter marked required in this document is not included in the request
Parameter incorrect type 400 (Bad Request) A parameter is included with a value of the wrong type (for example, number is expected and string is provided)
Parameter out of range 400 (Bad Request) A numeric parameter is included but the value is outside the allowed range
Parameter not in set 400 (Bad Request) A string parameter has a set of predefined valid values, and the value provided is not included in that set
Parameter not in correct format 400 (Bad Request) A string parameter with expected format is provided in the wrong format
Unsupported Content-Type 400 (Bad Request) An unsupported Content-Type header is provided
User not authenticated 401 (Unauthorized) The auth token supplied with the request is missing, invalid, or expired
Record not authorized 403 (Forbidden) The user is not authorized to view data matching the provided identifier or too many requests
Invalid user type 403 (Forbidden) Not an "API user"; not all user accounts have API access
API version not supported for MVE 403 (Forbidden) An operation was attempted against a validated resource using a version of an API not supported for MVE
Identifier not found 404 (Not Found) An identifier is provided that does not match any known data
The resource already exists 409 (Conflict) The resource already exists
Internal Server Error 500 (Internal Server Error) An unexpected error occurred
The device is not supported 501 (Not Implemented) The server does not support the functionality required to fulfill the request
A service is unavailable 503 (Service Unavailable) A service is currently unavailable to service the request.
The device is offline 504 (Bad Gateway) An attempt was made to talk to another device that is currently offline.

Schemas in Response Payloads

The response payload of some operations in this document have a section of information labeled schema. This section of information includes important pieces of metadata about the item or items attributes that gives better context to the meaning of attribute values. This section follows JSON Schema specification with added custom annotation keywords.

Security

Bearer-Authentication

Most of the calls in the API use bearer token authentication. What this means is that these requests require an Authorization header to be set to a value with the following format: Bearer: {accessToken}. Use the /login operation to request an accessToken. An example of the full header would look like the following: Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1....

Note: This example access token is truncated.

The expiration time of the access token is based on the user's Metasys profile.

Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer
Bearer format: JWT

API-Key-Authentication

The Streaming operation is the only operation to use API key authentication, because web browsers do not allow setting custom headers when initiating Server Sent Event connections.

Security Scheme Type: API Key
Query parameter name: access_token

activities

This section describes the operations you can perform on activities. Activities are a superset of all alarms and audits in a Metasys system. Use activities operations to view audits and alarms. Apply filters to further refine the results.

Activities Event Subscriptions

Subscribe for activity-related events to receive updates when activities are created, discarded, acknowledged, or annotated.

Subscribing

To subscribe for activity-related events, complete the following steps:

  1. Open a stream with the Get a stream operation. Take note of the stream ID.
  2. Use Get Activities and include a METASYS-SUBSCRIBE header with the stream ID.

Note: Any filters added to the original GET operation also apply the event subscription.

Unsubscribing

To unsubscribe from an activities event subscription, complete the following steps:

  1. Get the METASYS-SUBSCRIPTION-LOCATION from the subscribe operation response.
  2. Issue a Delete activities subscription request to METASYS-SUBSCRIPTION-LOCATION.

See also:

Events

There are five event types sent by the activities subscription: acknowledged, annotate, discard, new, and heartbeat.

  • activity.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 Payload Example 
    {
  "currentTime": "2021-02-16T16:21:10.23Z",
  "subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"]
}

  • activity.alarm.ack - An alarm acknowledge event is sent to indicate that the management status has changed to acknowledged.

    Acknowledged Alarm Payload Example 
    {
  "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
  "activity": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
    "objectName": "OA_T",
    "activityManagementStatus": "acknowledged",
    "creationTime": "2021-02-16T20:30:00Z",
    "spaces": [
      {
        "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
        "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
        "name": "Floor 1",
        "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "equipment": [
      {
        "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
        "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
        "equipmentName": "Engine1",
        "shortName": null,
        "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
    "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
    "alarm": {
      "message": "",
      "alarmGeneratorObject": {
        "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
        "referencedObject": {
          "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
        }
      },
      "isAckRequired": true,
      "acknowledgedTime": "2021-02-16T20:31:02Z",
      "type": "alarmValueEnumSet.avHiAlarm",
      "priority": 70,
      "category": "objectCategoryEnumSet.generalCategory",
      "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "triggerValue": {
        "item": "2.0",
        "schema": {
          "type": "string",
          "metasysType": "string",
          "units": {
            "id": "unitEnumSet.degF",
            "title": "deg F"
          }
        }
      },
      "description": ""
    }
  },
  "effectivePermission": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "canAcknowledge": true,
    "canDiscard": true,
    "canAnnotate": true
  }
}

  • activity.alarm.annotate - An alarm annotate event is sent when an annotation is added to an alarm activity, providing the information for the annotated alarm.

    Annotate Alarm Payload Example 
    {
  "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
  "activity": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
    "objectName": "OA_T",
    "activityManagementStatus": "pending",
    "creationTime": "2021-02-16T20:30:00Z",
    "spaces": [
      {
        "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
        "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
        "name": "Floor 1",
        "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "equipment": [
      {
        "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
        "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
        "equipmentName": "Engine1",
        "shortName": null,
        "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
    "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
    "alarm": {
      "message": "",
      "alarmGeneratorObject": {
        "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
        "referencedObject": {
          "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
        }
      },
      "isAckRequired": true,
      "acknowledgedTime": "2021-02-16T20:31:02Z",
      "type": "alarmValueEnumSet.avHiAlarm",
      "priority": 70,
      "category": "objectCategoryEnumSet.generalCategory",
      "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "triggerValue": {
        "item": "2.0",
        "schema": {
          "type": "string",
          "metasysType": "string",
          "units": {
            "id": "unitEnumSet.degF",
            "title": "deg F"
          }
        }
      },
      "description": ""
    }
  },
  "effectivePermission": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "canAcknowledge": true,
    "canDiscard": true,
    "canAnnotate": true
  }
}

  • activity.alarm.discard - An alarm discard event is sent when the management status of an alarm activity changes to discarded.

    Discard Alarm Payload Example 
    {
  "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
  "activity": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
    "objectName": "OA_T",
    "activityManagementStatus": "discarded",
    "creationTime": "2021-02-16T20:30:00Z",
    "spaces": [
      {
        "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
        "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
        "name": "Floor 1",
        "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "equipment": [
      {
        "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
        "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
        "equipmentName": "Engine1",
        "shortName": null,
        "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
    "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
    "alarm": {
      "message": "",
      "alarmGeneratorObject": {
        "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
        "referencedObject": {
          "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
        }
      },
      "isAckRequired": true,
      "acknowledgedTime": "2021-02-16T20:31:02Z",
      "type": "alarmValueEnumSet.avHiAlarm",
      "priority": 70,
      "category": "objectCategoryEnumSet.generalCategory",
      "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "triggerValue": {
        "item": "2.0",
        "schema": {
          "type": "string",
          "metasysType": "string",
          "units": {
            "id": "unitEnumSet.degF",
            "title": "deg F"
          }
        }
      },
      "description": ""
    }
  },
  "effectivePermission": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "canAcknowledge": true,
    "canDiscard": true,
    "canAnnotate": true
  }
}

  • activity.alarm.new - A new alarm event is sent when an alarm activity is created.

    New Alarm Payload Example 
    {
  "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
  "activity": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
    "objectName": "OA_T",
    "activityManagementStatus": "pending",
    "creationTime": "2021-02-16T20:30:00Z",
    "spaces": [
      {
        "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
        "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
        "name": "Floor 1",
        "spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "equipment": [
      {
        "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
        "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
        "equipmentName": "IDU1",
        "shortName": null,
        "equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
    "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
    "alarm": {
      "message": "",
      "alarmGeneratorObject": {
        "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
        "referencedObject": {
          "objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
        }
      },
      "isAckRequired": true,
      "type": "alarmValueEnumSet.avHiAlarm",
      "priority": 70,
      "category": "objectCategoryEnumSet.generalCategory",
      "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "triggerValue": {
        "item": "2.0",
        "schema": {
          "type": "string",
          "metasysType": "string",
          "units": {
            "id": "unitEnumSet.degF",
            "title": "deg F"
          }
        }
      },
      "description": ""
    }
  },
  "effectivePermission": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "canAcknowledge": true,
    "canDiscard": true,
    "canAnnotate": true
  }
}

  • activity.audit.new - A new audit event is sent when an audit activity is created.

    New Audit Payload Example 
    {
  "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
  "activity": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "itemReference": "{hostname}:{deviceHostname}",
    "objectName": "MS-NAE5510-3",
    "activityManagementStatus": "pending",
    "creationTime": "2021-02-16T16:21:10.23Z",
    "objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
    "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
    "audit": {
      "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
      "status": null,
      "preData": null,
      "postData": {
        "item": "10.10.198.131",
        "schema": {
          "type": "string",
          "metasysType": "string"
        }
      },
      "parameters": [],
      "errorString": null,
      "user": "MetasysSysAgent",
      "signature": null,
      "classLevel": "auditClassesEnumSet.userActionAuditClass",
      "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
      "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
      "annotationsUrl": null,
      "self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
    }
  },
  "effectivePermission": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "canDiscard": true
  }
}

  • activity.audit.annotate - An annotate audit event is sent when an annotation is added to an audit activity, providing the information for the annotated audit.

    Annotate Audit Payload Example 
    {
  "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
  "activity": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "itemReference": "{hostname}:{deviceHostname}",
    "objectName": "MS-NAE5510-3",
    "activityManagementStatus": "pending",
    "creationTime": "2021-02-16T16:21:10.23Z",
    "objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
    "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
    "audit": {
      "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
      "status": null,
      "preData": null,
      "postData": {
        "item": "10.10.198.131",
        "schema": {
          "type": "string",
          "metasysType": "string"
        }
      },
      "parameters": [],
      "errorString": null,
      "user": "MetasysSysAgent",
      "signature": null,
      "classLevel": "auditClassesEnumSet.userActionAuditClass",
      "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
      "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
      "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
    }
  },
  "effectivePermission": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "canDiscard": true
  }
}

  • activity.audit.discard - An audit discard event is sent when the management status of an audit activity changes to discarded.

    Discard Audit Payload Example 
    {
  "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
  "activity": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "itemReference": "{hostname}:{deviceHostname}",
    "objectName": "MS-NAE5510-3",
    "activityManagementStatus": "discarded",
    "creationTime": "2021-02-16T16:21:10.23Z",
    "objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
    "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
    "audit": {
      "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
      "status": null,
      "preData": null,
      "postData": {
        "item": "10.10.198.131",
        "schema": {
          "type": "string",
          "metasysType": "string"
        }
      },
      "parameters": [],
      "errorString": null,
      "user": "MetasysSysAgent",
      "signature": null,
      "classLevel": "auditClassesEnumSet.userActionAuditClass",
      "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
      "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
      "annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
    }
  },
  "effectivePermission": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "canDiscard": true
  }
}

Filter Behavior

Filters supplied to an activities request limit the results to activities for which the filters apply. When subscribing to an activities request that uses filters, the events received are also limited to the same filter criteria. Exceptions to this behavior occur when filtering on activity management status, such as for acknowledged or discarded activities. You receive an update whenever an activity management change occurs, regardless of filters, because the change can impact the original set of activities you subscribed to. For example, consider the following scenario:

  • You subscribe to acknowledged activities and receive all acknowledged activities, receiving updates for any acknowledged thereafter across the stream.
  • In this state, one of the activities in your original list is discarded by another user.

When this occurs, you receive an activity.alarm.discard message for the discarded activity even though your filters exclude activities that are discarded. This is necessary so that you can properly maintain the state of activities already received in your application.

List activities

Retrieves a collection of activities.

Authorizations:
Bearer-Authentication
query Parameters
activityType
Array of strings[ items <= 2 items ]
Items Enum: "alarm" "audit"
Example: activityType=alarm

Limit the activities returned to a specific type

includeDiscarded
boolean

Determines whether discarded activities will be included in the results or be the only type of activity in the results. Discarded activities are those for which the activityManagementStatus is discarded.

This parameter can produce 3 different types of results.

  • true - Return only discarded activities in the response.
  • false - Do not include any discarded activities in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded activities are returned.
continuationToken
string
Example: continuationToken=eyJhdWRpdCI6eyJpZCI6IjgOTQ2NjUzLTlmM...

Provide a token from a previous request to fetch the next set of results. Ignored for streaming subscriptions.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether activities which can be acknowledged are included in the results. When the value is true, activities which can be acknowledged will be included in the results. When false, activities which can be acknowledged will not be included in the results.

The use of this parameter implies a filter of activityType=alarm and the results will not include any audits.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether activities which can not be acknowledged are included in the results. When the value is true then the results will include activities which cannot be acknowledged. When the value is false then the results will not include activities which cannot be acknowledged.

The use of this parameter implies a filter of activityType=alarm and the results will not include any audits.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

originApplication
Array of strings
Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp
metasysEnum: auditOriginAppEnumSet

Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message.

The acceptable values for the elements of this parameter come from the auditOriginAppEnumSet enumeration. Only the long name of the origin application (for example, auditOriginAppEnumSet.deviceManagerAuditOriginApp instead of deviceManagerAuditOriginApp) is accepted. Find the definition of auditOriginAppEnumSet at the relative URL of /schemas/enums/auditOriginAppEnumSet.

See also:

classLevel
Array of strings
Example: classLevel=auditClassesEnumSet.userActionAuditClass
metasysEnum: auditClassesEnumSet

Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose.

The Enabled Audit Level attribute (attributeEnumSet.auditEnabledClasLev) determines which audit levels the system generates. Therefore, be aware that there will be no audits to return if the Enabled Audit Level attribute is set too low to generate audits at the desired class level in this filter. This attribute is set per device (for audits generated on that device).

The acceptable values for the elements of this parameter come from the auditClassesEnumSet enumeration. Only the long name of the class level (for example, auditClassesEnumSet.userActionAuditClass instead of userActionAuditClass) is accepted. Find the definition of auditClassesEnumSet at the relative URL of /schemas/enums/auditClassesEnumSet.

See also:

actionType
Array of strings
Example: actionType=auditActionTypeEnumSet.writeAuditActionType
metasysEnum: auditActionTypeEnumSet

Filter by list of action types. The action type property indicates the user or system action performed.

The acceptable values for the elements of this parameter come from the auditActionTypeEnumSet enumeration. Only the long name of the action type (for example, auditActionTypeEnumSet.writeAuditActionType instead of writeAuditActionType) is accepted. Find the definition of auditActionTypeEnumSet at the relative URL of /schemas/enums/auditActionTypeEnumSet.

See also:

user
Array of strings <= 100 items
Example: user=metasysuser

Filter by list of users. The user property indicates which user initiated the action being audited.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/activities?activityType=alarm&includeDiscarded=false&continuationToken=eyJhdWRpdCI6eyJpZCI6IjgOTQ2NjUzLTlmM...&sort=creationTime&startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&category=objectCategoryEnumSet.hvacCategory&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Batch operations

Used to invoke multiple activity operations in a single HTTP request. In this version of the API, the only activity-related operations that can be used in a batch are listed below.

See also

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required
method
required
string
Enum: "PATCH" "POST"

The HTTP method to use for each request.

required
Array of objects

A collection of entries that represent the operations to invoke.

Responses

Request samples

Content type
application/json
Example

A request to discard multiple activities (2 audits and 2 alarms). One audit request and one alarm request include annotation text and the other requests do not.

{}

Response samples

Content type
application/vnd.metasysapi.v5+json

This is an example response to a batch request. Two of the operations succeeded and two of them failed.

{
  • "responses": [
    ]
}

Delete activities subscription

Deletes a subscription to the activities resource.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Responses

Request samples 

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/activities/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

alarms

Alarms alert users to potential problems identified by a Metasys system, for example high zone temperatures. Use alarms operations to get object alarms, network device alarms, single alarms, alarm collections, and alarm annotations. Acknowledge or discard alarms with the edit patch operation. Filter the results with the query parameters time, priority, type, category, acknowledgement, and page. Sort the results by creation time and priority.

Get alarms for an object

Retrieves a collection of alarms for the specified object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeDiscarded
boolean

Determines whether discarded alarms will be included in the results or be the only type of alarm in the results. Discarded alarms are those for which the activityManagementStatus is discarded. This parameter can produce 3 different types of results.

  • true - Return only discarded alarms in the response.
  • false - Do not include any discarded alarms in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether alarms which can be acknowledged are included in the results. When the value is true, alarms which can be acknowledged will be included in the results. When false, alarms which can be acknowledged will not be included in the results.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether alarms which can not be acknowledged are included in the results. When the value is true then the results will include alarms which cannot be acknowledged. When the value is false then the results will not include alarms which cannot be acknowledged.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Get alarms for a network device

Retrieves a collection of alarms for the specified network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeDiscarded
boolean

Determines whether discarded alarms will be included in the results or be the only type of alarm in the results. Discarded alarms are those for which the activityManagementStatus is discarded. This parameter can produce 3 different types of results.

  • true - Return only discarded alarms in the response.
  • false - Do not include any discarded alarms in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether alarms which can be acknowledged are included in the results. When the value is true, alarms which can be acknowledged will be included in the results. When false, alarms which can be acknowledged will not be included in the results.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether alarms which can not be acknowledged are included in the results. When the value is true then the results will include alarms which cannot be acknowledged. When the value is false then the results will not include alarms which cannot be acknowledged.

equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Get alarms Deprecated

Retrieves a collection of alarms.

Note: This operation is deprecated and may be removed in a future release. To retrieve alarms, consider using GET /activities?activityType=alarm instead. See List activities

Authorizations:
Bearer-Authentication
query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeDiscarded
boolean

Determines whether discarded alarms will be included in the results or be the only type of alarm in the results. Discarded alarms are those for which the activityManagementStatus is discarded. This parameter can produce 3 different types of results.

  • true - Return only discarded alarms in the response.
  • false - Do not include any discarded alarms in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether alarms which can be acknowledged are included in the results. When the value is true, alarms which can be acknowledged will be included in the results. When false, alarms which can be acknowledged will not be included in the results.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether alarms which can not be acknowledged are included in the results. When the value is true then the results will include alarms which cannot be acknowledged. When the value is false then the results will not include alarms which cannot be acknowledged.

equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Get an alarm

Retrieves the specified alarm.

Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/alarms/4d0598d4-2836-4efd-84b8-6f39754b1fc5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

An alarm for an analog value object.

{}

Edit an alarm

Allows for acknowledging or discarding an alarm.

Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

Request Body schema: application/json
required
activityManagementStatus
required
string
Enum: "acknowledged" "discarded"

The new activity management status of the alarm.

The values of this property are described as follows:

  • acknowledged - The alarm has been recognized and viewed by a user. An alarm may only be acknowledged if activityManagementStatus is currently pending and isAckRequired is true.
  • discarded - The alarm has been acted upon and addressed by a user. Once an alarm is discarded, it cannot be changed to any other state.
annotationText
string or null

The annotation associated with the change of alarm state.

Responses

Request samples

Content type
application/json
Example
{
  • "activityManagementStatus": "acknowledged"
}

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "code": "string",
  • "message": "string",
  • "details": { },
  • "innerError": { },
  • "innerErrors": [
    ]
}

Get alarm annotations

Retrieves the collection of annotations available for the specified alarm.

Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "user" "-user"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/alarms/4d0598d4-2836-4efd-84b8-6f39754b1fc5/annotations?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

audits

How to retrieve, discard, and annotate audits.

Relationships

Audits have relationships to other resources in the system. Find information about the most important below.

  • objects

When users or the system affect objects in the Metasys system, such as analog inputs, multistate objects, or binary outputs, audits are generated. Those "acted upon" objects then relate to those audits. That relationship is returned as part of any audit response.

  • equipment instances

Equipment instance associations to audits build off of the objects association explanation. Each equipment instance can contain many points, such as Outdoor Air Temperature, Damper Position, or Zone Setpoint. Those points map to actual objects in Metasys, as noted above. When users or the system affect those objects, audits are generated. If an equipment instance's point is mapped to one of those affected objects the instance is then associated with that audit.

In short, an equipment instance contains points which map to Metasys objects which are affected by an audited action.

  • spaces

Space associations to audits build off of the equipment instance association explanation. Equipment instances can serve spaces, such as an Air Handler Unit (AHU) serving the floor of a building. Therefore, audits associated with a particular equipment instance are associated to the spaces they serve.

Get audits for an object

Retrieves a collection of audits for the specified object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

originApplication
Array of strings
Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp
metasysEnum: auditOriginAppEnumSet

Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message.

The acceptable values for the elements of this parameter come from the auditOriginAppEnumSet enumeration. Only the long name of the origin application (for example, auditOriginAppEnumSet.deviceManagerAuditOriginApp instead of deviceManagerAuditOriginApp) is accepted. Find the definition of auditOriginAppEnumSet at the relative URL of /schemas/enums/auditOriginAppEnumSet.

See also:

classLevel
Array of strings
Example: classLevel=auditClassesEnumSet.userActionAuditClass
metasysEnum: auditClassesEnumSet

Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose.

The Enabled Audit Level attribute (attributeEnumSet.auditEnabledClasLev) determines which audit levels the system generates. Therefore, be aware that there will be no audits to return if the Enabled Audit Level attribute is set too low to generate audits at the desired class level in this filter. This attribute is set per device (for audits generated on that device).

The acceptable values for the elements of this parameter come from the auditClassesEnumSet enumeration. Only the long name of the class level (for example, auditClassesEnumSet.userActionAuditClass instead of userActionAuditClass) is accepted. Find the definition of auditClassesEnumSet at the relative URL of /schemas/enums/auditClassesEnumSet.

See also:

actionType
Array of strings
Example: actionType=auditActionTypeEnumSet.writeAuditActionType
metasysEnum: auditActionTypeEnumSet

Filter by list of action types. The action type property indicates the user or system action performed.

The acceptable values for the elements of this parameter come from the auditActionTypeEnumSet enumeration. Only the long name of the action type (for example, auditActionTypeEnumSet.writeAuditActionType instead of writeAuditActionType) is accepted. Find the definition of auditActionTypeEnumSet at the relative URL of /schemas/enums/auditActionTypeEnumSet.

See also:

user
Array of strings <= 100 items
Example: user=metasysuser

Filter by list of users. The user property indicates which user initiated the action being audited.

includeDiscarded
boolean

Determines whether discarded audits will be included in the results.

  • true - Return only discarded audits in the response.
  • false - Do not include any discarded audits in the response.
  • missing - Discarded status is ignored; both discarded and non-discarded audits are returned.
equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/audits?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser&includeDiscarded=false&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&space=214f52d1-0c56-4a29-a690-abe5656d1647&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Gets the first 10 audits.

{
  • "total": 400,
  • "next": "https://{hostname}/api/v5/objects/a68f10e5-da10-5b87-a96b-42a36e9919ae/audits?page=2&pageSize=10&sort=-creationtime",
  • "previous": null,
  • "items": [
    ],
  • "effectivePermissions": [
    ],
  • "self": "https://{hostname}/api/v5/audits?page=1&pageSize=10&sort=-creationtime"
}

Get audits Deprecated

Retrieves a collection of audits.

Note: This operation is deprecated and may be removed in a future release. To retrieve audits, consider using GET /activities?activityType=audit instead. See List activities

Authorizations:
Bearer-Authentication
query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

originApplication
Array of strings
Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp
metasysEnum: auditOriginAppEnumSet

Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message.

The acceptable values for the elements of this parameter come from the auditOriginAppEnumSet enumeration. Only the long name of the origin application (for example, auditOriginAppEnumSet.deviceManagerAuditOriginApp instead of deviceManagerAuditOriginApp) is accepted. Find the definition of auditOriginAppEnumSet at the relative URL of /schemas/enums/auditOriginAppEnumSet.

See also:

classLevel
Array of strings
Example: classLevel=auditClassesEnumSet.userActionAuditClass
metasysEnum: auditClassesEnumSet

Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose.

The Enabled Audit Level attribute (attributeEnumSet.auditEnabledClasLev) determines which audit levels the system generates. Therefore, be aware that there will be no audits to return if the Enabled Audit Level attribute is set too low to generate audits at the desired class level in this filter. This attribute is set per device (for audits generated on that device).

The acceptable values for the elements of this parameter come from the auditClassesEnumSet enumeration. Only the long name of the class level (for example, auditClassesEnumSet.userActionAuditClass instead of userActionAuditClass) is accepted. Find the definition of auditClassesEnumSet at the relative URL of /schemas/enums/auditClassesEnumSet.

See also:

actionType
Array of strings
Example: actionType=auditActionTypeEnumSet.writeAuditActionType
metasysEnum: auditActionTypeEnumSet

Filter by list of action types. The action type property indicates the user or system action performed.

The acceptable values for the elements of this parameter come from the auditActionTypeEnumSet enumeration. Only the long name of the action type (for example, auditActionTypeEnumSet.writeAuditActionType instead of writeAuditActionType) is accepted. Find the definition of auditActionTypeEnumSet at the relative URL of /schemas/enums/auditActionTypeEnumSet.

See also:

user
Array of strings <= 100 items
Example: user=metasysuser

Filter by list of users. The user property indicates which user initiated the action being audited.

includeDiscarded
boolean

Determines whether discarded audits will be included in the results.

  • true - Return only discarded audits in the response.
  • false - Do not include any discarded audits in the response.
  • missing - Discarded status is ignored; both discarded and non-discarded audits are returned.
equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/audits?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser&includeDiscarded=false&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Gets the first 10 audits.

{
  • "total": 400,
  • "next": "https://{hostname}/api/v5/audits?page=2&pageSize=10&sort=-creationtime",
  • "previous": null,
  • "items": [
    ],
  • "effectivePermissions": [
    ],
  • "self": "https://{hostname}/api/v5/audits?page=1&pageSize=10&sort=-creationtime"
}

Get an audit

Retrieves the specific audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/audits/4990ee27-7a0a-4b2b-9b27-279e3f1a060c \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

An audit for an analog value object.

{
  • "id": "6c6ae3dd-c514-423d-bd22-0b48678c5384",
  • "creationTime": "2021-12-10T21:05:53Z",
  • "actionType": "auditActionTypeEnumSet.commandAuditActionType",
  • "activityManagementStatus": "pending",
  • "status": "statusEnumSet.ok",
  • "spaces": [ ],
  • "equipment": [ ],
  • "preData": {
    },
  • "postData": null,
  • "parameters": [
    ],
  • "errorString": null,
  • "user": null,
  • "signature": null,
  • "objectUrl": "https://{hostname}/api/v5/objects/283fd3ad-ab1c-5849-8bdb-d635c5c274d9",
  • "self": "https://{hostname}/api/v5/audits/6c6ae3dd-c514-423d-bd22-0b48678c5384",
  • "itemReference": "{hostname}:{deviceHostname}/AV1",
  • "objectName": "Interlock1/AV1",
  • "classLevel": "auditClassesEnumSet.applicationAuditClass",
  • "originApplication": "auditOriginAppEnumSet.interlockAuditOriginApp",
  • "description": "commandIdEnumSet.adjustCommand"
}

Edit an audit

Allows for discarding an audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

Request Body schema: application/json
required
activityManagementStatus
required
string
Value: "discarded"

The new activity management status of the audit.

The only accepted value of this property is discarded because it is the only valid activity management state transition for an audit. Once an audit is discarded, it cannot be changed to any other state.

annotationText
string or null

The annotation to associate with the change of audit state.

Responses

Request samples

Content type
application/json
{
  • "activityManagementStatus": "discarded"
}

Response samples

Content type
application/vnd.metasysapi.v5+json
{
  • "code": "string",
  • "message": "string",
  • "details": { },
  • "innerError": { },
  • "innerErrors": [
    ]
}

Get audit annotations

Retrieves the collection of annotations available for the specified audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/audits/4990ee27-7a0a-4b2b-9b27-279e3f1a060c/annotations?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Add audit annotation

Adds an annotation to an audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

Request Body schema: application/json
required
text
required
string [ 1 .. 255 ] characters \S

The text of the annotation to create. This must not be null, empty, nor only whitespace. Additionally, any surrounding whitespace will be trimmed.

Responses

Request samples

Content type
application/json
{
  • "text": "Looks okay."
}

List audit users

Retrieves a list of unique usernames from all users present in a currently stored audit. The provided usernames may or may not reflect known users of the current system, but were known when the system recorded an audit for them.

Authorizations:
Bearer-Authentication

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/audits/users \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

authentication

Operations to get and refresh an access token.

Request access token

Use this to request an access token that can be used for authentication on other API calls.

Request Body schema: application/json
required

Used to supply credentials for login.

username
string

The user name of an account. This can either be a local Metasys account, or an Active Directory account that has been granted access to Metasys. When using an Active Directory account, the value should be in the format {name}@{domain} (for example, jane-doe@mycorp.com).

Note: Only accounts with an Access Type of API can be used to request a token from the REST API.

password
string

The corresponding password of a Metasys account.

Responses

Request samples

Content type
application/json
Example
{
  • "username": "jane-doe",
  • "password": "strongPassword"
}

Response samples

Content type
application/vnd.metasysapi.v5+json

The result includes the access token needed to make requests. (The token in this example has been truncated.)

{
  • "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
  • "expires": "2021-04-22T00:12:18Z"
}

Refresh a token

Use this operation to request a new token before the previous one expires.

Authorizations:
Bearer-Authentication

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/refreshToken \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

The result includes the access token needed to make requests. (The token in this example has been truncated.)

{
  • "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
  • "expires": "2021-04-22T00:12:18Z"
}

equipment

This section describes the operations you can perform on equipment. Equipment is a broad term for anything that makes a building run, including boilers, chillers, air handling units, lights, meters, and security systems. Use equipment operations to get equipment instances and to list equipment points. Apply filters, sorting, and paging to further refine the results.

Get equipment hosted by a network device

Retrieves the collection of equipment instances hosted by the specified network device or its children. A network device is considered to host an equipment if the equipment defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of equipment instances.

{}

Get equipment instances

Retrieves a collection of equipment instances.

Authorizations:
Bearer-Authentication
query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of equipment instances.

{}

Get a single equipment instance

Retrieves the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A single equipment instance.

{}

Get equipment served by an equipment instance

Retrieves the equipment served by the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of equipment instances.

{}

Get equipment that serve an equipment instance

Retrieves the collection of equipment that serve the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: 04d68394-3415-4813-b5ec-43d840deee38

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/equipment/04d68394-3415-4813-b5ec-43d840deee38/upstreamEquipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of equipment instances.

{}

List equipment points

Retrieves the collection of points that are defined by the specified equipment instance. Each point contains a mapping to an attribute on an object.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "shortName"
Enum: "category" "-category" "equipmentName" "-equipmentName" "isDisplayData" "-isDisplayData" "shortName" "-shortName"
Example: sort=shortName

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/points?page=1&pageSize=100&sort=shortName' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of equipment points

{}

Get equipment serving a space

Retrieves the collection of equipment that serve the specified space.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of equipment instances.

{}

network-devices

This section describes the operations you can perform on network devices. Network devices are physical devices such as coordinators and routers that are required for communication between hardware on a computer network. Use network device operations to get, list, and delete network devices. Apply filters, sorting, and paging to further refine the results.

List network devices

Retrieves a collection of network devices.

Authorizations:
Bearer-Authentication
query Parameters
objectType
string
Example: objectType=objectTypeEnumSet.bacnetIntegrationClass
metasysType: enum
metasysEnum: objectTypeEnumSet

The type of network device to return.

The objectType query parameter cannot be used in conjunction with the classification query parameter.

The acceptable values for this parameter come from the objectTypeEnumSet enumeration. Only the long name of the object type (for example, objectTypeEnumSet.bacnetIntegrationClass instead of bacnetIntegrationClass) is accepted. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

classification
Array of strings
Items Enum: "device" "integration" "server" "controller"
Examples:
  • classification=device&classification=server&classification=controller - Only devices (excludes integrations)
  • classification=device - Only supervisory engines
  • classification=server&classification=device - Servers and supervisory engines

The classification to filter devices on. One or more values are supported.

The classification query parameter cannot be used in conjunction with the objectType query parameter.

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/networkDevices?objectType=objectTypeEnumSet.bacnetIntegrationClass&page=1&pageSize=100&sort=name&classification=device&classification=server&classification=controller' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of network devices.

{}

Get a single network device

Retrieves the specified network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A single network device.

{}

Deletes a network device

Deletes an engine or a server which is a child device of the site director. Cannot be used to delete controllers, integrations, or the site director.

Note: The device must be offline for the operation to succeed.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

Responses

Request samples 

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

List network device children

Retrieves the collection of network devices that are children of the specified network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/networkDevices?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of network devices.

{}

List network devices hosting an equipment instance

Retrieves the collection of network devices that host the specified equipment instance, along with the parents of those network devices. A network device hosts an equipment when the equipment defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of network devices.

{}

List network devices serving a space

Retrieves the collection of network devices that serve the specified space. A space serves a network device when any equipment instance serving the space defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of network devices.

{}

objects

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. 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.

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 operations (individual and batch).

Subscribing

To subscribe for COV events, complete the following steps:

  1. Open a stream with the Get a stream operation. Take note of the stream ID.
  2. Use one of the following operations and include a METASYS-SUBSCRIBE header with the stream ID:

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 request to METASYS-SUBSCRIPTION-LOCATION.

See also:

Events

COV Events : There are three event types sent by the COV subscription: heartbeat, update, and notification.

  • 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.

  • 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.

subscriptionIds
required
Array of strings <uuid> [ items <uuid > ]

Subscription IDs that the update applies to

required
object

New value information for the subscribed attributes with additional identifying information for the object the update applies to.

object (condition)

This property contains condition flags (if any are set) for the properties of item. If none of the properties have any condition flags set, then condition will not be included in the response or it will be empty.

schema
object

A JSON schema that describes the properties of the item property

{
  • "subscriptionIds": [
    ],
  • "item": {
    },
  • "condition": {
    }
}
  • 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.
subscriptionIds
required
Array of strings <uuid> [ items <uuid > ]

Subscription IDs that the notification applies to

required
object

Identifying information for the object the notification applies to which a client can use to read the new value of the attribute.

attribute
required
string
metasysType: enum
metasysEnum: attributeEnumSet

The attribute the notification applies to.

The values for this property come from the attributeEnumSet enumeration. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

object (condition)

This property contains condition flags (if any are set) for the properties of item. If none of the properties have any condition flags set, then condition will not be included in the response or it will be empty.

{
  • "subscriptionIds": [
    ],
  • "item": {
    },
  • "condition": {
    },
  • "attribute": "attributeEnumSet.overrideExpirationTime"
}

List objects

Returns the root object of the tree and, optionally, its children. The root object is the site object. The default response is a tree representation. Set flatten=true to flatten the tree into a list representation. The number of levels returned depends on the value of the depth parameter. To get just the root of the tree use a depth of 0. Values of depth greater than 1 are not allowed on this endpoint.

Authorizations:
Bearer-Authentication
query Parameters
depth
integer [ 0 .. 1 ]
Default: 1
Example: depth=1

The depth of the tree to return. The provided value is ignored if pathTo, objectType, or classification are specified.

flatten
boolean
Default: false

A value of true indicates the response payload should be a flat list. A value of false (the default) indicates the response payload should be a tree with child objects nested under their parent object. While this parameter influences the shape of the response, it does not affect the content. The same set of objects is returned no matter the value of this parameter.

includeExtensions
boolean
Default: false

A value of true indicates that extension objects should be included in the result. A value of false (the default) indicates that they should not be included.

This parameter is ignored if pathTo is specified.

pathTo
string
Example: pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a

This parameter causes the response to contain the object specified by this parameter, the root object, and the objects in between.

If this parameter is specified, then depth and includeExtensions are ignored.

includeEffectivePermissions
boolean
Default: false
Example: includeEffectivePermissions=true

Include the effectivePermissions property in the response payload. This property describes which objects in the response the current user can view, modify or delete.

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects?depth=1&flatten=false&includeExtensions=false&pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a&includeEffectivePermissions=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

The objects are returned in a tree structure. Child objects are nested under their parents.

{}

Create object

Creates a new object. Several things are needed to successfully create an object. You must know

  • the type of object you want to create
  • if that object type is supported in the location you want to create it
  • what properties can be set on that type of object when creating it
  • what properties are required to be set.

Find the complete list of object types with the operation GET /schemas/enums/objectTypeEnumSet. To determine the specific set of objects that can be created in a location use List supported child types (GET /objects/{objectId}/supportedChildTypes). To discover what object properties can be set and which are required when creating an object use Get a schema for an object type (GET /schemas/objectTypes/{objectType})

See also:

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required
parentId
required
string

The ID of the parent object. The new object will be created under this object.

localUniqueIdentifier
required
string <= 32 characters ^[^\x00-\x1F\x7F\x22#'*,.\/:<>?@\[\\\]|]+$

A string that is locally unique within the context of the parent object for identifying the new object. This string will be the last component of the itemReference of the newly created object. For example, assume you have a folder with an itemReference of adx:oas/Programming. Then you create an AV with a local unique identifier of ZN-3-T within that folder. The newly created object will have an itemReference of adx:oas/Programming.ZN-3-T.

The value must not contain any control characters or any of the following characters: " # ' * , . / : < > ? @ [ \ ] |

objectType
required
string
metasysType: enum
metasysEnum: objectTypeEnumSet

The type of object to create.

The values for this property come from the objectTypeEnumSet enumeration. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

item
object

The item object is where you set the properties of the newly created object. Which properties can be set and their data types can be discovered by using the Get schema for object type operation.

This property may or may not be required depending on the object you are creating. Some objects have defaults for all properties and require nothing to be set when creating them. Others have required properties that must be set at creation time.

Responses

Request samples

Content type
application/json
Example

This request body creates a new object of type objectTypeEnumSet.avClass under a folder with an identifier of 82b6f2d5-6fed-5074-b611-94dd40028312 with a locally unique identifier of ZN-3-SETPT. The properties on the new object are name, description, objectCategory, minPresValue and maxPresValue.

{
  • "parentId": "82b6f2d5-6fed-5074-b611-94dd40028312",
  • "localUniqueIdentifier": "ZN-3-SETPT",
  • "objectType": "objectTypeEnumSet.avClass",
  • "item": {
    }
}

List child objects

Returns the specified object and optionally one or more levels of the tree under the object. The default response is a tree representation. Set flatten=true to flatten the tree into a list representation.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 767d8af0-163f-552c-ba37-a884466075f9

Specifies the root of the subtree to return for this request. The objectId is the identifier of the object to retrieve (optionally along with 1 or more levels of descendants).

query Parameters
depth
integer >= -1
Default: 1
Example: depth=1

The depth of the tree to return. For typical usage, a value or 1 or 2 is recommended. Use -1 for maximum depth.

The provided value is ignored if pathTo, objectType, or classification are specified.

flatten
boolean
Default: false

A value of true indicates the response payload should be a flat list. A value of false (the default) indicates the response payload should be a tree with child objects nested under their parent object. While this parameter influences the shape of the response, it does not affect the content. The same set of objects is returned no matter the value of this parameter.

includeExtensions
boolean
Default: false

A value of true indicates that extension objects should be included in the result. A value of false (the default) indicates that they should not be included.

This parameter is ignored if pathTo is specified.

pathTo
string
Example: pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a

This parameter filters the response down to just containing the object specified by this parameter, the object specified by objectId in the path, and the objects in between.

If this parameter is specified, then depth, includeExtensions, objectType and classification are ignored.

objectType
Array of strings
Examples:
  • objectType=avClass - Analog Value Object Type
  • objectType=bvClass - Binary Value Object Type
  • objectType=mvClass - Multiple Value Object Type
  • objectType=avClass&objectType=bvClass - Multiple Types
metasysType: enum
metasysEnum: objectTypeEnumSet

Type of objects to include in the response. This parameter may be repeated. To search for all AV and AI objects one would specify /objects?type=objectTypeEnumSet.avClass&type=objectTypeEnumSet.aiClass.

The use of this parameter overrides depth to -1 and includeExtensions to true.

It is an error to specify this parameter if classification is specified.

The response will include the specified object, the objects that match the objectType for the given depth and any objects in between (like folders and devices).

The acceptable values for the elements of this parameter come from the objectTypeEnumSet enumeration. It is acceptable to use the short name of the object type (for example, avClass instead of objectTypeEnumSet.avClass) because the enumeration set is known from context. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

classification
Array of strings
Items Enum: "object" "device" "integration" "controller" "point" "site" "navList" "extension" "folder" "reference" "server" "archive"
Examples:
  • classification=object - Any object not classified by one of the other classification values
  • classification=device - An object that represents a supervisory controller
  • classification=controller - An object that represents a field controller
  • classification=object&classification=point - Points and Objects

Filter objects to those with the specific classification. The use of this parameter overrides depth to -1 and includeExtensions to true. It is an error to specify this parameter if objectType is specified.

includeEffectivePermissions
boolean
Default: false
Example: includeEffectivePermissions=true

Include the effectivePermissions property in the response payload. This property describes which objects in the response the current user can view, modify or delete.

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/767d8af0-163f-552c-ba37-a884466075f9/objects?depth=1&flatten=false&includeExtensions=false&pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a&objectType=avClass&classification=object&includeEffectivePermissions=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

The objects are returned in a tree structure. Child objects are nested under their parents.

{}

Get object id Deprecated

Use Lookup object identifier instead.

Finds the object identifier (the id property of an object) for the object with the specified fully qualified reference (fqr).

Authorizations:
Bearer-Authentication
query Parameters
fqr
required
string
Examples:
  • fqr=adx:adx - An example of a site director fqr
  • fqr=adx:nae23/Programming.AV1 - An example of an analog value object fqr
format: fully-qualified-reference

The fully qualified reference of an object. It refers to an object's itemReference property.

Fully qualified references use characters that must be escaped when used as query parameters. Most HTTP libraries do this for you automatically. However, if you are using curl or PowerShell where you specify the full URL yourself you may need to be aware. For example, here is the URL to use with curl for a reference of oas:oas/Programming.AV3: https://{hostname}/api/v5/objectIdentifiers?fqr=oas%3Aoas%2FProgramming.AV3

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objectIdentifiers?fqr=adx%3Aadx' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
"32cfddc0-411f-5b9e-9a6d-442cb62fecbb"

Lookup object identifier

Finds the object identifier (the id property of an object) for the object with the specified fully qualified reference (fqr).

Authorizations:
Bearer-Authentication
query Parameters
fqr
required
string
Examples:
  • fqr=adx:adx - An example of a site director fqr
  • fqr=adx:nae23/Programming.AV1 - An example of an analog value object fqr
format: fully-qualified-reference

The fully qualified reference of an object. It refers to an object's itemReference property.

Fully qualified references use characters that must be escaped when used as query parameters. Most HTTP libraries do this for you automatically. However, if you are using curl or PowerShell where you specify the full URL yourself you may need to be aware. For example, here is the URL to use with curl for a reference of oas:oas/Programming.AV3: https://{hostname}/api/v5/objectIdentifiers?fqr=oas%3Aoas%2FProgramming.AV3

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/identifiers?fqr=adx%3Aadx' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
"32cfddc0-411f-5b9e-9a6d-442cb62fecbb"

Get an object

Objects support one or more views. By default, this operation gets the default view of an object. For many objects this is the Focus View (identifier viewNameEnumSet.focusView). To see the list of views an object supports see List Views (/objects/{objectId}/views). To get a different view of an object specify a value for the viewId parameter.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

  • List Views for information on retrieving the view collection of an object.
Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
viewId
string
Examples:
  • viewId=viewNameEnumSet.focusView - Focus View
  • viewId=viewNameEnumSet.diagnosticView - Diagnostic View
metasysEnum: viewNameEnumSet

The view to retrieve.

This parameter is optional and if it is not specified the default view for the object will be returned. For many objects this is the Focus view (focusView).

The acceptable values for this parameter come from the viewNameEnumSet enumeration. It is acceptable to use the short name of the view (for example, focusView instead of viewNameEnumSet.focusView) because the enumeration set is known from context. Find the definition of viewNameEnumSet at the relative URL of /schemas/enums/viewNameEnumSet.

See also:

includeSchema
boolean

Every object can have a unique schema. Set this parameter to true to include the schema for this object in the response payload.

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb?viewId=viewNameEnumSet.focusView&includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

This is an example of an AV object without a schema. Notice that the presentValue is 105 but the maxPresValue is set to 100. This results in the presentValue attribute going unreliable. This can be seen in the condition object where presentValue has a reliability value of reliabilityEnumSet.unreliableHigh. We can also see that the current priority for presentValue is set to writePriorityEnumSet.priorityCriticalEquipment.

{}

Edit an object

This operation modifies one or more attributes of an object. Note: attributes must be updated in whole. For example, if you wish to modify an attribute of metasysType struct which is modelled as a JSON object you must include all elements of the struct. It is undefined what might happen if you do not. The write could fail, the non-mentioned members may get their default value or something else. This applies to any attribute that has a JSON type of array or object. The entire attribute value must be written even if you only wish to change one part of the value.

The request body contains an item property which contains one or more properties and their new values.

The attributes of an object (and their schemas) can be discovered by looking at the different views of an object or by requesting all of the attributes.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Request Body schema: application/json
required
item
object

The attributes to update.

Responses

Request samples

Content type
application/json
Example
{
  • "item": {
    }
}

Delete an object

Deletes the specified object.

Not all objects can be deleted (not even by an administrator). Examine the effectivePermissions of an object to determine if it can be deleted by the current user.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

List the views of an object

Objects support one or more views. Each view of an object contains a logical grouping of the object's attributes. This operation lists the collection of views that an object has.

Each entry in the response contains the id of a view, and also the absolute URL used to request that view. Use Get an object (/objects/{objectId}) to request a specific view by specifying the desired id for the viewId query parameter.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
includeSchema
boolean

Set this parameter to true to include a schema in the response.

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/views?includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

List attributes of an object

Returns an object payload with a JSON schema that contains all of the properties of the object. Each property entry contains only a partial schema for that property. (To discover the full schema of an attribute use /objects/{objectId}?includeSchema=true or /objects/{objectId}/attributes/{attrId}?includeSchema=true

The item section of the payload will contain at most one attribute, the defaultAttribute. The item section will be completely missing if the object does not have a default attribute.

There will be no views or condition sections like a typical object payload.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/attributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example
{
  • "item": {
    },
  • "schema": {
    }
}

Get attribute value

Returns an object payload containing the specified attribute. Invoke this operation with a valid METASYS-SUBSCRIBE header to create a subscription for changes to that attribute, rather than returning a value. The current value and any updates to the attribute are instead sent over the specified stream.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

attributeId
required
string
Examples:
  • presentValue - The Present Value
  • itemReference - The Fully Qualified reference
metasysEnum: attributeEnumSet

The attribute to read.

The acceptable values for this parameter come from the attributeEnumSet enumeration. Only the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) is accepted. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

query Parameters
includeSchema
boolean

Set this parameter to true to include a schema in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/attributes/presentValue?includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example
{
  • "item": {
    },
  • "condition": {
    },
  • "schema": {
    }
}

List commands

Returns a payload that lists all of the commands that an object supports. Each command entry has an invokeUrl property, which is the URL needed to invoke the command. In addition, each command entry has a commandBodySchema property, which is a JSON schema that describes the acceptable payload for the command. Commands are invoked using the HTTP method PUT along with the invokeUrl and acceptable body.

Note: Some objects, such as multi-state values (MV) and binary values (BV), may list a command that has a commandSet property and a property named aggregateCommand with a value of true instead of invokeUrl. This commandSet lists one or more commands. This entry is not a true command but rather provides a hint to graphical user interfaces on how they may want to group the commands of the commandSet under one command name. For example, an MV object lists a command with the identifier commandIdEnumSet.adjustCommand. This is not an actual command on an MV. Instead the actual commands that could be used to present this command in a UI are listed in the commandSet and they have identifiers like commandIdEnumSet.multistate0Command. The Metasys User Interface displays all of these commands as a single adjust command with the titles of the individual commands as the parameter to send.

Licensing Restrictions

Requires Monitoring and Commanding API license.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/commands \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example
{
  • "self": "https://{hostname}/api/v5/objects/960534d2-7df5-5ed8-884c-164e7a2f280a/commands",
  • "items": [
    ],
  • "effectivePermissions": {
    }
}

Send command

Used to send a command to an object. The payloads of commands differ, but they share some similarities. To learn the specifics of the commands of an object use List commands.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

commandId
required
string
Example: adjustCommand
metasysEnum: commandIdEnumSet

The identifier of the command to send.

The acceptable values for this parameter come from the commandIdEnumSet enumeration. It is acceptable to use the short name of the command identifier (for example, adjustCommand instead of commandIdEnumSet.adjustCommand) because the enumeration set is known from context. Find the definition of commandIdEnumSet at the relative URL of /schemas/enums/commandIdEnumSet.

See also:

Request Body schema: application/json
required

The body of a command is defined by the commandBodySchema. The commandBodySchema is a property of every command returned by the List commands operation.

priority
string (write-priority-enum-set)
Enum: "writePriorityEnumSet.priorityNone" "writePriorityEnumSet.priorityManualEmergency" "writePriorityEnumSet.priorityFireApplications" "writePriorityEnumSet.priority3" "writePriorityEnumSet.priority4" "writePriorityEnumSet.priorityCriticalEquipment" "writePriorityEnumSet.priorityMinimumOnOff" "writePriorityEnumSet.priorityHeavyEquipDelay" "writePriorityEnumSet.priorityOperatorOverride" "writePriorityEnumSet.priority9" "writePriorityEnumSet.priority10" "writePriorityEnumSet.priorityDemandLimiting" "writePriorityEnumSet.priority12" "writePriorityEnumSet.priorityLoadRolling" "writePriorityEnumSet.priority14" "writePriorityEnumSet.prioritySchedulingOst" "writePriorityEnumSet.priorityDefault"
metasysType: enum
metasysEnum: writePriorityEnumSet
parameters
Array of any >= 0 items
annotation
string

Responses

Request samples

Content type
application/json
Example

This body is used with the adjust command of an Analog Value (AV). It sends the value 72.5 along with an annotation about why the command was invoked. The URL for this command is /objects/{objectId}/commands/adjustCommand

{
  • "parameters": [
    ],
  • "annotation": "Increase the set point to make it warmer."
}

Response samples

Content type
application/vnd.metasysapi.v5+json
"Success"

List supported child types

Many objects support nested objects. The obvious examples of this are folder objects and device objects. Less obvious examples include objects like analog value and multi-state value objects (which can have child objects like integrations). This operation lists the types of objects that can be created under an object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/supportedChildTypes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

The supported child types of a folder.

[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

List object equipment points

Retrieves all equipment points mapped to attributes of this object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "shortName"
Enum: "category" "-category" "equipmentName" "-equipmentName" "isDisplayData" "-isDisplayData" "shortName" "-shortName"
Example: sort=shortName

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/points?page=1&pageSize=100&sort=shortName' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

Batch operations

This operation is used to invoke multiple operations in a single HTTP request. Often a batch request is more efficient than sending each individual operation in its own HTTP request.

In this version of the API, the only objects related operation that can be used in a batch is Get attribute value.

If this operation is invoked with a valid METASYS-CALL-ASYNC header it will cause a temporary subscription to be created for the attributes in the request and rather than returning any values, the current values and any updates to the attributes will be sent over the specified stream.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Request Body schema: application/json
required
method
required
string
Enum: "GET" "PATCH"

The HTTP method to use for each request. This property is restricted to GET for this version of the API since Get attribute value is the only operation supported in a batch.

(INTERNAL) The method PATCH is also supported for internal operations.

required
Array of objects non-empty

A collection of entries that represent the operations to invoke.

Responses

Request samples

Content type
application/json

This example shows a request body that will read the presentValue and status from 3 different objects using sequential numbers as request identifiers.

This example shows the use of sequential numeric values used as request identifiers but any unique strings can be used.

{
  • "method": "GET",
  • "requests": [
    ]
}

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

This example shows the response to a read multiple attributes request. Each operation response is uniquely identified by the corresponding identifier (id) from the request.

{
  • "responses": [
    ]
}

schemas

A collection of JSON schemas for describing enumerations and object types.

Get enumeration

This operation retrieves the specified enumeration as a JSON schema. The path of this operation appears in several schemas of object payloads.

To get a list of all enumerations fetch the enumerationSetNamesEnumSet:

GET /schemas/enums/enumerationSetNamesEnumSet

See also:

Authorizations:
Bearer-Authentication
path Parameters
enumId
required
string
Examples:
  • writePriorityEnumSet - The write priority enumeration
  • displayPrecisionEnumSet - The display precision enumeration
  • enumerationSetNamesEnumSet - The set of all sets
metasysType: enum

The enumeration to retrieve.

The acceptable values for this parameter come from the enumerationSetNamesEnumSet enumeration. It is acceptable to use the short name of the value (for example, writePriorityEnumSet instead of enumerationSetNamesEnumSet.writePriorityEnumSet) because the enumeration set is known from context. Find the definition of enumerationSetNamesEnumSet at the relative URL of /schemas/enums/enumerationSetNamesEnumSet.

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/schemas/enums/writePriorityEnumSet \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example
{
  • "$schema": "http://json-schema.org/draft-07/schema#",
  • "title": "Write Priority",
  • "$id": "https://{hostname}/api/v5/schemas/enums/writePriorityEnumSet",
  • "setId": 1,
  • "oneOf": [
    ]
}

Get object type schema

This endpoint retrieves a schema for a specific objectType. The schema describes the properties that can be set when creating an object of the specific type.

Authorizations:
Bearer-Authentication
path Parameters
objectType
required
string
Examples:
  • objectTypeEnumSet.avClass - AV
  • objectTypeEnumSet.bvClass - BV
  • objectTypeEnumSet.mvClass - MV
metasysEnum: objectTypeEnumSet

The type of object

The acceptable values for this parameter come from the objectTypeEnumSet enumeration. It is acceptable to use the short name of the object type (for example, avClass instead of objectTypeEnumSet.avClass) because the enumeration set is known from context. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

query Parameters
parentId
required
string
Example: parentId=2993aed9-5765-5641-889c-40ec968c8a82

The object under which this new object will be created.

extendedProperty
string
Examples:
  • extendedProperty=attributeEnumSet.presentValue - Present Value
  • extendedProperty=attributeEnumSet.reliability - Reliability
metasysEnum: attributeEnumSet

The attribute to extend.

Indicates which attribute of the parent object the extension should be linked to. Used only for extension objects (like alarm extensions).

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/schemas/objectTypes/objectTypeEnumSet.avClass?parentId=2993aed9-5765-5641-889c-40ec968c8a82&extendedProperty=attributeEnumSet.presentValue' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

This schema describes the properties that can be configured when creating an object of the type avClass.

{
  • "schema": {
    },
  • "views": [
    ]
}

spaces

Operations on space-related resources.

Get spaces served by a network device

Retrieves the collection of spaces served by the specified network device. A space is served by a network device when any equipment instance serving the space defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/spaces?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of spaces.

{}

Get spaces served by an equipment instance

Retrieves the collection of spaces served by the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/spaces?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of spaces.

{}

Get spaces

Retrieves a collection of spaces.

Authorizations:
Bearer-Authentication
query Parameters
type
string
Example: type=spaceTypesEnumSet.building
metasysType: enum
metasysEnum: spaceTypesEnumSet

Type of space to return.

The acceptable values for this parameter come from the spaceTypesEnumSet enumeration. Only the long name of the space type (for example, spaceTypesEnumSet.building instead of building) is accepted. Find the definition of spaceTypesEnumSet at the relative URL of /schemas/enums/spaceTypesEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/spaces?type=spaceTypesEnumSet.building&page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of spaces.

{}

Get a single space

Retrieves the specified space.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of spaces.

{}

Get space children

Retrieves the collection of spaces that are located within the specified space.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/spaces?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

A page of spaces.

{}

streaming

Your Metasys system works continuously: sensors report current conditions, algorithms make adjustments, and alarms alert operators to potential issues. Streaming is how the Metasys API provides access to these events using the HTML standard server-sent events (SSE). For further information, refer to Mozilla developer guide. In this document, Streaming typically refers to the Metasys feature and stream refers to the concept of the HTTP connection and the flow of data.

Per the standard, a server-sent event usually contains three components, separated by newline, with the last component having a second newline to mark the end of the event.

id: <event id>\n
event: <event type>\n
data: <event data>\n\n
Line Prefix Explanation
id ordering id to enable the "pick up where you left off" reconnection
event message type
data message payload as a JSON string

Example:

id: b6d184ee-e137-44aa-b9b1-14bc704cd25d:1\n
event: hello\n
data: b6d184ee-e137-44aa-b9b1-14bc704cd25d\n\n

Getting Started

To get started, you first need a client. There are SSE clients available in many languages.

Begin by getting a stream. Only one stream is needed regardless of the number of subscriptions you later create. As explained in the documentation for getting a stream, the first event, hello, is a special event because the data field contains your stream ID.

Some operations support the METASYS-SUBSCRIBE header which transforms them from being a single request/response operations into a streaming subscription. The value of the header is the stream ID from the data field of the hello event described above. As an example, refer to the Get Activities operation for more details about this technique. This technique does not apply to every operation. See each operation's description to understand its Streaming capability.

Not all event data is currently exposed by Streaming. Future versions of the API will add further Streaming capabilities.

Streaming Connection Maintenance

There are a few behaviors to be aware of if you want your stream to work beyond the lifetime of the access token used to get your stream.

Keep Events Flowing After Initial Access Token Expiration

Recall that your access token has an expiration time. To keep the stream longer than the lifetime of that access token, be sure to refresh your token just as you would when using non-Streaming portions of the API. Not only will you get a fresh token to use, but internally, your stream expirations are updated to match the expiration time of the new token.

Reconnect and Using the Current Access Token in Reconnect Requests

The server-sent events standard has a provision for reconnecting a lost connection. Call the same get a stream operation but also add the Last-Event-Id header with the id of the last event received. Most clients handle this for you. Metasys continues to buffer events for at least thirty seconds after the connection failure is detected, so you can resume streams that experienced brief outages. If Metasys has cleaned up your buffer or cannot find that id in the recently sent buffer, you will get a 204 response per the SSE specification. Because your existing stream is not resumable, your Last-Event-Id is no longer valid. The recovery path is to start anew by calling get a stream without the Last-Event-Id and subscribe again to data of interest.

One critical aspect of reconnect is ensuring that the reconnect request is done with the current access token. As covered by get a stream, Streaming lets you specify the token in either the Authorization header or query string. This flexibility accommodates a variety of clients. For example, the web browser client, EventSource, does not provide access to request headers, so you have to use the query string.

For EventSource, this however poses an issue because the reconnect attempt will be done against the original URL which has a potentially outdated access token embedded in the query string. For that reason, if you want to use a JavaScript client, consider using the open source EventSource component. The Metasys User Interface (MUI) employs this library to workaround the limitation of the browser's EventSource . When using it, use the Authorization header instead. Keep the options object passed to the constructor so you can update the Authorization property when you refresh your access token.

Assuming:

  1. Your access token is in variable accessToken
  2. Variable streamingUrl is the URL for get a stream
const eventSourceOptions = {
  headers: {
    Authorization: `Bearer ${accessToken}`,
  },
};

const eventSource = new $window.EventSourcePolyfill(
  streamingUrl,
  eventSourceOptions
);

Before token expiration:

  1. Get a refreshed token. Behind the scenes this also refreshes you stream expirations.
  2. Modify eventSourceOptions with new token like example below
eventSourceOptions.headers.Authorization = `Bearer ${newToken}`;

Tips For Other Client Libraries

SSE clients exist in many languages. Inclusion in this section is not an endorsement; however, if you chose one of these clients, these tips may prove useful for ensuring the current token is used for reconnect.

C# - 3ventic EventSource

When using the 3ventic EventSource for C# you will need to use Reflection to update Uri which is a private field within the EventSource that contains the location to get a stream with the access token embedded in the query string.

public static void SetField(Object obj, String fieldName, object value)
{
    Type type = obj.GetType();
    FieldInfo field = type.GetField(
        fieldName,
        BindingFlags.NonPublic | BindingFlags.Instance
    );
    field.SetValue(obj, value);
}

// example usage
Reflector.SetField(eventSource, "Uri", uriWithCurrentToken);

C# - LaunchDarkly EventSource

When using the LaunchDarkly EventSource for C# you will not call the Reset method to attempt a reconnect. Instead, dispose of the EventSource and then create a new instance, passing the the LastEventId from the last message and the URL to get a stream with a current access token embedded as a query string parameter.

Streaming Events

The following are types of events sent by Streaming along with example data payloads for each:

  • hello - Indicates Streaming connection was successful.

    Example Data Payload 
    "b6d184ee-e137-44aa-b9b1-14bc704cd25d"

  • heartbeat - Indicates Streaming connection is alive.

    Example Data Payload 
    "2021-02-16T16:21:10.23Z"

Get a stream

Opens or reconnects a Server Sent Event stream which is a prerequisite for subscribing to any dynamic updates

Authorizations:
Bearer-AuthenticationAPI-Key-Authentication
header Parameters
Last-Event-Id
string
Example: b6d184ee-e137-44aa-b9b1-14bc704cd25d:5

Providing the ID of the last event received enables a briefly broken stream to be resumed

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/stream \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Last-Event-Id: b6d184ee-e137-44aa-b9b1-14bc704cd25d:5'

time series

This section describes the operations you can perform on time series sample data.

Origin of Time Series data

The Metasys system has two locations from which time series samples can be retrieved. The first is from the trend or log object, itself. Each object on the Metasys site whose responsibility is to generate samples will have its own buffer to store them. When samples are retrieved from the objects endpoints, they will be retrieved from their respective buffers. Time series operations that work with a buffer will include "(buffer)" in their summary.

The second location is from the repository. As samples are collected in the trend or log objects themselves, those objects (if configured and enabled) have the ability to forward that information to a repository. The repository is the location on the LAN (Local Area Network) that can receive and store historical data from one to many Metasys sources. Samples retrieved from the timeSeries endpoint are retrieved from the particular Metasys device's repository. Time series operations that work with the repository will include "(repository)" in their summary.

Subscription Streaming Events

Clients may subscribe to Objects and Network Devices streaming events. A subscription is established by providing a METASYS-SUBSCRIBE header on a GET operation of the samples resource under either the objects resource paths.

Events

The following events (with accompanying examples) are available for samples:

  • timeSeries.subscription.established - Indicates when a subscription has been established for objects samples.
subscriptionIds
required
Array of strings

List of all active subscriptionIds for this stream

message
required
string

The display string message that indicates that the subscription has been established successfully.

required
Array of objects

The collection of available items.

total
required
integer

The total number of items in the collection

{
  • "subscriptionIds": [
    ],
  • "message": "Sample subscription successful",
  • "items": [
    ],
  • "total": 1
}
  • timeSeries.subscription.cancelled - Indicates when a subscription has been cancelled for objects samples.
subscriptionIds
required
Array of strings

List of all subscriptionIds for this stream which have been cancelled.

message
required
string

The display string message that correlates to the subscriptions that have been cancelled.

{
  • "subscriptionIds": [
    ],
  • "message": "Sample subscription cancelled"
}
  • timeSeries.error - Indicates an error occurred with regards to an active samples subscription.
subscriptionIds
required
Array of strings

List of all subscription Ids for this stream for whom errors have been generated.

message
required
string

The display string message that provides information about the errors that have been generated.

required
Array of objects

The collection of available error items.

total
required
integer

The total number of items in the collection

{
  • "subscriptionIds": [
    ],
  • "message": "There was an issue in retrieving samples",
  • "items": [
    ],
  • "total": 1
}
  • timeSeries.samples.update - Indicates new samples have been generated. Sample updates from multiple objects and attributes can be contained in a single event (each designated by their sampledByObjectId, sampledObjectId and attribute properties).
subscriptionIds
required
Array of strings

List of all subscription IDs that the updates apply to for this stream

total
required
integer

The total number of items in the collection

required
Array of objects

A collection of sample update information for the subscribed data with additional identifying information for the objects and attributes the updates apply to.

{
  • "subscriptionIds": [
    ],
  • "total": 2,
  • "items": [
    ]
}
  • timeSeries.heartbeat - Indicates that time series subscription(s) are still alive.
currentTime
required
string <date-time>

Current server time in ISO8601 format

subscriptionIds
required
Array of strings

List of all active subscriptionIds for this stream

{
  • "currentTime": "2022-01-01T00:00:00Z",
  • "subscriptionIds": [
    ]
}

Metasys-Call-Async Streaming Events

Clients may subscribe to Objects Samples Response streaming events. A subscription is established by providing a METASYS-CALL-ASYNC header on a GET operation of the samples resource under either the objects resource paths or POST operation of the samples resource under batch operation of times buffer. The following events (with accompanying examples) are available for samples:

Events

The following events (with accompanying examples) are available for async samples:

  • timeSeries.samples.stream.started - Indicates when a subscription has been established for objects samples response.
subscriptionIds
required
Array of strings

List of all active subscriptionIds for this stream

message
required
string

The display string message that indicates that the subscription has been established successfully.

required
Array of objects

The collection of available items.

total
required
integer

The total number of items in the collection

{
  • "subscriptionIds": [
    ],
  • "message": "Sample subscription successful",
  • "items": [
    ],
  • "total": 1
}
  • timeSeries.samples.stream.error - Indicates an error occurred with regards to an active samples response subscription.
subscriptionIds
required
Array of strings

List of all subscriptionIds for this async stream which an error has been generated,

message
required
string

The display string message that correlates to an error has occurred in async stream.

{
  • "subscriptionIds": [
    ],
  • "message": "An error occurred while streaming samples."
}
  • timeSeries.samples.stream.data - Indicates samples responses for each request. Samples from multiple objects and attributes can be contained in a single event (each designated by their sampledByObjectId, sampledObjectId and attribute properties).
subscriptionIds
required
Array of strings

List of all subscription IDs that the updates apply to for this stream

total
required
integer

The total number of items in the collection

required
Array of objects

A collection of sample update information for the subscribed data with additional identifying information for the objects and attributes the updates apply to.

{
  • "subscriptionIds": [
    ],
  • "total": 2,
  • "items": [
    ]
}
  • timeSeries.samples.stream.completed - Indicates that a streaming samples response has completed successfully.
subscriptionIds
required
Array of strings

List of all subscriptionIds for this async stream which has been completed.

message
required
string

The display string message that correlates to the completion of an async samples response.

{
  • "subscriptionIds": [
    ],
  • "message": "Samples stream response completed"
}

List all time series (repository)

The operation retrieves a collection of resources for which historical time series data exists. This operation uses the time series repository as its source of truth. It may contain data for objects that no longer actually exist on the site. This operation never considers time series that exist exclusively in buffers on devices and that are not configured to forward their samples to the repository.

Authorizations:
Bearer-Authentication
query Parameters
searchString
string
Examples:
  • searchString=AV - Find all references with `AV`` in them
  • searchString=Programming - Find all references with `Programming`` in them

Filter results by finding objects with an itemReference that contains the searchString as a substring.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 2000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "itemReference"
Enum: "itemReference" "-itemReference"
Example: sort=itemReference

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/timeSeries?searchString=AV&page=1&pageSize=100&sort=itemReference' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
{}

List trended attributes (buffer)

Retrieves a collection of attributes under the specified object for which samples are available in their respective local sample buffers.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get objects trended attributes response.

{}

List trended attributes (repository)

Retrieves a collection of attributes for the specified object for which samples are available in the trend repository.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request GET \
  --url https://metasys-server.example.com/api/v5/timeSeries/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json

Get trended attributes from the trend repository response.

{}

Get attribute samples (buffer)

Retrieves a collection of samples from the object's local sample buffer for the specified object attribute during a particular date and time range.

If the METASYS-SUBSCRIBE header is provided, then an event subscription will be created which will include the events described in Time Series.

Note: The parent endpoint /objects/{objectId}/trendedAttributes/{attributeId} is not currently supported.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

attributeId
required
string
Example: presentValue
metasysType: enum
metasysEnum: attributeEnumSet

The identifier of the attribute.

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

query Parameters
startSampleTime
string <date-time>
Example: startSampleTime=2020-05-12T16:46:47Z

The date and time representing the earliest sample to return.

endSampleTime
string <date-time>
Example: endSampleTime=2021-01-19T18:13:58.007Z

The date and time representing the latest sample to return.

sort
string
Default: "-sampleTime"
Enum: "sampleTime" "-sampleTime"
Example: sort=sampleTime

The criteria to use when sorting results (see rules).

sampledById
Array of strings
Examples:
  • sampledById=4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7&sampledById=4ffd6456-3d36-5e08-8efb-ba91d4a81126 - Multiple identifiers
  • sampledById=4ffd6456-3d36-5e08-8efb-ba91d4a81126 - Single identifier

Filter samples by objects by supplying one or more sampledById values.

An attribute may have multiple objects sampling it. Use this parameter to include samples only from a specific object or set of objects. If no value is given for this parameter, then the response will contain samples from all of the objects sampling this attribute.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes/presentValue/samples?startSampleTime=2020-05-12T16%3A46%3A47Z&endSampleTime=2021-01-19T18%3A13%3A58.007Z&sort=sampleTime&sampledById=4cc1cb52-b2db-4129-ac93-0d4a5e6dd6d7&sampledById=4ffd6456-3d36-5e08-8efb-ba91d4a81126' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

Get samples from trend object response containing only analog values.

{}

Get attribute samples (repository)

Retrieves a collection of samples from the trend repository for the specified object attribute during a particular date and time range. Note: The parent endpoint /timeSeries/{objectId}/trendedAttributes/{attributeId} is not currently supported.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

attributeId
required
string
Example: presentValue
metasysType: enum
metasysEnum: attributeEnumSet

The identifier of the attribute.

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

query Parameters
startSampleTime
string <date-time>
Example: startSampleTime=2020-05-12T16:46:47Z

The date and time representing the earliest sample to return.

endSampleTime
string <date-time>
Example: endSampleTime=2021-01-19T18:13:58.007Z

The date and time representing the latest sample to return.

page
integer >= 1
Default: 1
Example: page=5

The page of the collection being requested.

pageSize
integer <= 20000
Default: 500
Example: pageSize=500

The requested number of items in the response.

sort
string
Default: "-sampleTime"
Enum: "sampleTime" "-sampleTime"
Example: sort=sampleTime

The criteria to use when sorting results. Please refer to default sorting rules for general guidelines.

Responses

Request samples 

curl --request GET \
  --url 'https://metasys-server.example.com/api/v5/timeSeries/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes/presentValue/samples?startSampleTime=2020-05-12T16%3A46%3A47Z&endSampleTime=2021-01-19T18%3A13%3A58.007Z&page=5&pageSize=500&sort=sampleTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v5+json
Example

Get samples from the trend repository response containing only analog values.

{}

Batch operations for time series (repository)

This operation is used to invoke multiple time series operations in a single HTTP request. Often a batch request is more efficient than sending each individual operation in its own HTTP request. In this version of the API, the only time series related operations that can be used in this batch API are Get object samples (repository). This request is for fetching repository data (as opposed to fetching data from the buffer).

Authorizations:
Bearer-Authentication
Request Body schema: application/json
required
method
required
string
Value: "GET"

The HTTP method to use for each request. This property is restricted to GET for this version of the API.

required
Array of objects (Request object) non-empty

A collection of entries that represent the operations to invoke.

Responses

Request samples

Content type
application/json

This example shows a request body that will read samples for the presentValue and enabled attributes for object c550095d-ee4c-4314-b415-b0577e383ee9 and for the presentValue attribute of object c82d160b-884c-5eac-bad4-89754f0069e0.

{
  • "method": "GET",
  • "requests": [
    ]
}

Response samples

Content type
application/vnd.metasysapi.v5+json

The response to a batch request to fetch samples for three different attributes.

{}

Create samples subscription (buffer)

Creates a subscription to trend buffer samples

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

Request Body schema: application/json
required

New streaming subscription for time series data.

Array of objects

Collection of items to sign up for.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Update samples subscription (buffer)

Replaces an existing subscription to trend buffer samples.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Request Body schema: application/json
required

Streaming subscription for time series data.

Array of objects

Collection of items to sign up for.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Delete trend samples subscription

Deletes a subscription to trend samples.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Responses

Request samples 

curl --request DELETE \
  --url https://metasys-server.example.com/api/v5/timeSeries/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'