Skip to main content
Skip table of contents

Attribute Subscription Resource

Attribute subscription resource is used to retrieve attribute values and updates to those values sequentially through a subscription.

Attribute Subscription Resource is introduced in Structure 6.0. When working with an older version, use Value Resource.

To learn more about attributes, see Loading Attribute Values.

Subscriptions

A subscription represents an interest of a client code in a set of attributes for a set of rows in a particular forest. Just like when loading attributes through Value Resource, in order to create a subscription, you need:

  • A forest specification (forestSpec) for the displayed forest.
  • A list of row IDs for which the values should be loaded. Row IDs can be retrieved from Forest Resource before calling Value Resource.
  • A list of attribute specifications. Some examples are given below and in the documentation for Value Resource.

The chosen rows and attributes of interest are called a "window". The subscription server keeps track of registered subscriptions and corresponding windows, and, upon requests, calculates the updated data for a window and sends the updates back to the client.

Attribute subscription is the preferred way to continuously receive attribute values. For a one-off download, it's better to use Value Resource.

Base URL

Base URL for Attribute Subscription Resource is: $baseUrl/rest/structure/2.0/attribute/subscription

In the following documentation we will simply write /attribute/subscription meaning the full base URL above.

Common Parameters and Data Structures

There are a number of parameters that are used repeatedly in multiple methods in the Attribute Subscription Resource.

Input Query Parameters

These are passed as a part of URL. Neither of them are required.

Parameter NameTypeDefaultMeaning
valuesUpdateBooleanfalseIndicates whether a client desires to receive the updated values for the current or updated window. This typically implies that a request to load these values will be executed.
valuesTimeoutLong1000ms

Indicates the maximum time (in milliseconds) the server will wait for the values to be calculated before responding to the client. Applies only if valuesUpdate is true.

The default can be adjusted through Advanced Configuration and Dark Features.

signatureInteger0

Together, signature and version define the last point of synchronization with the updates from the server.

In the first request, the client should use zeros or not use them at all. Each successful response will include an updated signature and version, which client code should use the next time in order to get only the values that have changed.

versionInteger0

Data Structure: SubscriptionWindow

The SubscriptionWindow data structure represents a subscription window.

FieldTypeMeaning
forestSpecObject: a forest specification, the same as in Forest ResourceDefines the forest for which the values will be loaded.
rowsArray of Long numbersDefines a list of rows to be loaded.
attributesArray of Objects: AttributeSpecDefines a list of attributes to be loaded.


Example:

CODE
{
  "forestSpec": { "structureId": 1 },
  "rows": [ 10, 15, 1, 27, 1001 ],
  "attributes": [
    { "id": "summary", "format": "text" },
    { "id": "key", "format": "html" },
    {
      "id": "progress",
      "format": "number",
      "params": {
        "basedOn": "timetracking",
        "resolvedComplete": true,
        "weightBy": "equal"
      }
    }
  ]
}

Data Structure: SubscriptionData

The SubscriptionData data structure is sent back from most of the REST calls to the Attribute Subscription Resource.

FieldTypeMeaning
idIntegerThe unique ID of the subscription.
windowSubscriptionWindowThe current (updated) window for the subscription.
valuesUpdateSubscriptionUpdateAn update for the current subscription.

Data Structure: SubscriptionUpdate

A subscription update is returned as a part of SubscriptionData structure and carries the new values, versioning information, error information and loading progress information.

This structure is also used in the Poll Resource.


FieldTypeMeaning
idIntegerThe unique ID of the subscription.
fullBooleanIf true, this is a "full" or "total" update, meaning that all old values are obsolete. If false, it is an incremental update and includes only the updated values.
fromVersionRestVersionContains signature and version that were used to request the update.
versionRestVersionContains signature and version that should be used to request the next update.
dataArray of ObjectsEach object represents values for a particular attribute.
data[i].attributeAttributeSpecDescribes the attribute for which the values are provided.
data[i].valuesObjectA map from row IDs (represented as strings) to the attribute values. A value may take multiple forms – it could be a number, a text, a boolean, an array or an object.
data[i].outdatedArray of LongsOptional field that lists the values which are known to contain outdated values. (But the values are provided all the same, so that the client can show something while the updated values are being calculated.)
stillLoadingBooleanIf true, not all of the requested values have been loaded. The client can retry the request some time later.
inaccessibleRowsArray of LongsOptional field that lists all requested rows that are not accessible by the user (for any reason). The client code should not continue requesting them.
errorStructureErrorAn object containing error code and other diagnostics in case of a problem.
attributeErrorsA list of ObjectsAn optional list of attribute-specific errors.

Resource Methods

Create Subscription

CODE
POST /attribute/subscription

Query parameters

valuesUpdatevaluesTimeoutAllow immediately loading some values for the created subscription.
Input dataSubscriptionWindowPassed as the request body, the window defines the subscription parameters.
ResponseSubscriptionDataContains the ID of the newly created subscription, the used window, and some values if they were requested.

Retrieve Subscription or Values

CODE
GET /attribute/subscription/ID
Path parametersIDIdentifies the subscription by ID.

Query parameters

valuesUpdatevaluesTimeoutAllow immediately loading some values for the created subscription.

signature, versionIdentify the previous version of the values that the client has seen to get incremental updates.

skipLoadingA Boolean parameter: if true, then only the already calculated values will be loaded, without requesting the attribute subsystem to reload the values in the window.
ResponseSubscriptionDataContains all the subscription data and value updates if they were requested.

Update Subscription

Used to completely change the subscription's window.

CODE
PUT /attribute/subscription/ID
Path parametersIDIdentifies the subscription by ID.

Query parameters

valuesUpdatevaluesTimeoutAllow immediately loading some values for the updated subscription.

signature, versionIdentify the previous version of the values that the client has seen to get incremental updates.
Input dataSubscriptionWindowThe updated subscription window.
ResponseSubscriptionDataContains all the subscription data and value updates if they were requested.

Patch Subscription

Used to partially change the subscription's window. Only the fields mentioned in the input SubscriptionWindow object will be updated. 

CODE
POST /attribute/subscription/ID/patch
Path parametersIDIdentifies the subscription by ID.

Query parameters

valuesUpdatevaluesTimeoutAllow immediately loading some values for the updated subscription.

signature, versionIdentify the previous version of the values that the client has seen to get incremental updates.
Input dataSubscriptionWindowThe object with the parts of the subscription window that need to be updated.
ResponseSubscriptionDataContains all the subscription data and value updates if they were requested.

Delete Subscription

CODE
DELETE /attribute/subscription/ID
Path parametersIDIdentifies the subscription by ID.
ResponseHTTP 200Simple response with no data.

User Access

When a subscription is created, it is attached to the current user. Only this user will have access to the subscription.

Subscription Expiration and Caching

A subscription is considered a transient, cache-like object. It may be removed from the server at any time, even if the user has not requested it.

When a request is made about a subscription that no longer exists, the server responds with HTTP 404 error and an object describing the error in detail. The client code may decide to re-create a subscription at that point.




JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.