Index | Prev | Next

Subscribe

Subscribe creates and adds GetValue messages to a subscription. A subscription returns an initial value for each GetValue, and after that only for changes of value.

Subscriptions are private to the client session. Subscription names need only be unique to the client.

Request example

{

  "message" : "Subscribe",
  "name" : "SubscriptionName",
  "values" :
  [
       {
           "message" : "GetValue",
           "uid" : "identifier uniquely identifying
                    this specific GetValue",
           "node" : "slot:/nAnalyticTree/East",
           "data" : "definition:Some/Data/Definition",
           "tags" : ["hvac", "it"],
           "tagMode" : "all",
           "aggregation" : "max",
           "rollup" : "average",
           "interval" : "oneMinute",
       }
  ]
}

Request elements

Request element Value Description
message Subscribe Identifies the type of request being submitted.
name (of subscription) text Defines the subscription name. If the client does not already have a subscription by the given name, the system creates one.

Subscriptions are private to each session and only have to be unique in that context.
Values multiple Defines one or more GetValue message requests. See Values.

Values

Request element Value Description
message text Identifies the type of request being returned.
uid client string Provides a unique identifier (uid) for the GetValue string. There could be several GetValues for the same node and data, each with different options, such as tags. For this reason, a unique identifier is required.
Node or node (required) ORD (defaults to a relative ORD slot, which is resolved against the config space to which the Px view is assigned) Defines the ORD to the desired slot.
Definition or data (required) input ORD for data definition

Identifies the data definition (properties) associated with an input point (nAnalytics variable). No other input point directly contained by the same node can have the same data definition.

BFormats are allowed here.
Tags or tags (optional) tag text Defines or returns the tags used for the operation. The framework searches the data model tree for nodes that declare or inherit tags based on the Tag Mode setting.
Tag Mode or tagMode Any (default) or All Constrains the search to find nodes with one or more of the defined tags (Any) or requires that all tags be present to include the node (All).
Aggregation check box (if optional, and) drop-down list (property, defaults to First) or ORD parameter (aggregation=option)

If aggregation is not enabled in the binding/settings window, the aggregation value defined in the Data Definition applies to all chart bindings, reports and tables.

And returns the logical “and” of Boolean values.

Avg returns the statistical mean, which is determined by calculating the sum of all values and dividing by the number of values.

Count returns the total number or quantity of values in a combination. If you request this value on a binding in a PX view, the system counts the number of values based on the properties defined by the data source block and the algorithm’s Property Sheet.

First returns the first value in the combination.

Last returns the last value in the combination.

Max returns the highest value in the combination.

Median returns the value in the middle of a sorted combination—the number that separates the higher half from the lower half.

Min returns the lowest value in the combination.

Mode returns the statistically most frequently occurring number in the combination.

Or returns the logical “or” of Boolean values.

Range returns the statistical difference between the largest and smallest values in the combination.

Sum adds together all values in the combination resulting in a single value.

Load Factor returns the average value divided by peak value.

Std Dev returns the standard deviation of the values in the combination.

Rollup check box (if optional, and) drop-down list or ORD parameter (when configured in the data definition, defaults to First, when configured elsewhere, defaults to the value as defined in the Data Definition); rollup=option

If rollup is not enabled in the binding/settings window, the rollup value configured in the Data Definition applies to all chart bindings, reports and tables.

And returns the logical “and” of Boolean values.

Avg returns the statistical mean, which is determined by calculating the sum of all values and dividing by the number of values.

Count returns the total number or quantity of values in a combination. If you request this value on a binding in a PX view, the system counts the number of values based on the properties defined by the data source block and the algorithm’s Property Sheet.

First returns the first value in the combination.

Last returns the last value in the combination.

Max returns the highest value in the combination.

Median returns the value in the middle of a sorted combination—the number that separates the higher half from the lower half.

Min returns the lowest value in the combination.

Mode returns the statistically most frequently occurring number in the combination.

Or returns the logical “or” of Boolean values.

Range returns the statistical difference between the largest and smallest values in the combination.

Sum adds together all values in the combination resulting in a single value.

Std Dev calculates the standard deviation of the values in the combination.

Load Factor calculates the average divided by peak (Max) value.

Interval optional drop-down list (defaults to the optimal number of records on reports); interval=option Refers to the BInterval component, which the framework uses to identify the time between values in a trend (time series). When specified, a rollup is required, which causes the system to combine all values that fall into a single interval.

Options range from None to a Year.

Above the drop-down list, the Use This Value check box turns on and off the check box next to Interval in the Settings window (you access this window by clicking the Edit button (Image), followed by clicking the Settings button (Image) on the chart). The availability of this check box provides an easy way for a user to enable and disable the use of intervals in chart calculations.

Response example

{

  "message" : "Subscribe",
  "name" : "SubscriptionName",
  "values" :
  [
       {
           "message" : "GetValue",
           "uid" : "identifier uniquely identifying
                   this specific GetValue",
           "node" : "slot:/nAnalyticTree/East",
           "data" : "definition:Some/Data/Definition",
           "tags" : ["hvac", "it"],
           "tagMode" : "all",
           "aggregation" : "max",
           "rollup" : "average",
           "interval" : "oneMinute",
           "type" : "numeric",
           "value" : "20.20",
           "display" : "20.20{ok}",
        }
   [
}

Response elements

The response is the same as for PollSubscription (except for the message name). Only some response values may be subscribed. The server may break up a very large response into smaller sets of responses.

Response element Value Description
message Subscribe Identifies the type of request being submitted.
name (of subscription) text Defines the subscription name. If the client does not already have a subscription by the given name, the system creates one.

Subscriptions are private to each session and only have to be unique in that context.
Values multiple Defines one or more GetValue message requests. See Values.

Values

Property Value Description
message text Identifies the type of request being returned.
uid client string Provides a unique identifier (uid) for the GetValue string. There could be several GetValues for the same node and data, each with different options, such as tags. For this reason, a unique identifier is required.
Node or node (required) ORD (defaults to a relative ORD slot, which is resolved against the config space to which the Px view is assigned) Defines the ORD to the desired slot.
Definition or data (required) input ORD for data definition

Identifies the data definition (properties) associated with an input point (nAnalytics variable). No other input point directly contained by the same node can have the same data definition.

BFormats are allowed here.
Tags or tags (optional) tag text Defines or returns the tags used for the operation. The framework searches the data model tree for nodes that declare or inherit tags based on the Tag Mode setting.
Tag Mode or tagMode Any (default) or All Constrains the search to find nodes with one or more of the defined tags (Any) or requires that all tags be present to include the node (All).
Aggregation check box (if optional, and) drop-down list (property, defaults to First) or ORD parameter (aggregation=option)

If aggregation is not enabled in the binding/settings window, the aggregation value defined in the Data Definition applies to all chart bindings, reports and tables.

And returns the logical “and” of Boolean values.

Avg returns the statistical mean, which is determined by calculating the sum of all values and dividing by the number of values.

Count returns the total number or quantity of values in a combination. If you request this value on a binding in a PX view, the system counts the number of values based on the properties defined by the data source block and the algorithm’s Property Sheet.

First returns the first value in the combination.

Last returns the last value in the combination.

Max returns the highest value in the combination.

Median returns the value in the middle of a sorted combination—the number that separates the higher half from the lower half.

Min returns the lowest value in the combination.

Mode returns the statistically most frequently occurring number in the combination.

Or returns the logical “or” of Boolean values.

Range returns the statistical difference between the largest and smallest values in the combination.

Sum adds together all values in the combination resulting in a single value.

Load Factor returns the average value divided by peak value.

Std Dev returns the standard deviation of the values in the combination.

Rollup check box (if optional, and) drop-down list or ORD parameter (when configured in the data definition, defaults to First, when configured elsewhere, defaults to the value as defined in the Data Definition); rollup=option

If rollup is not enabled in the binding/settings window, the rollup value configured in the Data Definition applies to all chart bindings, reports and tables.

And returns the logical “and” of Boolean values.

Avg returns the statistical mean, which is determined by calculating the sum of all values and dividing by the number of values.

Count returns the total number or quantity of values in a combination. If you request this value on a binding in a PX view, the system counts the number of values based on the properties defined by the data source block and the algorithm’s Property Sheet.

First returns the first value in the combination.

Last returns the last value in the combination.

Max returns the highest value in the combination.

Median returns the value in the middle of a sorted combination—the number that separates the higher half from the lower half.

Min returns the lowest value in the combination.

Mode returns the statistically most frequently occurring number in the combination.

Or returns the logical “or” of Boolean values.

Range returns the statistical difference between the largest and smallest values in the combination.

Sum adds together all values in the combination resulting in a single value.

Std Dev calculates the standard deviation of the values in the combination.

Load Factor calculates the average divided by peak (Max) value.

Interval optional drop-down list (defaults to the optimal number of records on reports); interval=option Refers to the BInterval component, which the framework uses to identify the time between values in a trend (time series). When specified, a rollup is required, which causes the system to combine all values that fall into a single interval.

Options range from None to a Year.

Above the drop-down list, the Use This Value check box turns on and off the check box next to Interval in the Settings window (you access this window by clicking the Edit button (Image), followed by clicking the Settings button (Image) on the chart). The availability of this check box provides an easy way for a user to enable and disable the use of intervals in chart calculations.

Related Links

  • Messages (Parent Topic)

    • Index | Prev | Next