ADA Documentation

Revision as of 11:26, 13 May 2014 by Mdegraauw (talk | contribs) (→‎ADA XML Schema)

This chapter contains a walkthrough of ADA, for those who want to get up to speed building and deploying ADA apps.

Installing ADA

To get started with the examples, you'll need ADA Core checked out to a local directory. Either get it from SourceForge, or install the ADA package in eXist and copy that to disk.

Start with this layout: 

 - ada
   - core (for ada/core)
   - projects
     - my-project (we'll use demo1 in this Guide)
       - definitions
       - modules
       - new
       - schemas
       - views
       - xslt

After downloading ADA, ada/projects/empty contains the layout to get you started.

ADA Applications

ADA starts with a DECOR release, as made in the ART project form. Make one (or refer to an existing one), and retrieve the URI to it through: http://localhost:8877/decor/services/ProjectIndex (Throughout this Guide, we'll use localhost:8877 for the host - use another if you don't run a local instance on port 8877). Search for your project, and get an URL like this one: http://localhost:8877/decor/services/RetrieveTransaction?id=2.16.840.1.113883.3.1937.99.62.3.4.2&language=en-US&version=2014-05-12T14:02:55&format=xml

With RetrieveTransaction, a decor/transaction is 'enhanced' with all the goodies the dataset and terminology provide. It is:

  • a decor transaction
  • with the tree view from the dataset
  • all concept adornments (names, valueDomains, you name it) from the dataset
  • for every valueDomain of type 'code', the relevant valueSet pulled in
  • and all this filtered for just one particular language so you don't need to worry about stuff you don't need to worry about.

ADA Definitions

Now make an ADA definition file in /projects/my-project/definitions and call it demoapp-ada.xml. Here's an overview of the structure. 

<?xml version="1.0" encoding="UTF-8"?>
<ada ...>
    <project ...>
        <release ...>
    </project>
    <applications>
        <application ...>
            <views>
                <view ...>
                    <name>...</name>
                    <concepts include="all">
                        <concept ...>
                        <concept ...>
                    </concepts>
                </view>
            </views>
        </application>
    </applications>
</ada>

The root is called /ada, below are:

project

<project prefix="demoapp-" language="en-US" versionDate="2014-05-12T14:02:55">
     <release baseUri="http://localhost:8877/decor/services/RetrieveTransaction"/>
</project>

Change the following:

  • set project/@prefix to a memorable project prefix (lowercase letters and digits only, end with a hyphen)
  • set project/@language to the language from the RetrieveTransaction link
  • set project/@versionDate to the date from the RetrieveTransaction link

ADA retrieves all necessary information from the RetrieveTransaction service. Make sure this is OK (like, all names for the required language are provided, valueSets are present in the concepts etc.).

If not all is present - ADA is a really good way to test the completeness of your DECOR specs. Just generate an ADA app, run it and see what's missing.

application

Next comes a bit of housekeeping. 

<applications>
    <application version="1">
        <views>
            <view ...>
            </view>
        </views>
    </application>
</applications>

Except the application/@version this is just a way to get you to where it really happens: the view. An ADA view is - basically - an enhanced version of the RetrieveTransaction output, just like RetrieveTransaction itself is an enhanced version of a DECOR transaction. The ADA view allows you to add in UI necessities:

  • widgets
  • tabs
  • links between views (such as an index which points to detail views)
  • and more, and still more to come.

view

The ADA view is where it all happens. Views need:

  • a view/@type (we'll use 'crud' and 'index' in this walkthrough)
  • a view/@target (for which we'll explore 'xforms' and 'xquery' - html is another obvious candidate)
  • a view/@transactionId and view/@transactionEffectiveDate (this of course identifies the correspondig DECOR transaction)
  • a view/name (which is shown in the browser)
  • one or more view/concepts. concepts come in two flavors:
    • concepts include='all' (All concepts in the DECOR transaction are shown. No concept children are needed, unless you want special processing for those.)
    • concepts include='only' (No concepts in the DECOR transaction are shown, except the children of <concepts>.)
  • concept/@ref points to a DECOR concept from the DECOR transaction
  • concept/@widget is used for UI specials (In this example, we'll create two tabs - of course, for a tabbed view, you might want to choose concepts groups on the same depth in the DECOR dataset tree.)

This view will constitute the main CRUD view to edit or create instances of this particular transaction. The transaction below is a 'measurement form', where a patient can periodically submit weight measurements to a registry (the example is meant to show all main DECOR constructs, and is admittedly somewhat artificial). 

<view type="crud" target="xforms" 
    transactionId="2.16.840.1.113883.3.1937.99.62.3.4.2" 
    transactionEffectiveDate="2012-09-05T16:59:35">
    <name>Measurement Form</name>
    <concepts include="all">
        <concept ref="2.16.840.1.113883.3.1937.99.62.3.2.1" widget="tab"/>
        <concept ref="2.16.840.1.113883.3.1937.99.62.3.2.6" widget="tab"/>
    </concepts>
</view>

We'll make a second view, since we'll need an index of all weight measurements for lookups and edits. We'll list the concepts we want shown in the index (name and date of measurement, here). 

<view type="index" target="xquery"
    transactionId="2.16.840.1.113883.3.1937.99.62.3.4.2" 
    transactionEffectiveDate="2012-09-05T16:59:35">
    <name>Metingen Lijst</name>
    <concepts include="only">
        <concept ref="2.16.840.1.113883.3.1937.99.62.3.2.4"/>
        <concept ref="2.16.840.1.113883.3.1937.99.62.3.2.2"/>
    </concepts>
</view>

That's all it takes to define an app! Now it's time for the ADA magic to happen.

Making an ADA release

The next step is to execute some of the ADA stylesheets. Use ada2release.xsl to transform the ADA definitions to a release: 

 demoapp-ada.xml -> [ada2release.xsl] -> demoapp-ada-release.xml

This process pulls in all the information from RetrieveTransaction and combines it with the UI logic from ADA. 

<view id="1" type="crud" target="xforms"
  transactionId="2.16.840.1.113883.3.1937.99.62.3.4.2" 
  transactionEffectiveDate="2012-09-05T16:59:35">
    <name>Measurement Form</name>
    <implementation shortName="measurement_form"/>
    <dataset id="2.16.840.1.113883.3.1937.99.62.3.1.1" 
      effectiveDate="2012-05-30T11:32:36" statusCode="draft"
      transactionId="2.16.840.1.113883.3.1937.99.62.3.4.2" 
      transactionEffectiveDate="2012-09-05T16:59:35" 
      shortName="measurement_message">
      <concept minimumMultiplicity="0" maximumMultiplicity="*" 
        conformance="" isMandatory="false" 
        id="2.16.840.1.113883.3.1937.99.62.3.2.1"
        statusCode="draft" effectiveDate="2012-05-30T11:32:36" 
        type="group" widget="tab">
        <name language="en-US">Measurement</name>
        <desc language="en-US">Measurement of body weight on a specific date</desc>
        <implementation shortName="measurement" 
          xpath="/hl7:registrationProcess/hl7:organizer"/>

It still looks a lot like an ADA definition, with:

  • a <dataset> element where <concepts> was
  • implementation elements with
    • a @shortName, which is used for (amongst others) XML element names
    • an @xpath expression which shows where this concept resides in a HL7 document (only if all templates and templateAssociations are present).
  • all other information from dataset/concept and transaction/concept
  • plus the ADA such as @widget

Generating an ADA App

The next step is convert demoapp-ada-release.xml to the necessary schemas, forms and other resources 

 demoapp-ada-release.xml -> [release2newxml.xsl] -> empty XML
 demoapp-ada-release.xml -> [release2schema.xsl] -> XML Schema
 demoapp-ada-release.xml -> [release2xform.xsl]  -> XForms
 demoapp-ada-release.xml -> [release2xquery.xsl] -> XQuery modules

The ADA XML format

The first transform generates an empty ADA XML instance in ada/projects/demoapp/new. 

<?xml version="1.0" encoding="UTF-8"?>
<!--New XML generator, 2014-05-13T13:17:04.038+02:00-->
<measurement_message id="new" app="demoapp"
  transactionRef="2.16.840.1.113883.3.1937.99.62.3.4.2" 
  transactionEffectiveDate="2012-09-05T16:59:35"
  versionDate="2014-05-13T13:16:14" 
  prefix="demoapp-" language="en-US">
   <measurement conceptId="2.16.840.1.113883.3.1937.99.62.3.2.1">
      <weight conceptId="2.16.840.1.113883.3.1937.99.62.3.2.3" value="" unit="kg"/>
      <weight_gain conceptId="2.16.840.1.113883.3.1937.99.62.3.2.13" value="false"/>
      <weight_gain_data conceptId="2.16.840.1.113883.3.1937.99.62.3.2.18">
         <amount_of_weight_gain conceptId="2.16.840.1.113883.3.1937.99.62.3.2.19" value="" unit="gram"/>
         <cause_of_weight_gain conceptId="2.16.840.1.113883.3.1937.99.62.3.2.20" value=""/>
      </weight_gain_data>
      <datetime conceptId="2.16.840.1.113883.3.1937.99.62.3.2.2" value=""/>
      <measured_by conceptId="2.16.840.1.113883.3.1937.99.62.3.2.5" value="1"/>
      <remarks conceptId="2.16.840.1.113883.3.1937.99.62.3.2.17" value=""/>
   </measurement>
   <person conceptId="2.16.840.1.113883.3.1937.99.62.3.2.6">
      <name conceptId="2.16.840.1.113883.3.1937.99.62.3.2.4" value=""/>
      <bsn conceptId="2.16.840.1.113883.3.1937.99.62.3.2.7" value=""/>
      <date_of_birth conceptId="2.16.840.1.113883.3.1937.99.62.3.2.8" value=""/>
      <length conceptId="2.16.840.1.113883.3.1937.99.62.3.2.15" value="" unit="m"/>
   </person>
</measurement_message>

The ADA XML is a very straightforward XML format. It's design principles are readability, conciseness and following the dataset as closely as possible. It has:

  • an XML element name taken from @shortName (since shortName discards spaces and most special characters, and is all lowercase, DECOR concept names must yield unique shortNames for ADA to work)
  • the tree structure of the dataset, making it easy to navigate
  • an optional conceptId (it may be absent since it can be calculated from the ADA release info, if needed)
  • a @value attribute containing the entered value
  • a @unit attribute for quantities

ADA XML Schema

There are now two schemas: 

 ada/projects/demoapp/schemas/measurement_message-draft.xsd
 ada/projects/demoapp/schemas/measurement_message.xsd

Both schemas validate the ADA XML format for measurement_message. The 'draft' version allows incomplete data to be stored in the database, i.e. when someone is filling out a complex form and wants to store it for later completion. A draft schema will allow @value and @unit to be absent on all nodes, even when mandatory in the transaction. The other schema checks all constraints from the dataset and scenario.

ADA Views and Modules

Our two views are stored in: 

 ada/projects/demoapp/modules/index.xquery
 ada/projects/demoapp/forms/measurement_form.xhtml

We'll see those in action soon.

Deploying an ADA App

Retrieved from "https://wiki.art-decor.org/index.php?title=ADA_Documentation&oldid=1270"