ExternalRelation Reference

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

ExternalRelation nodes are used exclusively in The Structure File to define relations from tables in the Data Dictionary to "external" tables (e.g. tables NOT in Data Dictionary). Currently the TOPICA framework only supports relations to the tables Patient and OrgUnit - so the ExternalRelation elements may only refer to these two tables.

ExternalRelation may only be defined below StructureElement nodes ExternalRelation may NOT be used in defining input forms.

See ExternalRelation for description of the framework class. Note that only a subset of the fields are settable in the The Structure File, including when Using the Editor.

Using ExternalRelation

Use of ExternalRelation is optional.

Per default (when ExternalRelation is NOT used), each table in the Data Dictionary has exactly 1 relation to table Patient and 1 relation to table OrgUnit. Records always have relation to table Patient, and a field in StructureElement (the field OrgUnitRelation) determines whether and how the refenrce to table OrgUnit is used.

Use ExternalRelation if you need to have more one relation to table OrgUnit (so that each record may have 0 to many relations to organisational units).

Caution
Each record still MUST have exactly 1 reference to a patient. When using ExternalRelation, it is the configurator's responsibility to establish that every table in the Data Dictionary has 1 relation to table Patient!

ExternalRelation fields

Field

Type

Description

ReferencedTable

String

Name of the "external" table, the current table refers to.

Caution
Currently the only legal values are "Patient" and "OrgUnit".

ReferencedColumns

String

Comma-separated list of key fields in the referenced table.

When ReferencedTable equals "Patient", the legal value is "ID".

When ReferencedTable equals "OrgUnit", the legal value is "Type, Code".

RelationName

String

RelationName is used to auto-generate "foreign key" fields in the table. Therefore, RelationName must be unique within one table.

When ReferencedTable equals "Patient", RelationName MUST be BLANK.

There may be multiple relations on one table, where ReferencedTable equals "OrgUnit". ONe of the relations may have blank RelationName. This is called the default relation. Use this feautere for backward compatibility.

Examples:

ReferencedTable	ReferencedColumns	RelationName	Foreign key fields created in database table
Patient	ID		PATIENT_ID
OrgUnit	Type, Code		ORGUNIT_TYPE, ORGUNIT_CODE
OrgUnit	Type, Code	Relation1	ORGUNIT_Relation1_TYPE, ORGUNIT_Relation1_CODE
OrgUnit	Type, Code	Relation2	ORGUNIT_Relation2_TYPE, ORGUNIT_Relation2_CODE

Caption

String

Text displayed in user interface.

Propagate

Boolean

Set this to Boolean to make the relation "propagate" to all descendant tables (tables lower in the hierarhcy).

As described, it is the configurator's responsibility to establish that every table in the Data Dictionary has 1 relation to table Patient.

To implement this, add an ExternalRelation referring to table Patient to the "root" in The Structure File, and set Propagate=True.

Also when creating relations to table OrgUnit on a lower level (e.g. the "encounter" level), it will in most cases be useful to set Propagate=True. In this way all records below the encounter will "inherit" the relation value (as in the default case, when ExternalRelation is NOT used).

In other words: only in exceptional cases will it be useful to set Propagate=False (to disable "inheriting" references).

FillInStatusSelect

Enumeration

Value (integer)	Symbolic name
0	FillInStatus_Optional
1	FillInStatus_Required
2	FillInStatus_NotNull

FillInStatusComputation

String

TOPICA Basic expression that must return one of the enumariont values lsited for FillInStatusSelect above.

When FillInStatusComputation is blank, the value of FillInStatusSelect is used.

This makes it possible to dynamically configure the "fillin status" (whether it is required to enter an OrgUnit in the relation when crating records).

CssClassComputation

String

TOPICA Basic expression that should return a CSS class name. Obviously this CSS class name should be defined in one of the CSS files used.

StyleComputation

String

TOPICA Basic expression returning a value for an "inline" CSS style.