TOPICA Basic Global Variables

[This is preliminary documentation and is subject to change.]

Global variables are used to access information about the current context of the application. See also TOPICA Basic and Context.

Some global parameters will always have same value - e.g. DataDictionary.
Global variables EmployeeUser and PatientUser are defined by the logged in user, and will have the same value for the duration of the session.
Some global variables (e.g. Patient) will reflect the context selected by the user.
Some global variables will have same value during rendering of a page in the application. This is always true for Patient. It is also true for Record when rendering the page showing the record set in context. But during rendering of e.g. the patient record tree page, the record in context is varied (e.g. Record refers to each record being rendered in turn). This makes it possible to use TOPICA Basic to compute access to the record (i.e. to control security on the record level).

Global variables

Name

Type (class)

Description

Database

Access to information on databse server and databse.

Note

The global Database object CANNOT be access with Database - Database returns the connection string defined in the config files (typically Server.config).

db.ConnectString is equivalent to Database

DataDictionary

Metadata on the dynamic data model - i.e. data describing tables, fields, etc.

Table

DataDictionaryTable

When CREATING a new record (i.e. when a form is in "create mode"), Table refers to the DataDictionaryTable, that describes the database table, the new record will be created in.

When VIEWING/EDITING a record (i.e. when a form is in "edit mode"), Table has the value null. To get the table the current record belongs to, use the expression Record.Table.

OrgUnit

The organizational unit in context.

Set (e.g. not null) when an org.unit has been set in context.

Employee

The employee in context - happens during employee (user) administration.

Set (e.g. not null) when an employee has been set in context.

Note
Do not confuse with the logged in (employee) user - see EmployeeUser below!

EmployeeUser

Obsolete alias: User

Employee

The logged-in employee user.

Set (e.g. not null) when an employee is logged in.

If a patient is logged in, EmployeeUser will be null (and PatientUser will be different from null).

Patient

The patient in context.

Set (e.g. not null) when a patient has been selected (set in context).

During viewing / updating patient properties in the Patient Property Form.
During Entering Patient Data.
When running patient level reports.

Not set (e.g. null) in all other situations.

PatientUser

Patient

The logged-in patient user.

Set (e.g. not null) when a patient is logged in.

If an employee is logged in, PatientUser will be null (and EmployeeUser will be different from null).

Record

The dynamic patient data record in context.

The global variable Record is set (i.e. not null) in the following situations:

During building "open" nodes in the Patient Record Tree.
During viewing / updating a record (form instance).

The global variable Record is null in the following situations:

During building "create" and "group" nodes in the Patient Record Tree.
During creating a new record (form instance).

ParentRecord

Record

The "parent" dynamic patient data record in context.

The global variable ParentRecord is set (i.e. not null) in the following situations:

During building "create" and "group" nodes in the Patient Record Tree AND this node is NOT at the top level.
During creating a new record (form instance) below some other record (e.g. NOT when creating a record at the top level)

The global variable ParentRecord is null in the following situations:

During building "open" nodes in the Patient Record Tree.
During viewing / updating a record (form instance) directly below the patient.

Form

The (dynamic) input form.

This variable is set (holds value different from null) only when the user has a dynamic form displayed in the user interface.

Use the Form global variable to access the values entered by the user in the input fields of a form. This is used only in validation rules.

Caution
Use Form ONLY inside validation rules where it is guaranteed to be set (have value different from null). In most other situations Form will be null!

There is no way to set the Form global variable in the "TOPICA Basic Test" tool TestEvaluation.aspx, so you cannot test TOPICA Basic expressions involving Form in the "TOPICA Basic Test" tool.

Note
Values read from the Form global variable are NOT persisted to the database yet. Do not confuse with values read from the other global variable Record (these values come from a record that is saved in the database - can only be used in "edit" mode, because Record is null in "create mode").

Example: The current form as an integer field X. We want to implement a validation rule, that chekcs that this value is set to 1 at creation time, and (optionally) incremented by 1 at every update.

Copy

If(IsNull(Record), Form.X=1, (Record.X<=Form.X) And (Form.X<=Record.X+1))

Caution
It is important NOT to dereference null objects. As in most programming languages, dereferencing a null object causes an exception. Examples: Checking user: Normally, ONE of the variables EmployeeUser and PatientUser will contain a value different from null, and the other variable will be null. There are very few exceptions to this rule - this may only happen in few pages in the framework (pages that are specifically designed to be able to run in "anonymous" mode). Since these pages are not customizable by TOPICA Basic, these exceptional cases may be ignored. When implementing rules in forms, it is often important to distinguish between two scenarios: In "Edit mode", Record is set (e.g. not null). In this case ParentRecord will hold same value as Record.ParentRecord - both will be null if the current record is at the top of the record hierarchy, e.g. directly below the patient. In "Create mode", Record is null. In this case ParentRecord will be set (e.g. not null), when the record to be created will be created below some other record. If the record to be created will end up at the top of the record hierarchy (e.g. directly below the patient), ParentRecord will be null.

Caution

It is important NOT to dereference null objects. As in most programming languages, dereferencing a null object causes an exception. Examples:

Checking user:
- Normally, ONE of the variables EmployeeUser and PatientUser will contain a value different from null, and the other variable will be null. There are very few exceptions to this rule - this may only happen in few pages in the framework (pages that are specifically designed to be able to run in "anonymous" mode). Since these pages are not customizable by TOPICA Basic, these exceptional cases may be ignored.
When implementing rules in forms, it is often important to distinguish between two scenarios:
- In "Edit mode", Record is set (e.g. not null). In this case ParentRecord will hold same value as Record.ParentRecord - both will be null if the current record is at the top of the record hierarchy, e.g. directly below the patient.
- In "Create mode", Record is null. In this case ParentRecord will be set (e.g. not null), when the record to be created will be created below some other record. If the record to be created will end up at the top of the record hierarchy (e.g. directly below the patient), ParentRecord will be null.

Note
This topic describes only the built-in TOPICA-specific global constants. As described elsewhere, TOPICA Basic is an extension of the generic expression language defined in the "rule engine" (documented separately). Therefore, all constants defined in the "rule engine" also exist in TOPICA Basic. All parameters defined in the config files are accessible from TOPICA Basic as string values - simply by specifying the parameter key. This mechanism is obsolete - partly because of risk of "name clashes", partly because this does not work when the key contains ".". The preferred way to access .config-file parameters values is using the ConfigString function).

Note

This topic describes only the built-in TOPICA-specific global constants.

As described elsewhere, TOPICA Basic is an extension of the generic expression language defined in the "rule engine" (documented separately). Therefore, all constants defined in the "rule engine" also exist in TOPICA Basic.

All parameters defined in the config files are accessible from TOPICA Basic as string values - simply by specifying the parameter key. This mechanism is obsolete - partly because of risk of "name clashes", partly because this does not work when the key contains ".". The preferred way to access .config-file parameters values is using the ConfigString function).