Customising the Standard Web Enactment Interface

Table of Contents

• Overview
• The Mapping File
• Customised Task Pages
• The Folder Hierarchy
• Enacting a Customised Process-Description Over the Web

Overview

The Tallis Web Enactment application dynamically generates standard web pages that take the end-user through a process-description’s component tasks.

In most cases this is adequate, but if required, the standard web pages can be replaced by web pages customised for an individual process-description. Often the ability to use a pre-compiled, customised page would greatly enhance the enactment and user experience. Customised pages enable more control over the layout of enactment web pages and over the way information is present to the user. They provide the ability to add additional functions and tools to complement the process-description, such as images, links to further information and supporting material, widgets and even applets to aid the user during the enactment process. Using standard JSP tag libraries, it is also possible to perform additional functions at the server, such as automated database queries and mail processing.

Customising the standard web enactment interface can involve as little as modifying some task attributes in a XML mapping file. Otherwise, customised pages can be created for specific tasks, supplementing the standard html page with customised content or with an applet. Apart from modifying specific task pages, it is also possible to modify the web application itself. This document provides an introduction to the customisation of standard task pages. For a more detailed account of web-enactment customisation see Tallis Interface Primer.

The Mapping File

Certain PROforma components can be mapped to alternative content via the use of a XML mapping file. The mapping between the alternative content and the enactable process is achieved by binding a definition attribute in the XML to the name of the component in the PROforma content.

The XML mapping file conforms to the ‘http://www.cancerresearchuk.org/acl/proforma/ content#’ schema. If you have downloaded the Tallis Web Enactment suite, you can find the schema in \Apache Software Foundation\Tomcat 5.0\webapps\WEB_APP\WEB-INF\PROforma Content.xsd (or see The Mapping File XML Schema).

File Structure

Guideline Element

The content of the mapping file is contained within the guideline tag:

Task Elements

Five elements can populate the guideline tag: action, decision, enquiry, plan and task (i.e., keystone).

Customisations for each task are defined within task definition tags, which identify the specific task by adding the value of its PROforma Task Name to the definition attribute, e.g.:

A URI attribute, which specifies a specific page of content to be used rather than the automatically generated content, can be added to the task definition tag:

Customisations in a separate file override customisations in the mapping file. For more information about customised task pages see "Customised Task Pages" below.

Another useful attribute that can be added to each task is stylesheet. It specifies a specific style sheet to be used rather than the standard runtime style sheet. Tasks inherit the stylesheet attribute of their parent-plan.

Customising PROforma Entities

The caption and the description of PROforma entities can be modified by using the mapping file.

Caption & Description

The caption tag will override the caption property of a PROforma component.

The description tag will override the description property of a PROforma component.

Both tags MUST be nested within a valid action, decision, enquiry, plan, task, candidate, argument, or source tag. They can contain any valid XML content.

Example:

Customising Tasks

A task’s caption and description can be modified as described above.

Additionally, the task’s context can be modified by using the context tag. The context tag can contain any valid XML content.

Customising Actions

In addition to the base task properties described above, an action’s procedure can be modified by using the procedure tag. The procedure tag can contain any valid XML content.

The delegate attribute of the action tag can be used to group and display a set of actions on one page, by pointing to a specified PROforma plan. This is described in the "Customising Plans" section below.

Customising Enquiries

The mapping file enables users to control the order of the sources displayed for an enquiry and the user interface widget used for each source, and to introduce dependencies between sources.

The enquiry task definition tag can contain a sources tag – which contains at least one source tag – and one or more dependency tags.

The delegate attribute of the enquiry tag can be used to group and display a set of enquiries on one page, by pointing to a specified PROforma plan. This is described in the "Customising Plans" section below.

Source Tag

The source tag has three attributes:

• definition – identifies a PROforma source by its Name value
• position – an integer which defines the position of the source on the page, according to the following order:
• 
• dropdown – determines whether the source values are displayed using radio-buttons (or checkboxes in the case of multiple selection of values) or a dropdown list. By default, checkboxes or radio-buttons are used (dropdown=false).

Example:

On the left is the default screen layout; on the right is the screen layout using the above mapping file customisation.

Dependency Tag

This tag determines dependencies between sources. The tag defines a source attribute and a keyword value for that source, for which the nested source would be disabled, e.g.:

The pregnancy source is disabled if the male value is selected for the sex source.

Customising Decisions

If a decision has sources, it can be customised just like an enquiry (see "Customising Enquiries" above). Additionally, captions and descriptions of decisions, candidates and arguments can be modified using the relevant tags (see "Customising PROforma Entities" above).

Each decision tag can have one candidates tag. This tag must contain at least one candidate tag. A candidate tag can contain one arguments tag. This tag must contain at least one argument tag.

The maxRecommendations attribute of the decision tag can be used to determine the maximum number of candidates to be presented to the end-user as recommended, irrespective of how many are actually recommended by the enactment engine.

Example:

Note: In the current version of Tallis Composer (1.4) arguments do not have a Name field. Instead, the argument’s condition is automatically entered as argument name in the PROforma definition. This makes the use of the argument tag cumbersome and error-prone.

Customising Plans

The plan has to point to a customised plan page that will display the multiple enquiries (if you have downloaded the Tallis Web Enactment suite, you can find a customised plan page for enquiries (enquiryGroup.jsp) and one for actions (actionGroup.jsp) in \Apache Software Foundation\Tomcat 5.0\webapps\WEB_ APP\customisations\pages\).

Example:

Location

The mapping file has to be placed within the web enactment application folder, e.g.:

webapps/tallis/MappingFile.xml

or

webapps/tallis/customisations/mappings/MappingFile.xml

Pointing to the Mapping File

The customised process-description has to point to the mapping file. This is done via the Context field of the top-level plan.

In the Context field of the top-level plan type:

#metadata
tallis.content = PATH_TO_MAPPING_FILE

The path is relative to the web application, e.g:

#metadata
tallis.content = /customisations/mappings/mappingFile.xml

Customised Task Pages

Although most customisations can be done using the mapping file, there are several cases where it is advisable to use separate customised task pages:

• When adding dynamic content, as this can only be achieved via a jsp file.
• When there are many customised tasks, each with a lot of content, as the mapping file can become large and less efficient both in terms of editing and in terms of running the process.

Creating a Customised Task Page

The Tallis Web Enactment application dynamically creates standard web pages for tasks that don’t have the mappings to specify alternative content. The HTML code of these pages can be saved, edited and reused by Tallis during future enactments of the process-description.

Follow the steps below to use the dynamically generated code produced by the Tallis Web Enactment application:

• Start the enactment process: Run through the guideline until you reach the task you wish to associate with customised content.
• Capture the generated code: Right-click on the page in question and select ‘view-source’.
• The dynamically generated content for each task is created within the following comment tags to allow ease of location:
• <!-- start of automatically generated content -->
• generated content
• <!-- end of automatically generated content -->
• Copy the html between the comment tags and save the resulting text.
• Edit the generated code and save it: The new file MUST be accessible to the Tallis web-application you wish to run. This does not mean that the file must be contained within the Tomcat installation, only that it can be delivered via HTTP.
• Edit the mapping file: The customised page has to be specified in the mapping file, using the URI attribute of the task tag (see "Task Elements" in "The Mapping File" above).
• Edit the PROforma process-description: Add the necessary context properties to the top-level plan (the mapping file has to be located and pointed to as described in "Location" and "Pointing to the Mapping File" in "The Mapping File" above).

When creating a separate customised task page, it’s best to use jsp files as they are less likely to cause errors.

Customisations in a separate task file override customisations in the mapping file.

Required Content for Customised Task Pages

Specific information is required by the server for a task to be processed, with different task types requiring different information for a request to be successful. If minimal editing of the automatically generated content is performed (e.g., structural changes to layout), this is generally not an issue. However, if the content is significantly altered or has been built from scratch, this additional information may need to be explicitly managed.

Actions, plans and keystone tasks

The web enactment generates a "hidden" form for these task types, which will contain all the information required by the server for the correct processing of the task in question. No HTML form or extra content management is required.

Decisions

A decision is required to submit which candidate(s) the user wishes to commit for the task to be successfully processed. Care must be taken not to change the field names that are generated (HTML input and select tags).

If the decision is also authored to request specific dataitems, these fields will also need to be managed (see "Enquiries" below for further details).

Enquiries

An enquiry is required to submit values for dataitems marked as mandatory for the task to be successfully processed. Care must be taken not to change the field names that are generated (HTML input and select tags).

The Folder Hierarchy

If you have installed the Tallis Web Enactment suite, you will find the following folders in the Apache Software Foundation directory:

• webapps
  • tallis (or another web enactment application folder)
    • customisations
    • Files for customising the web enactment of specific process-descriptions
      • mappings
      • It is recommended to place your mapping files in this directory
      • pages
      • It is recommended to place your customised task pages in this directory
      • scripts
      • It is recommended to place your customised scripts in this directory
      • stylesheets
      • It is recommended to place your customised style sheets in this directory
    • runtime
    • JSP files for general layout and for specific components of the web application;
      These files can be used to modify the content and the look & feel of the entire web enactment application
      • captions
      • JSP files for captions
      • confirmations
      • JSP files for confirmations
      • contents
      • JSP files for contents
      • footer
      • JSP files for the footer
      • headers
      • JSP files for headers
      • images
      • Images for the web enactment application
      • menus
      • JSP files for menus
      • scripts
      • Scripts for the web enactment application
      • stylesheets
      • Style sheets for the web enactment application

Enacting a Customised Process-Description Over the Web

Standard process-descriptions can be enacted over the web using the ACL server repository. In order to run a customised process-description over the web, the mapping file must be placed within the web application folder, and the customised pages (if there are any) must be accessible via HTTP. As this type of content can contain malicious code, placing such files on the ACL server cannot be done directly. Hence, if you want to enact a customised process-description over the web, either use your own server, or contact us.