Utilities

This context is a system context that provides miscellaneous operations. It is not shown in the visible context tree.

Unique Actions

[?]

Show Data

This action fetches some data from the system by calculating an expression, shows it to the user using Edit Data UI procedure, and enables automatic re-retrieving and auto-refreshing of the shown data.

Action Name:	showData
Non-Interactive Mode:	Not Supported
Permissions:	Accessible at Observer permission level
Execution Parameters:	1. Data Acquisition: Expression to calculate Refresh period 2. Data Presentation: Title of the data window Help, the text to show in the data window Icon, the icon ID string of the data window icon 3. Location of the data window 4. Dashboard Properties of the data window

Show Report

This action shows a report based on custom Device. It uses Show Report UI procedure, and allows to control standard design template properties.

Action Name:	showReport
Non-Interactive Mode:	Not Supported
Permissions:	Accessible at Observer permission level
Execution Parameters:	Data: a Device to build report on. Design Properties: design template properties. If Design Properties parameter is not specified, a user is prompted to edit template properties in appropriate dialog. Afterwards a report window is opened.
		Binding example to use this action without user interaction: Target: `utilities:showReport!` Expression: `table("<<data><T>><<designProperties><T>>", {form/dataTableEditor1:dataTable}, array("title", "Some title"))` Activator: `form/button1:click@`

[?]

View Change History

This action shows historical changes of variable's value. It outputs the variable update history in the form of table. Every field of the monitored variable's format is shown in a separate field of the resulting table. If the variable value contains several rows, only the first row is shown.

View Variable Information

This action shows variable definition properties and its format.

[?]

View Event Information

This action shows event definition properties and its format.

Advanced Information

Context Information

Context Type: utilities

Context Name: utilities

Context Description: Utilities

Context Path: utilities

Context Mask: utilities

Context Permissions

[?]

Level	Description
None	Basic system internal operations.
Observer	Accessing and deleting variable/event history. Accessing and deleting variable statistics. Accessing device topology.
Operator	Sending E-mail and SMS messages.
Manager	Same as Operator.
Engineer	Requests for incoming mail checking.
Administrator	External application execution.

Public Variables (Properties)

[?]

This context has no public variables (properties).

Public Functions

[?]

Get Variable History

Returns update history of specified variables. See View Variable History action for more information.

Function Name:	variableHistory
Permissions:	Accessible at Observer permission level
Input Records:	1…Unlimited
Input Format:	Name	Type	Description
	context	String	Context or mask of contexts to load variable history from.
	variable	String	Name of the variable.
	fromDate	Date	Timestamp used to select only variable updates which occurred after a certain date. If it is NULL, all oldest events will be included.
	toDate	Date	Timestamp used to select only variable updates which occurred before a certain date. If it is NULL, all newest events will be included.
	dataAsTable	Boolean	If disabled (default behaviour), the resulting table will contain one additional field per every field of variable those history is retrieved. Thus, this mode is suitable if the following apply: There’s just one record in the function’s input parameters table Context parameter is not a mask Variable pointed by Context and Variable parameters is a single-record variable In all other cases value of this parameter will not be respected. If enabled or not respected, the historical values will be contained in a separate tabular field called `vValue`.
	limit	Integer	Maximum number of historical values to retrieve.
	sortAscending	Boolean	Flag switching between ascending and descending sorting of historical values.
Output Records:	0...unlimited
Output Format:	Output format is dynamic. It has `vContext` and `vVariable` string fields is history for more than one variable was loaded. It always has the `vUpdateTime` date field that contains timestamps of historical values. If has `vValue` data table field that contains historical values if the dataAsTable parameter was enabled or not respected. If has columns matching fields of the only variable those history was loaded if dataAsTable parameter was disabled and respected.

Execute External Application

This function executes an external application referred by input arguments, waits for its termination and returns its output.

This function has limited capabilities. For example, it cannot run piped commands and has limited support for accepting command line arguments with string escaping etc.

Use External Application/Script device driver for more customizable application execution.

Function Name:	execute
Permissions:	Accessible at Administrator permission level
Input Records:	1
Input Format:	Name	Type	Description
	command	String	Command fully qualified name with arguments.
	directory	String	Working directory, may be omitted but only if the next argument, charset, is also omitted. If there is no need to specify a directory but there is a need to specify a charset, NULL must be used as a directory argument.
	charset	String	Canonical name of the encoding as specified in the java.nio API, may be omitted. The list of supported encodings can be found in the Oracle documentation.
Output Records:	1
Output Format:	Name	Type	Description
	exitCode	Integer	Command exit code.
	output	String	Capture of command output.
	errors	String	Capture of command error output.

{utilities:execute("admin/executer.bat mkdir admin\\ myPath\\NewPath")} will create a folder with path adminmyPathNewPath

List Variables

This function returns a list of values of all single-cell (i.e. non-tabular and non-array) variables in all contexts matching to a certain mask and belonging to a certain group.

Function Name:	listVariables
Permissions:	Accessible at Observer permission level
Input Records:	1
Input Format:	Name	Type	Description
	mask	String	Mask of context to list variables from.
	group	String	Variable's group.
Output Records:	0...unlimited
Output Format:	Name	Type	Description
	context	String	Context description.
	variable	String	Variable description.
	value	String	String representation of variable's value.

Statistics

This function returns last values for a statistical channel (e.g. last month's average, last day's minimum, etc.)

Function Name:	statistics
Permissions:	Accessible at Observer permission level
Input Records:	1
Input Format:	Name	Type	Description
	mask	String	Mask of context to fetch statistical data from.
	channel	String	Name of channel.
	key	String	Dataset key or NULL to use default dataset.
	period	String	Time period to show last values for. If NULL, the data will be fetched for all periods. Period names: millisecond or ms for Milliseconds second, sec or s for Seconds minute, min or m for Minutes hour, hr or h for Hours day or d for Days week or w for Weeks month for Months (Note, that month is zero-based, i.e. value for January is 0.) year or y for Years
	full	Boolean	If true, all statistical values are returned according to the above period (e.g. all hourly averages). If false, only last collected values are returned (e.g. last full hour averages).
	average	Boolean	Show average value for the last period of selected type. Default is true.
	minimum	Boolean	Show minimum value for the last period of selected type. Default is false.
	maximum	Boolean	Show maximum value for the last period of selected type. Default is false.
	sum	Boolean	Show total value for the last period of selected type. Default is false.
	first	Boolean	Show first value for the last period of selected type. Default is false.
	last	Boolean	Show last value for the last period of selected type. Default is false.
Output Records:	0...unlimited
Output Format:	Name	Type	Description
	context	String	Name of context that originated data.
	start	Date	Start of time period.
	end	Date	End of time period.
	key	String	Dataset key or NULL if default dataset was used.
	average	Float	Average value for the time period.
	minimum	Float	Minimum value for the time period.
	maximum	Float	Maximum value for the time period.
	sum	Float	Total value for the time period.
	first	Float	First value for the time period.
	last	Float	Last value for the time period.

Raw Statistics

This function returns raw statistical data for a statistical channel.

Function Name:	rawStatistics
Permissions:	Accessible at Observer permission level
Input Records:	1
Input Format:	Name	Type	Description
	context	String	Name of context to fetch statistics from.
	name	String	Name of channel to fetch statistics from.
Output Records:	0...unlimited
Output Format:	Dynamic

Context Entities Statistics

Returns statistics for the entities of the specified context or contexts.

Function Name:	contextEntitiesStatistics
Permissions:	Accessible at Observer permission level
Input Records:	1
Input Format:	Name	Type	Description
	mask	String	Context or context mask associated with the desired entities. Optional, default is root context.
	type	String	Indicate entity type to collect for statistics. Required, one of the following must be provided: 1 - Variables 2 - Functions 4 - Events
	name	String	Specify exact entity name to filter results. Optional, default will display all associated entities.
Output Records:	0...unlimited
Output Format:	Name	Type	Description
	context	String	Context path associated with the entity.
	name	String	Name of the entity.
	getCount	Integer	Variables Only - number of times the variable value has been retrieved.
	setCount	Integer	Variables Only - number of times the variable value has been set.
	execCount	Integer	Functions Only - count of function executions.
	subscribeCount	Integer	Events Only - count of times components have subscribed to the event.
	unsubscribeCount	Integer	Events Only - count of times components have unsubscribed from the event.
	listenerCount	Integer	Events Only - count of event listeners.
	instancesCount	Integer	Events Only - count of event instances.

Delete Statistics

This function is used to purge all data collected by a statistical channel.

Function Name:	deleteStatistics
Permissions:	Accessible at Observer permission level
Input Records:	1
Input Format:	Name	Type	Description
	mask	String	Mask of contexts to look for statistical channels.
	channel	String	Name of channel to purge data from.
Output Records:	0
Output Format:	None

Selection Values

This function returns a data table suitable to be used as selection values of another data table's field. It's most often used in an expression of a data table binding that's targeted to the choices property of the field.

The function first constructs an intermediate data table by evaluating an expression. It then goes through this table row-by-row and evaluates two other expressions for each row. First one returns the selection values itself and second one returns its description.

The arguments of selectionValues are all expressions. In the example below, see that the tableExpression argument is not simply reference to a variable of DataTable type, but actually an expression which returns a data table.

callFunction("utilities"
  , "selectionValues"
  , "{users.admin.models.svExampleModel:svTable}"
  ,"{ifIndex}"
  ,"{ifDescr}"
)

The following example shows how an expression uses the function getVariable retrieve the svTable variable.

callFunction("utilities"
  , "selectionValues"
  , 'getVariable("users.admin.models.svExampleModel", "svTable")'
  , "{ifIndex}"
  , "{ifDescr}"
 )

Function Name:	selectionValues
Permissions:	Accessible at Observer permission level
Input Records:	1
Input Format:	Name	Type	Description
	tableExpression	String	Expression that should return a table whose records will be used to construct selection values list.
	valueExpression	String	Expression that's calculated over each record of the above table and should return a string representation of a selection value.
	descriptionExpression	String	Expression that's calculated over the same record and should return a description of the selection value.
Output Records:	0...unlimited
Output Format:	Name	Type	Description
	value	String	String representation of a selection value.
	description	String	Description of the selection value.

Summary

This function aggregates time series data by calculating per-source and per-time-period averages, minimums, maximums, totals, sample counts, and other metrics. Source numeric values can be fetched from:

Historical context events stored in the server database
Historical values of a context variable (also loaded from the server database)
Data collected by a statistical channel

The function input is a multi-row table. Each row in the input table defines a distinct data series. Each data series will be represented by a separate column in the function output, e.g. "per-period per-source averages for variable A" or "per-period per-source sample counts for event B".

Function Name:	summary
Permissions:	Accessible at Observer permission level
Input Records:	0...unlimited
Input Format:	Name	Type	Description
	seriesName	String	Name of the data series, i.e. name of series column in the function output. Must contain only English letters, numbers and underscore characters.
	seriesDescription	String	Human-friendly description of the series, i.e. description of the output field.
	startDate	Date	Earliest date of the first data sample that will be processed for the series.
	endDate	Date	Latest date of the last data sample that will be processed for the series.
	masks	String	Space-separated list of context masks matching sources to load series data from. Examples: `users..devices.` - all devices available for the function caller `users.john.devices.dev1 users.john.devices.dev2` - two specific devices
	entity	String	Name of context entity (i.e. variable or function) those historical values will be processed by the series.
	entityType	Integer	Type of context entity those historical values will be processed by the series. Can be Variable or Function, see their numeric code reference here.
	expression	String	Iotellect expression that must return a number. The expression is used to: Fetch numeric data samples from Data Tables representing historical events and variable values Process pre-aggregated data samples contained in a statistical channel (if series refers to statistics) If expression returns NULL, a processed data sample is discarded.
			Series Date Expression Resolution Environment:
			Default Context	Context those history/statistics is being processed.
			Default Data Table	Data Table representing a currently processed historical event or variable value.
			Default Row	0
			Environment Variables	Standard variables only.
	dateExpression	String	Iotellect expression that must return a date. It is used to fetch sample acquisition dates from Data Tables representing historical events and variable values. NULL expression (the default suitable for most cases) forces the function to use timestamps indicating when historical events and variable values were written to the server database.
			Series Date Expression Resolution Environment:
			Default Context	Context those history/statistics is being processed.
			Default Data Table	Data Table representing a currently processed historical event or variable value.
			Default Row	0
			Environment Variables	Standard variables only.
	grouping	Integer	Time period type to use for data grouping. See available types here.
	aggregation	Integer	Numeric values aggregation type. See available types here.
	changeType	Integer	Type of the series. See descriptions of available types here. Numeric type codes: 0 - Gauge 1 - Counter 2 - Derive 3 - Absolute
	outOfRangeValuesHandling	Integer	Defines how out-of-range values (i.e. gauge-type values or per-second rates calculated according to the above series type) will be processed: 0 - Ignore, i.e. don't respect the below minimum and maximum values 1 - Discard, i.e. don't process values that are out of the below range 2 - Normalize, i.e. convert low and high out-of-range values to the lower or upper bounds respectively
	minValue	Double	Minimal allowed gauge-type value or per-second rate.
	maxValue	Double	Maximal allowed gauge-type value or per-second rate.
	timeZone	String	Time zone to use for aligning time periods in the output table. If null, Iotellect Server default time zone is used. Time zones can be specified in the string form, e.g.: GMT-8 GMT-08:00 America/Los_Angeles Specifying different timezones for different data series is not supported and will cause unpredictable results.
	showDetails	Integer	Defines whether per-time-period data will be added to the function output: 0 - Never, the per-time-period record will be skipped unless other series define that it should be visible. If this option is used for all series, the details section will be effectively skipped and only totals will be shown. 1 - Always, the per-time-period record will be added even if other series define that is should be skipped 2 - Valuable, the per-time-period record will be added only if aggregate value is not null or NaN (or if other series define that is should be visible) The default value is Always.
	showTotals	Boolean	Defines whether all-range totals will be added to the function output. Only value defined for the first series (i.e. in the first row of function input) will be used, other values will be ignored.
	sortPriority	Integer	Defines sorting policy for the function output: 0 - group by time periods first, then by sources 1 - group by sources first, then by time periods
Output Records:	0...unlimited
Output Format:	Static output fields that are always available:
	Name	Type	Description
	periodName	String	Human-readable name of the time period those aggregated data is represented by the output record.
	periodMiddle	Date	First millisecond of a time period those aggregated data is represented by the output record.
	periodEnd	Date	Middle millisecond of a time period those aggregated data is represented by the output record.
	periodStart	Date	Last millisecond of a time period those aggregated data is represented by the output record.
	context	String	Path of a source context those data is represented by the output record.
	Additional columns of the function output are defined by data series specified in the function input:
	Name	Type	Description
	name defined by `seriesName` input field	`Date` for series using First Date and Last Date aggregation types. `Integer` for series using Total Count and Valid Count aggregation type. `Double` for other series.	Each dynamic column contains per-source per-time-period aggregates calculated according to the series parameters.

Fire Backdated Event

Generate events with a creation time is in the past. This is primarily useful for updating the history of events that were received from some third-party source with a delay.

Function Name:	fireBackdatedEvent
Permissions:	Accessible at Admin permission level
Input Records:	0...unlimited
Input Format:	Name	Type	Description
	context	String	Path of context to generate event in.
	event	String	Name of the event to generate.
	level	Integer	Event level or null to use default level.
	creationTime	Date	Past date of the event. Will be saved in server database.
	data	Data Table	Event-specific data. Must match format specified in event definition.
Output Records:	0
Output Format:	None

Create Component Location for Grid

Convenience function for creating a data table matching the format of the Component Location variable. The input values other than path are formatted and returned in the grid output field. The output fields absolute and dockabled each contain an empty, but correctly formatted, data table.

Function Name:	componentLocationForGrid
Permissions:	Accessible at Manager permission level
Input Records:	1
Input Format:	Name	Type	Description
	path	String	String indicating the path to a target dashboard or container as described in the `path` field of the Component Location variable.
	row	Integer	Refer to the `grid` field of the Component Location variable for descriptions of these fields.
	column	Integer
	rowSpan	Integer
	columnSpan	Integer
Output Records:	1
Output Format:	Name	Type	Description
	path	String	The same value provided in the input field `path`.
	absolute	Data Table	The same format as the `absolute` field in the Component Location variable. Contains no rows.
	grid	Data Table	The same format as the `grid` field in the Component Location variable. Contains a single row, containing the values indicated in the function input.
	dockable	Data Table	The same format as the `dockable` field in the Component Location variable. Contains no rows.

Create Component Location for Absolute

Convenience function for creating a data table matching the format of the Component Location variable. The input values other than path are formatted and returned in the absolute output field. The output fields grid and dockabled each contain an empty, but correctly formatted, data table.

Function Name:	componentLocationForAbsolute
Permissions:	Accessible at Manager permission level
Input Records:	1
Input Format:	Name	Type	Description
	path	String	String indicating the path to a target dashboard or container as described in the `path` field of the Component Location variable.
	x	Integer	Refer to the `absolute` field of the Component Location variable for descriptions of these fields.
	y	Integer
	width	Integer
	height	Integer
	zIndex	Integer
Output Records:	1
Output Format:	Name	Type	Description
	path	String	The same value provided in the input field `path`.
	absolute	Data Table	The same format as the `absolute` field in the Component Location variable. Contains a single row, containing the values indicated in the function input.
	grid	Data Table	The same format as the `grid` field in the Component Location variable. Contains no rows.
	dockable	Data Table	The same format as the `dockable` field in the Component Location variable. Contains no rows.

Create Component Location for Dockable

Convenience function for creating a data table matching the format of the Component Location variable. The input values other than path are formatted and returned in the dockable output field. The output fields grid and absolute each contain an empty, but correctly formatted, data table.

Function Name:	componentLocationForDockable
Permissions:	Accessible at Manager permission level
Input Records:	1
Input Format:	Name	Type	Description
	path	String	String indicating the path to a target dashboard or container as described in the `path` field of the Component Location variable.
	position	String	Refer to the `dockable` field of the Component Location variable for descriptions of these fields.
	positionAttribute	String
	targetId	String
	tabIndex	Integer
	tabPosition	String
	preferredWidth	Integer
	preferredHeight	Integer
	minimumWidth	Integer
	minimumHeight	Integer
	x	Integer
	y	Integer
	width	Integer
	height	Integer
	movable	Boolean
	closable	Boolean
	resizable	Boolean
	collapsible	Boolean
	maximizable	Boolean
	floatable	Boolean
	collapsed	Boolean
	showHeader	Boolean
	description	String
	icon	Data Table
Output Records:	1
Output Format:	Name	Type	Description
	path	String	The same value provided in the input field `path`.
	absolute	Data Table	The same format as the `absolute` field in the Component Location variable. Contains no rows.
	grid	Data Table	The same format as the `grid` field in the Component Location variable. Contains no rows.
	dockable	Data Table	The same format as the `dockable` field in the Component Location variable. Contains a single row, containing the values indicated in the function input.

Get Modules

Returns a table with information about all the modules available in the indicated store. The specified storeAddress must exist and be configured in the Store List under Global Configurations.

Function Name:	getModules
Permissions:	Accessible at Manager permission level
Input Records:	1
Input Format:	Name	Type	Description
Input Format:	storeAddress	String	Indicate the store address from which to retrieve the module list.
Output Records:	0… Unlimited
Output Format:	Name	Type	Description
	id	String	Module ID.
	description	Boolean	Successfully
	image	Data Block	Image associated with the module
	versions	Data Table	Data table containing information for different versions of the module. version: Indicates module version. description: Module description content: File containing the module. dependencies: List of module dependencies. preInstallScript: Script to be run before module installation. postInstallScript: Script to be run after module installation. preUninstallScript: Script to be run before module is uninstalled. postUninstallScript: Script to be run after module is uninstalled.

Get Solutions

Returns a table with information about all the solutions available in the indicated store. The specified storeAddress must exist and be configured in the Store List under Global Configurations.

Function Name:	getSolutions
Permissions:	Accessible at Manager permission level
Input Records:	1
Input Format:	Name	Type	Description
Input Format:	storeAddress	String	Indicate the store address from which to retrieve the list of solutions.
Output Records:	0… Unlimited
Output Format:	Name	Type	Description
	name	String	Solution name.
	description	String	Solution description.
	modules	Data Table	List of IDs of the modules which comprise the solution. The data table has a single field: id: Module ID

Install Modules

Install any number of modules by providing a list of module IDs. The specified storeAddress must be exist and be configured in the Store List under Global Configurations.

Function Name:	installModules
Permissions:	Accessible at Manager permission level
Input Records:	1…unlimited
Input Format:	Name	Type	Description
	storeAddress	String	Store address.
	id	String	ID of module to install.
Output Records:	0… Unlimited
Output Format:	Name	Type	Description
	id	String	Module ID
	installed	Boolean	Indicates if the module was successfully installed.
	status	String	If the module was not successfully installed, indicates the reason for failure.

Uninstall Modules

Uninstall any number of modules by providing a list of module IDs.

Function Name:	uninstallModules
Permissions:	Accessible at Manager permission level
Input Records:	1
Input Format:	Name	Type	Description
Input Format:	id	String	ID of module to uninstall.
Output Records:	0… Unlimited
Output Format:	Name	Type	Description
	name	String	Module name
	uninstalled	Boolean	Indicates if the module was successfully uninstalled
	status	String	If the module was not successfully uninstalled, indicates the reason for failure

Construct Storage

Creates or updates a table in a database to serve as the storage for a class. Calling this function in the utilities context will target the Relational Database configured for the server. If called with the context of a device using the SQL Database Driver or Graph Database Driver, it will create or update a table in the database indicated by the device configurations.

Function Name:	storageConstruct
Permissions:	Accessible at Manager permission level
Input Records:	1
Input Format:	Name	Type	Description
	table	String	Name of the table to be created or updated in the database.
	fields	Data Table	List of fields to create in the indicated table. This input is the same format as the Class Configuration Fields table.
	lifeCycles	Data Table	Table describing the life cycles of the class which will manage the newly created table. This input is formatted the same as the Class Configuration Life Cycles table.
	manyToManyRelations	Data Table	Table describing the relations of the class which will manage the newly created table. This input is formatted the same as the Class Configuration Many To Many Relations table.
	inheritedTables	Data Table	List of tables that are inherited by the table named in the table input parameter. This data table has a single field with any number of rows: Name: Name of a table inherited by the table named in the table input parameter
	dropExistingColumns	Boolean	Optional input with default value `True`, and the following effect on function execution: When `True`, any columns already existing in the table named by the table input parameter will be dropped, except for columns listed in the field input parameter. When `False`, any columns already existing in the table named by the table input parameter will be unaffected if they are not listed in the field input parameter.
Output Records:	0
Output Format:	None

Public Events

[?]

Common Events: info (Information)

DPF_EXPORT_V5.8.8 / TIME_1743710539 / 2025-04-03 20:02:19 / STRLEN_78027 / STRLEN_HTML_80058

{VERSION}

Was this page helpful?