Overview Sections:  Overview of Architecture*  |   Service Anatomy  |   Service Families  |   Accessing Application Variables

Detailed Architectures:  Core*  |   Validation  |   ID Generation  |   Ontologies  |   Meta Data  |   Functional Specs  |   Alerts  |   Plugins
* If you are looking at this documentation for the first time, we recommend you start here for each section.


Architecture for Alerts

Alerts can be used to notify users when certain data of interest are present.


Alerts Architecture Diagram for Project35


Alerts Scenario

  1. End users can create a list of alert bundles they want associated with the application. The alerts are created by the Alerts Editor and these are stored as ZIP files.
  2. End users can reference these ZIP files through a feature provided by the Form Generation System. The alerts bundles are actually triggered when the document is validated (see Validation), either through an explicit request to show errors or a request to export the current data set to a final submission format. Both of these requests are triggered via the Form Generation System.
  3. If any alerts bundles have been registered by the end user the validation activity is extended to scan the document for patterens described in the alerts. Any combinations of field values that match an alert are flagged according to the nature of the alert that has been specified.
  4. If the nature of the alert is an error then this can block exporting to final submission format. In this way, the alerts sytem supplements normal validation activities.


Key Reference Sections

Form Generation System  |   Alerts System  |   Alerts Bundles  |   Alerts Editor

Each section is structured to address purpose, description, design considerations, scope of effect, and relevant code packages.


Alerts as Different from Validation

The Alerts System is not the same as Validation. Validation activities take place as a result of comparing field values with the parameters of a particular field. For example, checking that an integer field has an integer field value or that date field values are in the correct field value. For an alert, flags that are set are more for field values that may be legitmate on their own but incorrect in combination with other field values.

The nature of an alert being flagged as an error is to prevent to form from being exported to final submission format. There ar more consequences of an error occuring due to validation. Failures of validation are all errors, whereas alerts may be classified for informational purposes as well. Alerts are meant to supplement validation activities.


Reference Sections for Alerts

Form Generation System

Purpose To generate UIs for Project35 which suite displays on desktop and Tablet PCs.


Description Project35's architecture maintains a rigid separation between the structures that hold data and the structures that present them to an end-user. The model aspects are represented by the native data structures, the description of which can be found in the Core Architecture section. The view aspects are represented by the following packages:
  • project35.desktopDeployment
  • project35.tabletDeployment

General Classes for Generating Desktop Project35 Forms

When end-users invoke the "run_project35" script, it spawns an instance of Project35Application. The object prompts end-users to load a model and it produces template record definitions that can be used to populate a document.

  • Project35Application creates an instance of an empty Project35Dialog, which is the main window for the data entry tool;
  • Project35Dialog has three major UI components: Project35MenuBar, NavigationTree, and RecordView;
  • Project35MenuBar containing a variety of menus subclassed from Project35Menu;
  • Project35Menu contains general-purpose code for handling plugins;
  • NavigationTree is the tree display that appears on the left part of the window. This manages a tree of NavigationTreeNode objects that mirror the tree of RecordModel objects, which comprise the document;
  • RecordView comprises a RecordViewTitle, which appears flushed left at the top of the panel, and a collection of DataFieldView objects, which render form fields;
  • DataFieldView objects all use a corresponding DataFieldModel object that is part of the currently selected RecordModel object.

General Class Relationship Diagram for Generating Desktop Project35 Forms


Classes for Generating Edit Fields in Desktop Project35 Forms

  • EditFieldView contains code which can render properties of a corresponding EditFieldModel object. It is responsible for rendering a "Plugins" button for any form field that has been associated with a collection of plugins. The other field view classes use properties defined in corresponding edit field model objects.
  • RadioFieldView uses the choices provided by GroupFieldModel to render a group of radio buttons. If GroupFieldModel provides more than three choices, Project35 uses a CombinationFieldView to render the items as a drop-down list.
  • URIFieldViews use TextFieldModel objects whose XML Schema definitions used "xs:anyType" for the type attribute (See EditFieldModel Properties).
  • IDFieldView uses an instance of IDFieldModel to render a text field that is accompanied by a "Generate Key" button.
  • The identifier service used to provide an identifier is a property of the IDFieldModel.

Class Relationship Diagram for Rendering Edit Fields in Desktop Project35


Classes for Generating List Fields in Desktop Project35 Forms

  • ListFieldView comprises a ListTypeManager, a ListValueManager and it uses an instance of ListFieldModel.
  • ListTypeManager manages the type of child record that will be created or edited when end-users press "New" or "Edit" buttons. There are implementations of ListTypeManager that accommodate lists that support one or multiple types.
  • MultiListTypeManager renders a combination box populated with the kinds of records that can appear in the list field.
  • ListValueManager is an abstract class that manages the display of list items.
  • SingleListValueManager represents a one item list as a single non-editable text field that shows the display name of the child record.
  • MultiListValueManager shows the child records in a scrollable list of record names.
  • project35.desktopDeployment.RecordViewFactory creates list fields. It determines the type of list field to produce by inspecting the fieldViewType attribute of the ListModel object.

Class Relationship Diagram for Rendering List Fields in Desktop Project35


Classes for Generating Forms in Tablet Project35

TabletProject35 was designed to support the same data models as those used to run Desktop Project35. However, we envisioned that different forms of deployment would be used at different stages of editing the same document. End-users will tend to use TabletProject35 to do simple data entry tasks which require them to be at a work site such as a laboratory or a remote field location. They will tend to use Desktop Project35 to support complex data entry tasks and to fill in the rest of the document.

TabletProject35 was designed with the following principles in mind:

  • minimise the feature set of the application to support essential tasks
  • minimise the use of pop-up dialogs
  • economise on screen real estate
  • change features which rely on right-menu clicks.

The classes used to generate forms in Tablet Project35 are in the project35.tabletDeployment package. Many of them share the same name as other classes that cater to supporting Desktop Project35. There are a few notable differences.

First, some of the menu items have been removed. For example, the File Menu does not contain an "Export to Final Submission Format" button. This feature was deemed non-essential because it was likely this would be done with the Desktop version.

To reduce the number of pop-up dialogs, some features were altered so they used a stack of screens instead of separate windows. For example, consider the "Window" feature in Desktop Project35. When end-users switch from one file to another, a new window grabs focus. In Tablet Project35, only one file is shown at a time. When end-users change the current file, it changes the file loaded in the current window.

As another example, the DefaultOntologyViewer was altered so it relied on JPanel objects instead of JDialog objects. This was done so the ontology viewer was more easily embedded in a stack of windows.

To economise on screen real estate, the NavigationTree was removed. It is accessible via the "Where Am I" button, which pushes a view of the NavigationTree onto the stack of windows. TabletProject35 supports navigation via a RecordStack object. RecordStack is a drop down list that shows the currently edited branch of the tree.

Finally, the right click mechanism for activating ontology services is replaced by pressing a "Mark-up" button which appears at the end of a text field.



Design Considerations

Initially, Project35 tightly coupled data objects with the objects that viewed them. This led to severe performance problems because Java would potentially be managing thousands of UI components, each using a collection of Swing objects. This led to stripping the native data structures of references to UI components. Eventually the production of form field views was centralised in the class project35.desktopDeployment.RecordViewFactory.

The most significant change in the form generation classes came when Tablet Project35 was developed. Initially we wanted to run the software on a PDA. However, these devices often require a specialised form of the JVM which does not support Swing components. Although the native data structures were stripped of references to UI components, they still had one crucial reference to the swing libraries: the ChangeListener class. We realised it would not be easy to port the code base to a PDA platform so instead we decided on a Tablet PC platform.

It became clear that we had to make some changes to the forms. The Navigation Tree was taking up too much room in the display and it was difficult to tap a pen on some of the nodes. Too many windows popped up and they cluttered the screen area. We also observed that it was difficult to activate ontology services. In the Tablet display, a right-click action is done by tapping and holding the pen on a form label. This seemed too awkward to do, so a "Mark up" button was developed instead.

The development of TabletProject35 took 3 consultation meetings with mass spectrometer scientist Jennifer Lynch and ten business days of coding. The result proved that Project35's design isolated its model aspects enough to develop new ways of visualising them.



Scope of Effect The UI classes are probably not used by anything other than classes in Desktop and Tablet deployment packages.


Relevant Code Packages The classes used to generate user interfaces in Project35 are in the project35.desktopDeployment and project35.tabletDeployment packages.

Back to top


Alerts System

Purpose To provide a means of allowing end-users to compile their own lists of errors, warnings and tips that can be used by other researchers in the community when they validate their data sets. It is intended as an extensible way to enhance validation facilities of the tool and a passive way that researchers can communicate with each other.


Description

Project35 supports an Alerts System to supplement the toolís standard validation facilities and to allow end-users a way of using advice provided by other end-users. An alert is a set of matching criteria which identifies patterns of field value combinations in a record. The matching criteria can be associated with one of four intents:

  • Error;
  • Warning;
  • Information bulletin;
  • Request for the user to contact someone else.

Domain experts can use the Project35 Alerts Editor to create a collection of alerts called an Alert Bundle. The bundle is a ZIP file that contains a small XML file to represent each alert. The alert bundles can be included as part of the release of a new model folder, or they can be hosted at some URL. Other end-users can import these alert bundles and use them in two situations:

  • They attempt to export the document to a final submission format;
  • User uses the "Show Errors" feature in the View Menu.

When either of these actions are taken, the tool scans the current document and identifies any records which match an alert. The results are included with any errors the system identifies in the document. Should any of the alerts represent errors, then the task of exporting data to a final format will fail.



Design Considerations

The Alert system was originally developed because Project35 had no way of identifying errors which were due to combinations of field values found within the same record. Individual field values could be validated but they could still present errors when they were considered in conjunction with other field values on the same form. For example, a patient record form could have fields "gender" and "cancer type". "male" and "ovarian cancer" could represent legal values for their respective fields but represent an illegal combination of values. The system was generalised to include warnings and other kinds of messages that might prove useful in an activity of standardised data entry.

Now that Project35 supports field validation services and general plugins at the field, record and document levels of data entry activity, it is unclear whether this system will become more popular. The Project35 Alerts system is limited in that it will only identify patterns of values found within the same record. However, the system allows end-users to enhance the toolís validation capabilities without having to code plugins. This benefit may prove important in settings where there is a scarce availability of software developers to make validation plugins.

Project35ís validation package has been modified so that validation routines return a collection of alerts rather than a String that could contain an error message. This was done to allow validation plugins to return results that reflected different kinds of data quality.



Scope of Effect

The Alerts package is becoming more intertwined with the Validation package. Validation services described in the project35.soa.validation package are required to return a collection of Alerts when they validate a field, record or document. Many of the error messages thrown by parts of the system are encapsulated in a SystemErrorAlert(..) object, which is an instance of an Alert.



Relevant Code Packages

Most of the classes used to support alerts functionality are found in the project35.soa.alerts package. The Alerts Editor can be run by invoking project35.desktopDeployment.Project35Alerts.

Back to top


Alerts Bundles

Purpose These are to record associations between collections of field values in a given type of record and an intent, which may be a warning, an error, an information bulletin, or a request for information by someone.


Description Alerts Bundles are zipped series of XML files that record associations between collections of field values in a given type of record and an intent, which may be a warning, an error, an information bulletin, or a request for information by someone. The only thing that is really blocked is exporting to final submission format.


Design Considerations Something was needed that represented a collection of alerts. Some means of serialising alerts as a series of xml files that are contained within a ZIP file.


Scope of Effect Only within the Alerts System and Alerts Editor.


Relevant Code Packages project35.soa.alerts contains the following: code for the Alerts Editor, a data container class Alert, and serialisation routines for writing the alerts.

Back to top


Alerts Editor

Purpose To provide domain experts a means of codifying their expertise in a way which could be used to electronically identify combinations of field values within someone else's documents.


Description Project35 has an editor that allows domain experts to specify alerts which can be incorporated as part of the software's feature for checking errors in a document.

An alert is an association between a set of field matching criteria on the same form and one of the following intents:

  • An error;
  • A warning;
  • An information bulletin;
  • A request for further contact.

For examples of alerts, first consider a form "patient" which has fields "gender" and "cancer_type". An alert could specify that the combination of values "gender=male" and "cancer_type=ovarian cancer" is an error. A warning alert might be that a combination of drugs used in a diagnosis is known to have undesirable side effects. An information bulletin alert might associate the make and version of a laboratory machine with a notice that some aspect of the device should be upgraded. A request alert for further information could associate a combination of medical symptoms with a request to contact some researcher who is doing a related clinical study.

Groups of domain experts use the editor to create a collection of alerts known as an alert bundle. Each bundle is a *.ZIP file that contains a small XML file for each alert. Alert bundles can be managed on the same local machine as the Project35 installation or be managed on a web page managed by some remote server.

Document authors can reference one or more alert bundles. When they attempt to validate the current document, Project35 scans for records which match patterns described by the alerts.

The editor is invoked by a call to project35.desktopDeployment.Project35Alerts. This class allows the end-user to select a data entry model. When the editor appears, users can create alerts using combinations of values for record fields that have been defined in the model.

The Project35 Alerts Editor

The dialog is represented by an instance of Project35AlertsEditor. Each dialog comprises two major parts:

  • AlertsTreePanel - manages a tree of alerts organised into categories for each intent.
  • AlertEditingPanel - provides fields for describing the nature of the alert and an instance of MatchingCriteriaView, which lets users specify combinations of field values.

Each Alert that is created is a combination of the intent and an instance of the data container class MatchingCriteria. During serialisation of an alerts bundle, each alert is written to a separate XML file within a ZIP file.



Design Considerations The Project35 Alerts Editor was developed to allow domain experts to create validation services in a way that did not involve writing code. The alerts could be created by multiple curation groups and made available to multiple document authors via URLs for alert bundle ZIP files.


Scope of Effect

Most changes made to the Alerts Editor should only impact code found in package project35.metaData. Note that MatchingCriteriaView and MatchingCriteria are used in both the Alerts Editor and in the advanced search feature that is supported in the generated data entry tools.



Relevant Code Packages

The main() class which starts the Project35 Alerts Editor is project35.desktopDeployment.Project35Alerts. The rest of the code that supports the editor is located in package project35.soa.alerts.

Back to top