Difference between revisions of "ART Template Editor"

(Metadata)
(Creating a link to a template that resides in a BBR)
 
Line 47: Line 47:
  
 
[[File:TemplateEditor-Listdetail.png|250px|right|Template List Detail]]
 
[[File:TemplateEditor-Listdetail.png|250px|right|Template List Detail]]
Once you selected a template from a repository the template is added to your project as a reference. It act as if it was a template in your own project but in fact is "borrowed" from the repository whenever it is used (visualized, used design of other templates, used for schematron generation etc.).
+
Once you selected a template from a repository the template is added to your project as a reference. It acts as if it was a template in your own project but in fact is "borrowed" from the repository whenever it is used (visualized, used design of other templates, used for schematron generation etc.).
  
 
In order to indicate that a template is referenced from a repository rather than a being a project template, a white circle symbol is shown to the left of the template name (instead of a status color as it is shown for templates "owned" by the project).
 
In order to indicate that a template is referenced from a repository rather than a being a project template, a white circle symbol is shown to the left of the template name (instead of a status color as it is shown for templates "owned" by the project).

Latest revision as of 09:21, 8 November 2019

Template Editor Overview

Starting the template editor is done from the ART Template Viewer or the ART Template Associations forms. From those forms you either start a completely new template, create a new version of an existing template, or edit a template. These options are handed as parameters to the Template Editor.

You can only work with the template editor if you are a designated project author.

Template Prototypes

In ART-DECOR, templates are typically created and edited based on so called prototypes. Prototypes are in fact templates in DECOR format but fully derived from an underlying standard (model). The most prominent example is the CDA prototype repository (ad1bbr). It exposes a set of MIF (HL7's model interchange format) derived templates that are used to created new templates, or that helps when editing existing templates by showing all possible template elements and properties as a kind of translucent background model where the designer can choose from.

The figure below shows the original CDA model part, here: encounter (1). All CDA model parts have been transformed into DECOR format templates, so called prototypes (2). This step was done by the ART-DECOR team already and the prototypes are exposed through a Building Block Repository named ad1bbr (see later).

When creating or editing a template (3) the prototype definitions act as a "background" information for the template designer. He decides for example to eliminate optional items (see hl7:text element in the figure) These items are grayed out and may be selected later. Others are shown in black (see hl7:code) as it is selected by the designer to be included in the template design.

Templates Prototypes

Creating a new template

Templates Plus Button

On the left hand side of the template viewer you'll find (up to) four buttons as shown in (1).

Click the TemplateEditor-plusbutton.png button in the Template Viewer. The template editor will open and present a dialog with prototypes to base your new template on. These are taken from the building block repositories referenced in the project.

Prototype Dialog

The prototypes are alphabetically ordered and grouped by classification (1). You can set a filter, e.g. to show only templates of a specific type or the templates of your own project only (2). For all templates you may inspect the meta data (3). Click the prototype you need e.g. CDA Section and click the Select button.

Please note that is some cases also prototypes have multiple versions., in this case all selectable versions are summarized as sub-elements of a prototype.

Prototype Dialog Multiple Versions

From here, editing follows the same pattern as editing an existing template using the rules for a specialization of a template based on that prototype. See section about editing a template.

Information.svg Please note that you need a reference to one of the prototype building block repository (BBR) in your project in order to see prototypes. The simplest way to do so is to add a BBR reference in your project, see Reference a building block repository. A list of prototype BBRs can be found here.

Creating a new version of an existing template

When a template has reached the status 'Active', you can no longer alter it. What you can do is create a new version of it. The Template Viewer will present you with a choice when you click the Edit button on an active template

New Version Dialog

When you choose new version with the same id, it means that any dynamic binding to the selected template will now point to this new version. When you choose new version with different id, no existing bindings to templates are affected.

The Template Editor opens. From here, editing follows the same pattern as editing an existing template using the rules for an adaptation of a template based on that prototype. See section about editing a template.

Creating a link to a template that resides in a BBR

Click the TemplateEditor-linkbutton.png button in the Template Viewer. The template repository browser window will open and present you a dialog with templates that reside in all accessible repositories. These are taken from the building block repositories mentioned in the project.

Repository Dialog

You can enter search terms in the search field (1) and the templates matching the criteria are shown (2) with their names, effective dates, status codes and an abbreviation of the repository they reside. Some meta data details are shown also (3). If a template is already linked to your project, the chain symbol TemplateEditor-linkbutton.png is shown along with the template name (and you cannot select the template again).

Template List Detail

Once you selected a template from a repository the template is added to your project as a reference. It acts as if it was a template in your own project but in fact is "borrowed" from the repository whenever it is used (visualized, used design of other templates, used for schematron generation etc.).

In order to indicate that a template is referenced from a repository rather than a being a project template, a white circle symbol is shown to the left of the template name (instead of a status color as it is shown for templates "owned" by the project). Template from repository

If you display a template that resides in a repository you have the option to edit that template (and by editing it you make a copy to your own project), or to delete the reference to that template. The options are offered through the button list.

Template Ref Button Details

Editing a template

Consider that a template in the editor is one potentially long page that allows editing the meta data like name, display name (1), description (2), classification, reference (3), etc. and the body like example, elements, attributes, choices, includes and their properties (starting at 4).

Editor Metadata Details

Metadata

You can edit the metadata, most of the meta data editing is filling out text and selecting options from the drop down menus. When you have selected a template from a prototype list then you typically have already set a classification for that template, otherwise you can select one.

Editor Metadata Classification

You can add a relationship to another template or model easily.

Editor Metadata Relationship

You may also change the ID of a template. In the editor, the ID is shown within a top right button. By clicking on the ID management button a dialog appears that allows to change the ID of the template.

Editor Metadata ID

Information.svg Be sure that you change IDs of templates with care as it may affect other templates that uses the current ID. Also be sure to change the template id element in the template design of the template in question if the context is * or ** as this is not changed automatically. Not correcting the * or ** context id template element may result in invalid or incorrect validation results.

Design Body

The design body of a template shows all information needed:

  • a hierarchical list of elements and attributes (1)
  • tiny little buttons to add or delete items (2)
  • a popup menu offering you all possible data types in that context (3)
  • cardinality fields to specify minimum and maximum multiplicity as well as the conformance and whether an item is mandatory, denoted as M (4)
  • further conformance statements like value set bindings (5) or containments (6).

Item Element Details

Body Element Editing

When you get to the body of the template you'll notice an action button TemplateEditor-actionbutton.png to the far right with context sensitive options. When you click on the action button a context dependent dialog (see left) appears). When you are working on a specialization for example, you will not get the option of creating new elements that are now part of the prototype. On datatypes you get to option to add attributes/elements that are part of that particular datatype.

In detail most of the actions are self explanatory, only some of them need further explanation.

Add description

Add constraint

A textual further constraint statement on the item

Add properties

A way to add additional properties to certain items, e.g. units or ranges on physical quantity items

Insert text

Adds fixed element content text.

Text

Remove datatype

Add 'contains'

Allows to add a containment of another template, a selection dialog is shown where you can search a template and then select dynamically (1, i.e. refers always to the most recent version) or statically (2, i.e. a specific version).

Containment

Once selected the containment of a template is always shown in this way.

Containment

Insert 'include' into

Adds an inclusion of another template into the current item, a selection dialog is shown

Insert 'include' below

Adds an inclusion of another template below the current item, a selection dialog is shown

Insert 'choice' into

Adds a choice into the current item

Insert 'choice' below

Adds a choice below the current item

Insert example

Please make use of interspersed examples as much as possible at main template level (an overall example) or per element (shows example for an element only).

An example can have a caption (1) and a type (2) like neutral, error, or valid. The latter effects the visualization of the example. On main template level you can add examples too, you even can use the wand (3) to let ART create a draft example for you based on the definitions of the template.

Example

Example

If you example is in error this is indicated by a small error symbol on the lower left.

Example

Insert reference

Adds a reference to the item

Closed

Makes this element defined as closed instead of open

New datatype item

Add let

Adds a new raw schematron let statement

Add assert

Adds a new raw schematron assert statement

Add report

Adds a new raw schematron report statement

Add fixed code

Adds a fixed code to a coded element or attribute

Actions for Fixed Codes

Add vocabulary

Adds a binding to a value set, a selection dialog is shown.

Value Sets

If a certain datatype is specializable into another datatypes or flavors thereof you may select this from the datatype drop menu. In the following figure, there is a flavor II.BSN (Dutch citizen service number) and a flavor II.EPSOS for the main datatype II.

Actions for Datatypes

Please note that if you edit template based on prototypes, the underlying prototype model is always transparently present. Not selected items are shown grayed-out, but you may add items from the prototype at any time by simply click on the add button, or delete items by clicking the minus button.

Edit with protoypes

Saving the template, locks

Saving the template currently closes the Template Editor so intermediate saving and continue work is not possible. However, ART locks the template while you are working on it if you are editing an existing template. If you accidentally have a template locked and want to unlock is go to the Project Tab Status and in the dialog all locked artifacts are shown (and can be deleted).

Template Lock

Changing the status of a template

Once you have created templates, they each have a certain status. If you have started from "draft" you may want to proceed to "active" once your template is ready for use. You can do that by licking on the colored status symbol in the button list right to the template. If you do so, a dialog is provided to change the status, e.g. to "active". Additionally a human readable version label and an expiration date may be added.

Status change

There is a state transition diagram.

State machine

Please note that, once a template has been set to active, you cannot edit it any more. The only thing to make changes is to create a new version of the template (see dialog above) or a new template.