Create subscriptions

Create one or more subscriptions that can be used to listen for changes in data points for a set of time series.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json
required

The subscriptions to create.

required
Array of objects = 1 items
Subscription definitions. A subscription may be configured explicitly with a list of time series, or it may be a configured dynamically through a filter. The subscription cannot change type later.

An explicit list must be manually updated by the user, while a filter will be updated automatically whenever a time series is added/deleted/updated (eventually consistent).

The filter subscriptions uses the same syntax as advanced filters in the Filter time series endpoint, with two exceptions: The field is named `filter` instead of `advancedFilter`, and we do not support the `search` LeafFilter.

Advanced filtering

The filter field lets you create complex filtering expressions that combine simple operations, such as equals, prefix, and exists, by using the Boolean operators and, or, and not. Filtering applies to basic fields as well as metadata. See the advancedFilter syntax in the request example.

Supported leaf filters

Leaf filter Supported fields Description and example
containsAll Array type fields Only includes results which contain all of the specified values.
{"containsAll": {"property": ["property"], "values": [1, 2, 3]}}
containsAny Array type fields Only includes results which contain at least one of the specified values.
{"containsAny": {"property": ["property"], "values": [1, 2, 3]}}
equals Non-array type fields Only includes results that are equal to the specified value.
{"equals": {"property": ["property"], "value": "example"}}
exists All fields Only includes results where the specified property exists (has a value).
{"exists": {"property": ["property"]}}
in Non-array type fields Only includes results that are equal to one of the specified values.
{"in": {"property": ["property"], "values": [1, 2, 3]}}
prefix String type fields Only includes results which start with the specified text.
{"prefix": {"property": ["property"], "value": "example"}}
range Non-array type fields Only includes results that fall within the specified range.
{"range": {"property": ["property"], "gt": 1, "lte": 5}}
Supported operators: gt, lt, gte, lte

Supported properties

Property Type
["description"] string
["externalId"] string
["metadata", "<someCustomKey>"] string
["name"] string
["unit"] string
["unitExternalId"] string
["unitQuantity"] string
["instanceId", "space"] string
["instanceId", "externalId"] string
["assetId"] number
["assetRootId"] number
["createdTime"] number
["dataSetId"] number
["id"] number
["lastUpdatedTime"] number
["isStep"] Boolean
["isString"] Boolean

Limits

  • Filter query max depth: 10.
  • Filter query max number of clauses: 100.
  • and and or clauses must have at least one element (and at most 99, since each element counts towards the total clause limit, and so does the and/or clause itself).
  • The property array of each leaf filter has the following limitations:
    • Number of elements in the array is 1 or 2.
    • Elements must not be null or blank.
    • Each element max length is 256 characters.
    • The property array must match one of the existing properties (static top-level property or dynamic metadata property).
  • containsAll, containsAny, and in filter values array size must be in the range [1, 100].
  • containsAll, containsAny, and in filter values array must contain elements of number or string type (matching the type of the given property).
  • range filter must have at lest one of gt, gte, lt, lte attributes. But gt is mutually exclusive to gte, while lt is mutually exclusive to lte.
  • gt, gte, lt, lte in the range filter must be of number or string type (matching the type of the given property).
  • The maximum length of the value of a leaf filter that is applied to a string property is 256.
Responses
201

A list of subscriptions that were created.

post/timeseries/subscriptions
Request samples
application/json
{
  • "items": [
    • {
      }
    ]
}
Response samples
application/json
{
  • "items": [
    • {
      }
    ]
}