Application Metadata and Configuration
This paper describes Tolven's approach to managing application metadata and configuration. Both the eCHR and ePHR applications, supplied out-of-the-box with Tolven, are configured using this metadata. As such, metadata is the primary means of configuring a new or existing Tolven application.
Installation of Tolven includes three primary products: A database (eg PostgreSQL), an LDAP server (eg openLDAP), and the Tolven application server, which includes a Tomcat web server, JBoss, message queues, and a number of other components. Each of these three products may be upgraded from time to time as new versions become available. In general, Tolven will provide forward compatibility with these components. However, support agreements may enumerate specific versions of these components as well as the underlying operating system version(s) and web browsers supported.
The database holds configuration metadata e.g. the fact that there is a such thing as a list of patients, as well as instance data is defined by metadata, not "hard code".
For scalability, multiple Tolven application servers can access the same database. Each server will "see" the same configuration and instance data.
System Configuration (background)
A brief overview of system configuration is worth mentioning just to provide a context for the remainder of this document. This type of configuration is mostly about connecting up the components and ensuring that the components can trust each other. For example, the application server needs to know how to contact the database and what credentials to provide so that the connection is accepted.
Certain other system-wide configuration must also be managed: access to mail server, are demo accounts allowed to be setup, etc. What this type of configuration does not do is control how the application actually looks or behaves.
[Early versions of Tolven combined installation and configuration thus limiting the ability to uptake a new version without re-configuration. With the beta release, configuration is separate from installation information.]
Unlike many applications, Tolven comes with mutual authentication already enabled and configured. The system administrator does have to acquire and install digital certificates to replace the self-signed certificates provided by Tolven.
Account Type is the basis for each Tolven application. An Account Type is represented as a row in a database table. Out of the box, Tolven provides two Account Types, eCHR (Clinical) and ePHR (Personal). You may notice that, technically, these configurations are very similar, often with just small differences that appeal to a different audience. For example, a blood pressure reading is identical between applications but may be presented in different ways. The "patient list" in the ePHR application is called Family Members but otherwise behaves the same.
Attributes of the AccountType:
Home Page - The definition of the outer page of the main application
- CSS (Skin) - The Cascading Style Sheet that defines the look of the application (colors, tabs, spacing, etc)
Rules - OPS-5 Rules that will execute when a new message is processed in an Account of this AccountType
- Template Account - An Account to be used as a template when someone creates a new account under this Account Type.
AccountTypes are maintained by the system administrator.
Factory Preset to Account Type
As a convenience, Tolven does as much as possible to ensure that a new installation works "out of the box". This also provides a useful basis for testing and problem isolation. The hard-coded Factory Preset serves this purpose.
Tolven provides a mechanism to update the factory preset configuration when appropriate, however, this is completely optional.
Factory Preset Account Types can be disabled. One advantage of staying with (or at least close to) factory presets is that Tolven does the configuration work.
Rather than changing the factory preset configuration, it may be more manageable to create a completely new account type thus avoiding conflicts with the Tolven-provided account types.
The CSS for each account type is separate but since most of the page definitions are common between the two factory preset applications, the Tolven-supplied CSS files are virtually identical except for the visual aspects of the style sheets.
It is important to realize that because of multiple browser support, modifying CSS is not an easy task. It is not unusual that a change that looks fine in one browser will display incorrectly in another browser. Color changes usually have no side effects. On the other hand, margins, padding, floats, and display settings can be difficult to get right.
Updating From Account-Type to Account
One pillar in the Tolven architecture is to avoid, where possible, imposing functional changes unilaterally on an account. (Security, login, and similar system-wide behavior is not included in this approach). For example, Clinic A might be ready to uptake a change on a different day than clinic B. Each can do so at time that is convenient to that account rather than to the system administrator.
Technically, such an upgrade only involves manipulating database data, no software changes are involved. This is because the software is written in such a way that it honors the current configuration whether it is old or new. In other words, the software is upgraded when it is convenient for system administration. An account is upgraded (functionally) when it is convenient for the account administrator and the users of the account.
A quick review of what an account is:
- Accounts are typically a clinic, department, service, practice, or family.
- An account will typically have multiple users
- One user can be a member of more than one account
- The behavior of an account is dependent on its account type (e.g. eCHR, ePHR).
- Tolven's strongest security boundary, including encryption-based security, is enforced between accounts. In other words, information in one account is not accessible from another account.
- Sharing data between accounts requires an "explicit action", by a user of the originating account. For example, if a user wants to authorize a network of emergency rooms to access a summary of their medical record, then that summary is sent to an account representing that pool of ERs. In this way, the owner of the data is not granting access to the data but in fact is giving a copy of the data to the ER network (accompanied by an audit trail of the action).
A user is either logged into a single account or is in the vestibule. The vestibule is where the user selects which account they wish to log into or where they can create a new account. Once the user logs into an account, their experience will be controlled by the configuration for that account. Switching accounts requires a password to avoid a nosy person "backing into" someone's personal health record.
The configuration of accounts is done by account administrators. The user that creates an account is automatically an account administrator. This administrator can:
- Change the account title
- Add new users to the account (currently, the user must already be a Tolven user).
- Remove users from the account (the user's status in other accounts is unaffected)
- Change a user's administrator status
- Set the default time zone for the account
- Set the default language for the account (Tolven currently only offers English)
- Create demo data (clinical accounts only)
- Manage public "Provider" profiles
- Manage exchange agreements between accounts. This controls, for example, if a clinic will allow messages to be received from a Lab department (only partially implemented).
- Update the application to new behavior
- Fine-tune general application displays. For example, enabling or disabling certain menus or changing the order of menus. These settings are not overridden by updates to the application configuration.
Other application-level configuration is not under the control of the account administrator (only that can the administrator can accept or defer updates).
The tolven.properties file contains a number of settings that affect system-wide runtime behavior. The following table lists some of the more interesting settings:
|mail.smtp.host||smtp.mydomain.com||The name of your mail server for sending notifications|
|mail.smtp.auth||false||Does the mail server require authentication|
|mail.debug||false||Should tolven display debug information when connecting to the mail server?|
|tolven.timezone||America/Los_Angeles||Timezone to override the operating system Timezone (this is the default for all accounts unless the account specifies a timezone)|
|tolven.repository.oid||A Unique OID to assign to all messages originated from this instance of the database|
|tolven.login.create.demoUser||true*||Allow "demo" users to be created from the login screen (no activation email is sent)|
|tolven.login.create.activatedUser||true*||Allow activated users to be created from the login screen. (Activation email is required).|
|tolven.register.referenceRequired||false||For a user to create an account, they must provide a special number on the registration screen. For example, an employer or other kind of sponsor might only allow employees to create a tolven account (but the employer does not want to be privy to the account).|
|tolven.register.expiration||3600||If a new user does not respond to their invitation within this number of seconds, the login will be removed thus allowing the user to try again such as when the user provided an incorrect email address. This avoids the need for a system administrator to manually reset the account.|
|tolven.notice.uri||/notice.xhtml||Not usually edited - this page collects notices from a database table and displays them on the login page.|
|tolven.ldap.deleteUser||false||All a user to delete their own account. Technically, the account is simply deactivated so a sys admin can restore it.|
|tolven.gen.patient.max||1000||For demo/training purposes, specifies how many patients a user can create at one time.|
*If both demoUser and activatedUser are set to false, then Tolven will not create users. In this case, users must be created through some other means such as through a corporate LDAP or personnel system.
Each user can control which account they log into automatically after they have been authenticated or if they are given the chance to select which account to log into.
The user can change their own password, set a preferred timezone (if the account timezone is not correct), language, email message preference (HTML or plain text).
The menus for a particular Account (or Account Type) exist in database tables. What this means is that if two or more Tolven installations are configured to reference the same database, then both installations will share the same metadata, menu structure, users and actual instance data.
A tab entry in the menu structure represents a navigation point. Tabs form the basic navigation tree for the application. Internally, Tabs can go to ten levels deep, the Tolven-supplied style sheets only support four levels (Use of four levels of menus is discouraged).
The number of items at any one level is not limited except by the real estate available on browsers. Tolven has found that ten items at any one level is about max.
The logo for the application is specified in the AccountType
A placeholder represents an instance of some entity such as patient or a specific observation. A placeholder is characterized visually by having a close button. In addition the actual contents of the placeholder display is controlled by a small xhtml snippet controlled by the MenuStructure entry for that placeholder. For example, a patient would typically display first, last name, gender and age.
Tolven automatically displays a copy of the placeholder title into the Caption bar of the browser to provide additional assurance that the user is looking at the correct patient.
Portlets are small display that can be "stacked" into a single view. Each portlet is separately defined, queried and updated. Portlets are arranged into a grid pattern.
Lists define a collection of things. Tolven presents all lists as scrollable with no specific size limit. Each column to be displayed is specified in a child table to MenuStructure called MSColumn. Each entry in this table specified the MenuData value(s) to display, the column order, width, alignment, and any drilldown capabilities.
All columns are automatically sortable. A filter is provided automatically. (Rules determine which items are filterable by adding phrases (which do not have to be shown on the screen) to the MenuDataWords table.
Wizards and Drilldowns
A wizard is the form used to create a placeholder instance (patient, observation, allergy, etc).
A drilldown is the read-only form used to display placeholder data. Prior to submission, the drilldown shows what the item will look like after submission. It also shows any errors, if any (see below). If the application reports errors, the wizard cannot be submitted.
Once submitted, the drilldown is a permanent representation for that item (submitted documents are immutable).
Work In Process
Work in process display is handled automatically. The TRIM definition specifies where (and if) a particular item is shown. In the following example, Weight is shown in the Activity Tab. As soon as the weight is either submitted or cancelled, it will be removed from the list automatically. Clicking on the action re-opens the unfinished item.
Tolven can store definitions for clinical content in Templated RIM XML form. Note that a trim instance is structurally identical to a TRIM definition. Of course the content is different. Here is a trim definition for weight. Notice that it specifies the name of the page used to define the wizard itself (this page defines the steps in the wizard and how each step is constructed). And it specifies the drilldown page.
Menu Data contains instances of data defined by MenuStructure "metadata". As such, menu data is not used for configuration. However, in one case, MenuData is actually used to hold trim instances (in other words, configuration data). This is done to take advantage of the fact that one trim definition can sometimes handle many actual clinical concepts.
As an example, look at the diagnosis menu. This list has 68 thousand variations of a single TRIM template. It would be impractical to create separate trim definitions for each diagnosis.
Unlike most lists, selecting an item from the diagnosis list does not drill down to that item but rather it "instantiates" a new placeholder (Diagnosis) within the current "context" in this case a patient and then opens a wizard to complete the submission process.
How Wizard Layouts are referenced by TRIM
A wizard is not accessed directly, via URL. First of all. in Tolven, a wizard is not a freestanding page but in fact is a pane (like an IFrame) managed via AJAX. As with most other elements of the application, it is the application metadata, stored in tables in the database, that determines "what goes where" on the screen.
Without going into a lot of details here, TRIM documents represent the details of everything that will go on in a wizard. Among other things, the TRIM document specifies which wizard layout represents the "user interface" for that TRIM. TRIM templates can belong to one or more applications and if necessary, a different wizard can be associated with each application. For example, the exact same TRIM, say, for a Weight assessment, might go into more details for a clinical application than for a personal/non-clinical application.
Configuring rules is probably the most difficult aspect of configuring a Tolven application. Simply put, when a document is submitted to Tolven, it is asserted into the working memory of the rules specified in the account type for that submission. then, tolven asks the question: "What do you want to do with this submission".
The rules are free to do nothing at all or, as is most common, add items from the submission to various lists.
The details of rules are described in a separate brief. It should suffice to know that rules generally detect patterns in the submission as well as in the existing data. when a condition is met, the rule actions typically call an action such as populating a list. Here is part of the rule that puts an HL7 Observation onto the appropriate list:
Notice that this rule must determine, if the HL7 observation should go on the Tolven observation list or the Tolven diagnosis list (in HL7, both are considered observations). You may also notice that different values are extracted from the observation, depending on the type of observation.
Menu Path Names
In the rule example above, you will see several examples of a path name. These names correspond to the menu hierarchy established by the tabs and placeholders described above. For example,
means the echr application (the root of the menu hierarchy), the patient (placeholder). The diagnosis (placeholder - within patient).
A completely separate rule then says "If I have a placeholder for diagnosis, add it to the diagnosis list".
Notice the "when" condition in #1, consisting of two tests. The first line checks to see if there is a definition of a menu item
The second line of the condition checks to see if there is a placeholder instance, an actual diagnosis.
If both of these conditions are met, then the consequence of the rule is to (#2), place a reference to the placeholder on the diagnosis list using the menu path:
In this path, echr still refrs to the account type, patient still refers to the same placeholder. dx is the Diagnosis tab item and values is the name of a list under the Diagnosis tab.
A simple call is provided (#3) to allow the name of the diagnosis to be indexed in order to find the diagnosis by its name.
The path names used in rules are also used in the browser. If you were to look at the internal representation of items in the browser, they would look nearly identical to these paths. However, they would also have instance identifier embedded. For example,
refers to a specific patient - so rather than meaning a patient in general, the dash and number means that the path refers to a specific patient. Again, all of the actual names used in these paths comes from the MenuStructure configuration. The instance ids are always taken from the primary (surrogate) id assigned to the MenuData item.
A quick reminder: Although not shown, all of this structure is separated by Account. For example, referencing patient-123 doesn't actually allow access to that patient unless that patient is found in the current account, otherwise, a query returns not found. This is important because bad guys could otherwise fiddle with browser-side script to violate security. Tolven prevents that from happening.
Technically, there is only one patient-123 in the system (if the same patient is present in another account, it will have a different internal id). So the account test in queries really is just a safety check. In fact, the 123 itself is completely unique so even the type of data (patient) is not necessary to find the correct instance.
SELECT * FROM MenuData md where md.id = 123
Is all that is needed. However,
SELECT * FROM MenuData md where md.id = 123 AND md.account.id = :account
account is added to prevent a user in one account from trying to access data in another account.
[The preceding is shown for background: Writing queries is not usually required.]
Features that need no Configuration
Lists: All lists are filterable and sortable (ascending and descending) on most columns. For example, there is no need to configure a separate list of patient's sorted by last name or a list of appointments sorted by date because these features are available as part of the main patient list.
Text Size: All Tolven-provided screens automatically honor browser text size settings (both smaller and larger).
Login Page - Any number of notices can be configured into the login screen (viewable before the user logs in). The database tables containing the notices allow each notice to have a start and end time as well as an effective time: Effective on April 13 something will happen, show the message starting April 10, until April 15.
Questions Page - Once the user is logged in, the system can impose questions (text, radio, and checkbox). Answers will be saved for each user. Questions can be imposed at any time such that the next time a user logs in, they will be asked all unanswered questions. Once answered, the questions are not asked again. If there are no unanswered questions, the screen is not displayed at all.
At this time, Tolven does not have much GUI support for configuration. Therefore, as you've seen above, many of the configuration items depend on direct manipulation of XML (TRIM), rules, and database tables (using SQL or a general purpose SQL GUI).
Tolven provides Java and in some cases Web Services APIs for configuring menus, accounts, and account types.
Finally, Tolven provides a skeleton application for configuring metadata called Browse. This is a pure servlet-based application that has examples of navigating some of the available metadata.
- The Tolven Institute
- License Agreement
- Products & Services
- Architecture Briefs
- Frequently Asked Questions
- Useful Links
- Complementary Projects
- Contact Us
Rely on the Tolven support team to help resolve problems during any stage of your application development lifecycle, deployment or implementation.