Multi-Histories

Block Group: Data Services
Block Icon:Multi-Histories block icon

The Multi-Histories block retrieves a table of information about the value histories of multiple data nodes.

For information on using dataflow blocks, see Dataflow.

Note

The invoke property must be triggered to load the table the first time and also to load the table after any changes.


Input/Output Properties

These properties can take input and give output.

  • invoke (trigger)
  • enabled (boolean)
  • interval (number)
  • autoRun (boolean)
  • timeout (number)
  • paths (multi-line text)
  • timeRange (date range)
  • dataInterval (enum or string)
  • showStatus (boolean)
  • rollup (enum or string)
  • missingValue (enum or string)
  • header (enum or string)
  • delta (enum or string)

invoke causes the histories to be loaded. This trigger works only if enabled is set to TRUE.

enabled specifies whether this Multi-Histories block is enabled.

  • TRUE—The histories load as specified by invoke, autoRun, and interval.
  • FALSE—The histories do not load.

interval specifies how often the histories are loaded, in seconds. A value of 0 means that they are reloaded on autoLoad or invoke only.

autoRun specifies whether the histories are loaded automatically.

  • TRUE—The histories are loaded every time any property is changed. The first time that the path property is populated counts as a change.
  • FALSE—The histories are loaded when the invoke property is triggered, or at the specified interval.

timeout specifies, in seconds, how long this block attempts to load the histories before the request is canceled.

paths specifies the list of paths to the histories to load, separated by line breaks. Do not use commas to separate file names. You can drag files from the Metrics panel to this field. To edit text in a popup window, click the Edit in Window icon. To create line breaks, press Alt + Enter in the block properties panel, or press Enter in the popup window.

timeRange specifies the date and time range to return the histories for. You can click the button and use the date range picker to specify a range.

dataInterval specifies the date or time interval between each consecutive pair of data points.

showStatus determines whether a status column is included for each value history column in the output table. Status values report the status of the node at the time that data was collected, such as “down” or “overridden.”

rollup specifies the type of rollup used. The value of the rollup property can be one of the following:

  • Avg—The average of all number values in the interval
  • Min—The smallest number value in the interval
  • Max—The largest number value in the interval
  • Sum—The sum of all number values in the interval
  • First—The first value in the interval
  • Last—The last value in the interval
  • Count—How many non-null values are in the interval

missingValue specifies what value to display in the event of missing data. The value of the missingValue property can be one of the following:

  • Null—a null value
  • Use previous—The value for the previous timestamp
  • Use next—The value for the next timestamp
  • Interpolate—The average between the previous and next timestamps
  • Zero—Zero

header specifies the string that is used as the name of each value history column in the output table. The value of the header property can be one of the following:

  • Default—The default string "vn"
  • Name—The name of this node, for which this column is a value history
  • Parent—The name of the data node's parent
  • Parent_Name—The names of both this node and its parent

delta specifies what is in the value history columns of the output table.

  • None—The value collected at the given time
  • With previous—The difference between the values in this row and the previous one
  • With next—The difference between the values in this row and the next one

Output Properties

The following properties of the Multi-Histories block can give output but cannot take input.

  • loading (boolean)
  • output (table)

loading returns whether the histories are currently loading.

output returns a table of the given histories' values. Columns are:

  • timestamp—The time associated with a value
  • vn—The first data node's value, or its delta if specified by the delta property.
  • status—The status of the data node at the time of collection.

How to Add Paths to the Multi-Histories Block

To add paths:

  1. Within the paths field, click Edit in Window to open a loadHistories.paths panel.
  2. In the Data panel, choose the relevant device or data source.
  3. Drag the relevant History icon from the Metrics panel to the loadHistories.paths panel.
  4. Press Enter to create a new line.
  5. Repeat steps 2 to 4 until all paths are entered.

Example

The following image demonstrates how to populate the paths property by dragging histories from the Metrics panel.

Multi-Histories dataflow model