ADA Documentation

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