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 duratino of the session.
Some global variables (e.g. Patient) will reflect the context seelcted 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

DataDictionary

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

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 (for employee administration).

Set (e.g. not null) when no employee has be set in context.

Caution
Not connected to 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 (e.g. during view / updating patient properties in the Patient Property Form, or during Entering Patient Data),

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

There is no way to set the Form global variable in the "TOPICA Basic Test" tool, 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 this value must initially be set to 1, and can optionally be 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 vital 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 vital 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-specfific global constants. As described elsewhere, TOPICA Basic is an extension of the generic expression language defined in the "rule engine" (documentend separately). Therefor, 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 constants (type: String). This mechanism is obsolete (the preferred way to access these values is using the ConfigString function) - but this is kept for backward compatibility.

Note

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

As described elsewhere, TOPICA Basic is an extension of the generic expression language defined in the "rule engine" (documentend separately). Therefor, 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 constants (type: String). This mechanism is obsolete (the preferred way to access these values is using the ConfigString function) - but this is kept for backward compatibility.