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 Name	Type	Default	Meaning
`valuesUpdate`	Boolean	`false`	Indicates 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.
`valuesTimeout`	Long	`1000ms`	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.
`signature`	Integer	`0`	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.
`version`	Integer	`0`

Data Structure: `SubscriptionWindow`

The SubscriptionWindow data structure represents a subscription window.

Field	Type	Meaning
`forestSpec`	Object: a forest specification, the same as in Forest Resource	Defines the forest for which the values will be loaded.
`rows`	Array of Long numbers	Defines a list of rows to be loaded.
`attributes`	Array of Objects: AttributeSpec	Defines a list of attributes to be loaded.

Example:

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

Field	Type	Meaning
`id`	Integer	The unique ID of the subscription.
`window`	`SubscriptionWindow`	The current (updated) window for the subscription.
`valuesUpdate`	`SubscriptionUpdate`	An 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.

Field	Type	Meaning
`id`	Integer	The unique ID of the subscription.
`full`	Boolean	If 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.
`fromVersion`	`RestVersion`	Contains signature and version that were used to request the update.
`version`	`RestVersion`	Contains signature and version that should be used to request the next update.
`data`	Array of Objects	Each object represents values for a particular attribute.
`data[i].attribute`	AttributeSpec	Describes the attribute for which the values are provided.
`data[i].values`	Object	A 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].outdated`	Array of Longs	Optional 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.)
`stillLoading`	Boolean	If true, not all of the requested values have been loaded. The client can retry the request some time later.
`inaccessibleRows`	Array of Longs	Optional field that lists all requested rows that are not accessible by the user (for any reason). The client code should not continue requesting them.
`error`	`StructureError`	An object containing error code and other diagnostics in case of a problem.
`attributeErrors`	A list of Objects	An optional list of attribute-specific errors.

Resource Methods

Create Subscription

POST /attribute/subscription

Query parameters	`valuesUpdate`, `valuesTimeout`	Allow immediately loading some values for the created subscription.
Input data	`SubscriptionWindow`	Passed as the request body, the window defines the subscription parameters.
Response	`SubscriptionData`	Contains the ID of the newly created subscription, the used window, and some values if they were requested.

Retrieve Subscription or Values

GET /attribute/subscription/ID

Path parameters	ID	Identifies the subscription by ID.
Query parameters	`valuesUpdate`, `valuesTimeout`	Allow immediately loading some values for the created subscription.
	`signature`, `version`	Identify the previous version of the values that the client has seen to get incremental updates.
	`skipLoading`	A 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.
Response	`SubscriptionData`	Contains all the subscription data and value updates if they were requested.

Update Subscription

Used to completely change the subscription's window.

PUT /attribute/subscription/ID

Path parameters	ID	Identifies the subscription by ID.
Query parameters	`valuesUpdate`, `valuesTimeout`	Allow immediately loading some values for the updated subscription.
	`signature`, `version`	Identify the previous version of the values that the client has seen to get incremental updates.
Input data	`SubscriptionWindow`	The updated subscription window.
Response	`SubscriptionData`	Contains 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.

POST /attribute/subscription/ID/patch

Path parameters	ID	Identifies the subscription by ID.
Query parameters	`valuesUpdate`, `valuesTimeout`	Allow immediately loading some values for the updated subscription.
	`signature`, `version`	Identify the previous version of the values that the client has seen to get incremental updates.
Input data	`SubscriptionWindow`	The object with the parts of the subscription window that need to be updated.
Response	`SubscriptionData`	Contains all the subscription data and value updates if they were requested.

Delete Subscription

DELETE /attribute/subscription/ID

Path parameters	ID	Identifies the subscription by ID.
Response	`HTTP 200`	Simple 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.