Multi-Histories

Block Group:	Data Services
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.

These properties can take input and give output.

• invoke (trigger)
• enabled (boolean)
• interval (number)
• autoRun (boolean)
• timeout (number)
• paths (multi-line text)
• thread (number)
• 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)
• unifyTimezone (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 autoRun 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 (default)—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. The default is 60.

paths specifies the list of paths to the histories to load, separated by line breaks or commas. 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.

thread specifies the maximum number of histories that are requested at the same time. The default, 0, means that all histories are requested at once.

timeRange specifies the date and time range to return the histories for. The default is today. 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. Options are Default (default), None, One year, Three months, One month, One week, One day, Twelve hours, Six hours, Four hours, Three hours, Two hours, One hour, Thirty minutes, Fifteen minutes, Ten minutes, Five minutes, One minute, Thirty seconds, Fifteen seconds, Ten seconds, Five seconds and One second.

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 (default)—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
• And—The logical AND of all values in the interval
• Or—The logical OR of all values in the interval
• Count—How many non-null values are in the interval
• Auto—No rollup is specified; the server's default is used

missingValue specifies what value to display in the event of missing data. To use a different setting for each history, enter one value per path, separated by line breaks or commas, in the same order as paths. The value of the missingValue property can be one of the following:

• Null (default)—a null value
• Use previous—The value for the previous timestamp
• Use next—The value for the next timestamp
• Interpolate—A value linearly interpolated between the previous and next values, based on the timestamps (numeric histories only)
• 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 (default)—The default string "vn", where n is the position of the path, starting from 0
• 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. To use a different setting for each history, enter one value per path, separated by line breaks or commas, in the same order as paths.

• None (default)—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

unifyTimezone specifies the time zone of the timestamps in the output table.

• auto (default) or local—Timestamps are converted to the browser's local time zone.
• remote—Timestamps are kept in the time zone returned by the server.
• You can also enter a time zone offset such as +08:00 or -05:00.

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

• loading (boolean)
• output (table)
• loaded (number)

loading returns whether the histories are currently loading.

loaded returns the number of histories that have finished loading in the current request.

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.
• vn_status—If showStatus is TRUE, the status of the data node at the time of collection. (With header set to other than Default, the column is named after the value column with _status appended.)

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.

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