Standard References

Standard references may point to:

•	Cells of Data Tables containing values of context variables/functions or just some relevant data.

•	Properties of context variable/function definitions (their descriptions or flags indicating whether the variable is readable/writable).

•	Properties of data table fields (e.g. their descriptions and help texts).

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

"Classic" Data Table Cell References

In the most common use case, standard references resolve to a Data Table cell value. This Data Table may be a variable value, function output, or just a certain table defined in current environment (see Default Data Table).

Full syntax: context:entity(parameter_list)$field[row]. Resolved to a value of Data Table cell pointed by field and row. Data Table is a value of variable entity (or function entity if parameter_list is specified) in context context.

Value from Default Context: entity(parameter_list)$field[row]

Value from Default Data Table: field[row]

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 widgets, the default context is one from which the widget 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.

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).

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.

A variable (such as childInfo) may actually be a table containing some fields (such as firstname). To refer to a field of some variable, you have to follow the variable name with a $ sign, followed by the field's name. So, to make the entity part refer to the firstname field of the userInfo variable, you would have to write it as childInfo$firstname.

If reference points to a function, and 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.

Data Table References

Resolved Data Table references return a whole Data Table.

Data Table returned by such references is often used as an input parameter of Data Table processing functions.

If neither field nor property is specified, reference is resolved:

•	to Data Table representing entity value, if entity is specified;

•	to Default Data Table, if entity is not specified.

Variable value reference syntax: context:variable

Function output reference syntax: context:function(parameter_list)

The above items mean that empty reference ("") is resolved to a Default Data Table.

Here is how to insert reference to a Default Data Table into an expression: {}

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 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).

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 one of the following properties:

Property	Type	Description
row	Integer	This property resolves to the current row of the Data Table being processed. For example, when widget 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 in the childInfo variable of the default ("current") context. This reference 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 ().