Standard References

Standard references may point to:

Data Tables representing values of context variables, input/output of context functions or just some relevant data
Individual cells of the above tables
Properties of context variable/function/event definitions (e.g. their descriptions or readable/writable flags)
Properties of data tables and their fields (e.g. their descriptions and help texts)
And other pieces of the unified data model

The full syntax of a standard reference: context:entity(parameter_list)$field[row]#property

In most cases using references may be substituted by using Context and Data Table processing functions. References will in most cases look shorter but they won't offer any runtime benefits against using functions.

Syntax Variations

The below table shows and describes different possible syntax variations of standard references:

Syntax	Description	Function-based Analog
`field`	Returns value of a default table's cell pointed by field and default row.	`cell(dt(), "field")`
`field[row]`	Returns value of a default table's cell pointed by field and row.	`cell(dt(), "field", row)`
`variable$`	Returns data table representing value of variable in a default context.	`getVariable(dc(), "variable")`
`function(parameter_list)`	Calls function of a default context with parameters specified in parameter_list. Returns data table representing function output.	`callFunction(dc(), "function", parameter_list)`
`variable$field`	Gets data table representing value of variable from default context. Returns cell value of this data table pointed by field and default row.	`cell(getVariable(dc(), "variable"), "field")`
`variable$field[row]`	Gets data table representing value of variable from default context. Returns cell value of this data table pointed by field and row.	`cell(getVariable(dc(), "variable"), "field", row)`
`variabele$field[row].nestedField[rowInNested]`	Gets data table representing the value of variable from default context. If the cell indicated by row and field contains a data table, retrieves a cell in that data table identified with rowInNested and nestedField. The number of nesting levels is not limited. For example to address a 4th level table’s cell use `variabele$field[row].subField[subRow].subSubField[subSubRow].subSubSubField[subSubSubRow]` syntax.	cell( cell( getVariable( dc(), "variable" ) , "field" , row ) , "nestedField" , rowInNested )
`function(parameter_list)$field`	Gets data table representing output value returned by function of default context called with parameters specified in parameter_list. Returns cell value of this table pointed by field and default row.	`cell(callFunction(dc(), "function", parameter_list), "field")`
`function(parameter_list)$field[row]`	Gets data table representing output value returned by function of default context called with parameters specified in parameter_list. Returns cell value of this table pointed by field and row.	`cell(callFunction(dc(), "function", parameter_list), "field", row)`
`context:variable`	Returns data table representing value of variable in context.	`getVariable("context", "variable")`
`context:function(parameter_list)`	Calls function of context with parameters specified in parameter_list. Returns data table representing function output.	`callFunction("context", "function", parameter_list)`
`context:variable$field`	Gets data table representing value of variable from context. Returns cell value of this data table pointed by field and default row.	`cell(getVariable("context", "variable"), "field")`
`context:variable$field[row]`	Gets data table representing value of variable from context. Returns cell value of this data table pointed by field and row.	`cell(getVariable("context", "variable"), "field", row)`
`context:variabele$field[row].nestedField[rowInNested]`	Gets data table representing the value of variable from context. If the cell indicated by row and field contains a data table, retrieves a cell in that data table identified with rowInNested and nestedField. The number of nesting levels is not limited. For example to address a 4th level table’s cell use `context:variabele$field[row].subField[subRow].subSubField[subSubRow].subSubSubField[subSubSubRow]` syntax.	cell( cell( getVariable( "context", "variable" ) , "field" , row ) , "nestedField" , rowInNested )
`context:function(parameter_list)$field`	Gets data table representing output value returned by function of context called with parameters specified in parameter_list. Returns cell value of this table pointed by field and default row.	`cell(callFunction("context", "function", parameter_list), "field")`
`context:function(parameter_list)$field[row]`	Gets data table representing output value returned by function of context called with parameters specified in parameter_list. Returns cell value of this table pointed by field and row.	`cell(callFunction("context", "function", parameter_list), "field", row)`
`.:`	Returns path of default context.	`dc()`
`(empty reference text)`	Returns default table.	`dt()`

Default Row

If row is not specified, value is taken:

From current row, if Data Table is processed row-by-row in the current environment;
From row 0 (first row in a Data Table) in all other cases.

Full syntax: context:entity(parameter_list)$field

Value from Default Context: entity(parameter_list)$field

Value from Default Data Table: field

Default Context

If context is specified in the reference, data is fetched from this context.

If context is not specified, data is retrieved from a default context.

The default context is automatically defined according to whatever you're doing. For example, when filtering events, the default context is the context in which a given event (the one we're working on) was fired. You might say that the default context is the "current context".

Example: When working with dashboards, the default context is one from which the dashboard was launched.

Relative context paths (e.g. .devices.device1) are resolved starting from this default context.

Example: childInfo$firstname refers to the default context, while users.admin:childInfo$firstname explicitly refers to a specific context.

{.:} reference will return path of default context. dc() function will also return this path.

Default Data Table

Just like you can omit the context part of the reference and still end up with a valid reference, you can also omit the entity part. When you omit the entity part, it is assumed you're referring to the so-called "default" Data Table, which can also be called "current Data Table". For example, when filtering events, the default Data Table is the table for the event being currently filtered.

An example using the Default Data Table would be a reference such as firstname. That's the whole reference -- just firstname. When you write it, you assume the system would "know what you mean" -- i.e, that it would apply to the firstname field of the Data Table for event currently being filtered, in the case of filtering events.

{} (empty) reference will return the whole default Data Table (that can be used, for example, by Data Table processing functions). dt() function will also return this table.

Resolving Entity

The entity part specified in the reference is the name of a variable or function existing in the context you're referring to. It is considered to be a function if the reference contains a parameter_list in parenthesis, and as a variable otherwise. So users.admin:childInfo refers to a variable, while users.admin:delete() refers to a function. If the entity you're referring to (such as delete()) does not exist, resolution will fail.

If reference points to a function, it is called with parameters specified by the parameter_list during resolution.

Example: Resolution of reference :register("charlie", "12345", "12345") will cause execution of register function from the root context.

Function Parameter List

The parameter_list is then used to create a Data Table according to the function's input format as described here.

Error Handling

If an error occurs when getting variable value of calling function, reference resolution fails.

Resolving Properties

Sometimes, you might want to specify a property to find out a certain property of context, variable, function, data table, or data table field.

You might be wondering what is the difference between a field and a property. Well, a field contains actual data, while a property contains "meta-data" -- data about data. Let's say we're working with the version variable of the server context (its path is server:version). The variable contains a field (also called version) with actual data, such as "4.01.00" (this is the server version). You can refer to this field as server:version$version.

This same variable also has a description property, containing data about the variable. In this case, the property would contain a string, "Server Version". The property is not stored within the variable's Data Table -- rather, it "concerns" the variable definition (rather than its value). You can refer to this property as server:version#description.

So, when referring to a field you use the $ sign, and when referring to a property you use the pound sign (#). This is important because fields often have properties (i.e, a field has a description). More on this below.

Context Properties

Context property reference syntax: context:#property

Property	Type	Description
name	String	Name of the context.
description	String	Description of the context.
type	String	Type of the context.
icon	Image	Context icon. May be used by the Image component of a Widget.

Variable Definition Properties

Variable definition property reference syntax: context:variable#property

Property	Type	Description
description	String	Description of the variable.
icon	Image	Property-specific icon. May be used by Image component of a Widget.
readable	Boolean	True if variable is readable for current user.
writable	Boolean	True if variable is writable for current user.

Function Definition Properties

Function definition property reference syntax: context:function(parameter_list)#property

Property	Type	Description
description	String	Description of a function.

Data Table Properties

Data Table property reference syntax: context:entity(parameter_list)#property

Property	Type	Description
records	Integer	Number of records in the table. This can be useful for figuring out how many records were returned in response to your reference. For example, `users:list()#records` calls the function listing all users in the system and returns the number of records in the result (i.e, how many users your permissions allow you to see in the system).
quality	Integer	Quality code associated with the data table. It is a marker of the reliability of the data sample represented by the data table. Typically defined by the source of the data, whether a physical device or the device driver.
timestamp	Date	Timestamp of the data table value. Some parts of the system provide time information next to the data sample. For example, several types of drivers set this property to the timestamp of the physical device if it is provided by communication protocol.

Data Table Field Properties

Data Table field property reference syntax: context:entity(parameter_list)$field#property

Property	Type	Description
description	String	Field description
help	String	Field help (detailed description)
svdesc	String	Selection value description, i.e. string that is used to represent current field value in the user interface.

For example, users.admin:childInfo$firstname will return something like "John" (which is the value of the field), while users.admin:childInfo$firstname#description will return something like "User's first name" (which is the field's description property).

Property-only References

If reference consist of a property only (e.g. #property), it is resolved to the following property:

Property	Type	Description
row	Integer	This property resolves to the current row of the Data Table being processed. For example, when a dashboard chart is based on custom data, its Source Data table is processed line by line. For every line Source Data Bindings expressions are calculated. Thus, we may use `{#row}` in any Source Data Bindings expression to create consecutive series or category names (0, 1, 2, ...).

Examples

Reference Text	Comments
`recipient`	This reference returns the value of the `recipient` field in the default ("current") data table. It's useful, for example, when working with event filter expressions.
`recipient[3]`	Same as above, but the value is taken from the fourth row.
`users.admin:childInfo$email`	Resolves to the value of the `email` field in the Data Table containing the value for the `childInfo` variable in the `user.admin` context. Will contain the system administrator's email address in this case.
`:info$description`	This example starts with a colon. So it refers to the "" (empty string) context, which is the name of the root context. So it returns the description field of the info variable within the root context. Note that while "description" is also the name of a property, you can still have a "description" field as well. The difference is whether you use the # or the $ sign to refer to it.
`DS_setting#description`	Resolves to the description property of the `DS_setting` field in the default data table.
`users.test.deviceservers.ds1:buzz()`	Resolves to the Data Table returned by "buzz" function in context `users.test.deviceservers`. To get a data table, the "buzz" function must be called, thereby causing the `ds1` Device Server to blink its lights in the "real world".
`.:childInfo$firstname`	Resolves to the value of the `firstname` field in the `childInfo` variable of the default ("current") context. This references use a relative context path ("."). You might as well not put anything before the colon, but a dot works the same. You'll get a string with the user's first name ("Joe").
`.:childInfo$country#svdesc`	Returns name of user's country (that is the description of the selection value of `country` field). Note that `.:childInfo$country` will return the system internal numeric country code.
`users.admin.deviceservers.ds1.devices.1:selfTest("quick")$status`	This reference points to the `status` output field of the `selfTest` function defined in the context `users.admin.deviceservers.ds1.devices.1`. This function is called with one parameter.
`attendance:dailyActivityData('{.:}','{date}')`	This reference will resolve to a Data Table returned by `dailyActivityData` function defined in `attendance` context. This function will be called with two parameters: Result of evaluating expression `{.:}`, that is a path of default context ("`.`"). Result of evaluating expression `{date}`, that is value of `date` field in first row of default data table
`users.admin:#icon`	Resolves to an icon of user context ().

DPF_EXPORT_V5.8.8 / TIME_1743710530 / 2025-04-03 20:02:10 / STRLEN_32232 / STRLEN_HTML_33299

{VERSION}

Was this page helpful?