DTS Export Module User Guide
Version 1.2
Introduction
The DTS Export Module is a DTS 4 plug-in Module that supports printing
and exporting of DTS Concept data. Exporting to delimited-text and Excel files
are supported. Concepts to be exported are simply dragged from other DTS Editor
panels and dropped into the Export Module’s floating panel. User-defined export
Profiles specify the Concept attributes to be written. The Export Module satisfies
many simple export requirements. For more sophisticated exports, including
programmatic operation, see the Terminology Query Language (TQL) Module.
Installation
Extract the files in ExportModule-1.2.zip into your DTSInstall directory. Be sure the Use folder names box is checked. This will place all the Excel Module files into the appropriate folders:
Folder Files
DTSInstall\bin\export Default Profile.exp
DTSInstall\lib\modules exportmodule.jar
xmldigester.jar
pluginutils.jar
poi-3.6-20091214.jar
poi-ooxml-3.6-20091214.jar
poi-ooxml-schemas-3.6-20091214.jar
xmlbeans-2.3.0.jar
DTSInstall\docs exportmoduleuserguide.pdf
DTSInstall\docs\help exportmoduleuserguide.htm
Running the Export Module
The Export Module is run by selecting the New Export Panel option
in the DTS Editor Tools menu or the Export icon
Using the DTS Export Module
After selecting the New Export Panel DTS Editor menu option (or the Export Module icon), the Export Module dialog will be opened. As shown in the screen shot below, this dialog consists of a tabbed panel with two tabs: Export and Profiles. The sections below describe the options available in each tab.
Exporting Concept Data
This section describes the steps to be followed to perform an export. For instructions on specifying the contents of the export, see Managing Export Profiles.
Preparing for Export
To perform Concept exports, select the Export tab. The export panel (see screen shot above) consists of a set of export parameter fields and a drop panel for Namespaces, Subsets, and Concepts. The fields specify options for the export:
Export Profile The format (set of attributes) that is used in an export is defined by an Export Profile. Select the desired Profile for an export from the combo box. Profiles are described in detail in the Managing Export Profiles section below.
Title String Enter an optional “title” string for the export. For file exports, if this value is not empty, the title string is exported as the first (and only) field in the first record. The title is exported before any header record. For print exports, the value is used as the print page header.
Export to File If this radio button is selected, export will be directed to a file. Enter the path and name of the export file (.txt, .xls or .xlsx) in the field, or click the Browse button to search the file hierarchy. If an extension is not specified, .txt is added.
Export to Printer If this radio button is selected, export will be written to a printer. After the Export button is pressed (see below), a printer dialog will be shown to select the target print device.
Selecting Concepts
The Concepts to be exported are listed in the main (drop) panel of the Export tab. Concepts can be dragged to this list from other DTS Editor panels such as the Tree Viewer, Search Panel, Details Panel, etc. Remember that Concepts are dragged with their Snapshot Dates. Each Concept is displayed with its Namespace and associated Version name (see screen shot below).
Namespaces, Namespace Versions, Subsets, and Subset Versions can also be dropped. Namespaces and Subsets are considered to be dropped with their most recent versions. On export, the constituent Concepts in these objects will be included in the export. The screen shot below shows an example Export panel with four Concepts, a Namespace and a Subset.
Drop list entries are exported in the order in which they appear in the drop panel list. This order can set/modified in three ways:
1. When an object is dragged into the panel, the list shows an “insert bar” as the cursor is moved over the existing items. The new object can be dropped anywhere in the list.
2. Objects in the drop list can be dragged to other panels, including the drop panel. When the drop is to a different panel from the drop panel, a “copy” operation is performed, i.e., the object is retained in the drop list. If the drop is to the drop panel itself, a “move” operation is performed.
3. The objects in the drop list can be sorted using the panel’s Sort button. See Export Actions below.
Drop list objects can also be modified via a right-click “context” menu associated with each export object. Any entry can be removed from the drop list by selecting the Remove item in the menu. Concept objects also have additional Modifier options. These Modifiers cause Concepts related to the base Concept to be included in the export. Mouse-over Change Modifier to: in the context menu and select the desired Modifier. The available Modifiers are:
ONLY Only the designated Concept is included in the export. This is the default Modifier. No notation for ONLY is shown in the list entry.
ALL The Concept and all of its descendants are included in the export.
CHILDREN Only the children of the Concept are included in the export.
DESCENDANTS Only the descendants of the Concept are included in the export.
The screen shot below shows a Concept drop list with Modifiers added and the context menu visible.
Export Actions
Five action buttons are available at the bottom of the Export panel:
Export Performs an export of the selected objects. Objects are exported in the order given in the drop list. If export is to a file, and the file already exists, the panel first prompts to Append to or Replace the current contents. If Append is selected, the Title and Header are not written and export rows are added to the existing file. At the completion of the operation, the panel provides statistics for the export and, if a file export, prompts for viewing the file. The contents of the panel (fields and drop list) are not changed after the export.
Sort Sorts the items in the drop panel. Namespaces are placed first (in order by Namespace Name) followed by Subsets (in order by Subset Name) followed by the explicit Concepts (in order by Concept Name). This action removes duplicate objects, but otherwise equivalent objects, e.g. Concepts, with different version dates are considered unique.
Clear Clears the contents of the drop panel, i.e., all Namespace, Subset, and Concept objects are removed.
Minimize Minimizes the Export Panel to a small drop panel. Objects dropped into the panel are added to the end of drop list. See Using the Export Well below for further information.
Close Closes the Export Panel.
Using the Export Well
Selecting the Minimize action button minimizes the Export panel to a small floating Export Well panel (see left). This panel reduces the footprint of the Export panel so that more of the DTS Editor is visible. Any objects dropped into the central “well” of the panel are added to the end of the drop list. The well shows the total number of objects in the list. Press the Maximize button to restore the full Export Panel. The Export Well can be moved (by dragging its title bar), but cannot be closed.
Managing Export Profiles
The contents of an export are determined by export specifications called Profiles. Profiles contain general export information such as the delimiter to be used for text exports and whether a header is to be printed, and detailed descriptions of the Concept attributes to be written. Profile specifications are persisted in XML files having the “prf” extension and placed in the DTSInstall\bin\export directory.
To view, modify or create Profiles, select the Profiles tab. This tab (see example below) consists of a Profile select combo and Profile details panel. When the Profiles tab is selected while the Export tab is visible, the Profile panel is loaded with the Profile selected (if any) in the Export tab’s Export Profile.
To view an existing Profile, select the Profile from the Export Profile combo.
To create a new Profile, press the New button next to the Export Profile combo. The panel will prompt for a new Profile name. If this name is not already in use, the name will be added to the Profile combo, selected, and the Profile detail panel will be initialized.
Profile Definition
An export Profile consists of a set of basic parameters and a list of export Fields. The basic parameters are displayed at the top of the Profile details panel and the export Fields are shown in the Fields table (see screen shot above).
Profile Parameters
The first parameter specifies how attribute Fields having multiple values are handled in the export. This parameter has three possible values selectable by the radio buttons:
Export first only Only the first value of the attribute is exported. As a result, only one row/line is written for each Concept.
Combine values Multiple attribute values are combined into a single value using the specified delimiter. This combined value is written as the attribute Field value. As in the previous option, this results in only one row/line being written for each Concept.
Write
multiple lines Attributes with
multiple values result in multiple lines/rows per Concept. For example, if a Synonym is specified
as an export Field and a Concept has two synonyms, two lines/rows will be
produced, differing only in the value of the Synonym field. If more than one field has
repeating values, an appropriate number of unique output records will be produced. Value replication follows
the "natural" ordering of field values: the first field/column varies
the slowest, the last varies the fastest.
The Text File Delimiter parameter specifies the Profile’s main delimiter. This parameter value is only used if the destination export file (from the Export panel) is a text file (.txt extension) or the export is to a printer. To specify that a tab is to be used as the delimiter, enter “(tab)”.
The third parameter, Export Header, specifies if a “header” line/row is to be written before any data lines. The header line consists of descriptions for each of the export Fields, e.g., “Concept Name”, Code in Source”, etc.
Profile Fields
The main content of an export is defined by a set of Profile Fields. Objects in the export drop list are processed sequentially and for each export Concept, called the Field’s Key Concept, the Fields are evaluated and output into a column of a row in the export. Each Field represents an attribute of the Key Concept, or derivative of an attribute. Fields are specified by creating and editing row entries in the Profile’s Field table (see screen shot above).
A Profile Field consists of six elements:
Col The (one-based) number of the Field’s column. This element is filled by the Profile panel and is not editable.
AT The Attribute Type code associated with the Field. See the description of Attribute Types below.
Attribute The name of the specific DTS Type for the Attribute Type code.
Namespace The optional name of the Namespace for the DTS Type.
DT The Display Type for the Field. See the description of Display Types below.
Display The name of the specific DTS Type for the Display Type code.
Some Fields are completely determined by the Attribute Type element, while others require one or more additional elements. The paragraphs below describe the elements and their interdependencies.
The Attribute Type
Element
The following Attribute Type codes are available for
selection from the AT column editor:
CN The Field value
is the Concept Name of the Key Concept. CN has no other elements.
CC The Field value is the Concept Code of the
Key Concept. CC
has no other elements.
CI The Field value is the Concept ID of the Key Concept. CI has no other elements.
CS The Field value is the Concept Status of the Key Concept (ACTIVE, INACTIVE, DELETED). CS has no other elements.
NS The Field value is the name of the Key Concept’s Namespace. NS has no other elements.
K The Field value is the Kind of the Key Concept. K has no other elements.
VN The Field value is the Name of the Key Concept’s associated Version. VN has no other elements.
VD The Field value is the Release Date of the Key Concept’s associated Version. VD has no other elements.
PN The Field value is the Preferred Name of the Key Concept. If there is no Preferred Name, the value is the empty string. PN has no other elements.
RN The Field value is the Resolved Name of the Key Concept. If there is a Preferred Name, the value is that Name. If there is no Preferred Name, the value is the Concept Name. RN has no other elements.
S The base Field value is a Synonym of the Key Concept. The Attribute and Display Type elements are required.
P The base Field value is a Property of the Key Concept. The Attribute and Display Type elements are required.
DC The base Field value is a Defining Concept of the Key Concept. The Attribute and Display Type elements are required.
DR The base Field value is a Defining Role of the Key Concept. The Attribute and Display Type elements are required.
R The base Field value is a Role of the Key Concept. The Attribute and Display Type elements are required.
IR The base Field value is an Inverse Role Key Concept. The Attribute and Display Type elements are required.
A The base Field value is an Association of the Key Concept. The Attribute and Display Type elements are required.
IA The base Field value is an Inverse Association of the Key Concept. The Attribute and Display Type elements are required.
SS The Field value is the name of a Subset in which the Key Concept participates. SS has no other elements.
The Attribute Element
Attribute Types S, P, DC, DR, R, IR, A, and IA require specification of the associated DTS Type. Available Attributes are displayed in the combo for the Attribute element. The Attribute values are the set of all DTS Types (for the selected Attribute Type) that exist in the DTS Knowledgebase. Types with the same name but which are present in different Namespaces only appear once.
The Export Module uses an “anonymous attribute” technique for displaying values. With this technique, the selection of the actual DTS Type for attribute evaluation is deferred until the Key Concept is known. Thus, “Code in Source” can be selected as the Attribute for a P Field and when evaluated, this Field will export the Property value(s) of the “Code in Source” Property Type that exists in (is owned by) the Key Concept’s Namespace. If there is no “Code in Source” Property Type in the Key Concept’s Namespace, then the value is empty. This is the default Attribute behavior; it can be overridden with an entry in the Namespace element.
The Namespace Element
The Namespace element is always optional. The values of this element are the names of the Namespaces in the DTS Knowledgebase. If a Namespace is selected for the Namespace element, then this Field only returns values of the Attribute DTS Type for the specified Namespace, e.g., only “Code in Source[SNOMED CT]”. The Namespace element thus “specifies” the otherwise anonymous Attribute for the Field.
The Display Type
Element
This element is required for Attribute Types P, DC, DR, R, IR, A, and IA. The Display Type (DT) element enables multiple display options for the Field.
If the Attribute Type was specified as P, the following two options are available:
V The Field value is the value of the Property (the default).
PQ The Field value is the value of a Property Qualifier on the Property. The DTS Type of the Qualifier is given in the Display element.
If the Attribute Type was specified as DC, DR, R, IR, A or IA the following options are available:
CN The Field value is the Concept Name of the Attribute’s target Concept (the default).
CC The Field value is the Concept Code of the Attribute’s target Concept.
CI The Field value is the Concept ID of the Attribute’s target Concept.
CS The Field value is the Concept Status of the Attribute’s target Concept.
PN The Field value is the Preferred Name of the Attribute’s target Concept.
RN The Field value is the Resolved Name of the Attribute’s target Concept.
P The Field value is the value of a Property of the Attribute’s target Concept. The DTS Type of the Property is given in the Display element.
AQ The Field value is the value of an Association Qualifier on the Association. This Attribute Type is only available for A and IA Attribute Types. The DTS Type of the Qualifier is given in the Display element.
The Display Element
If PQ, P, or AQ is selected for the Display Type (DT) element, the DTS Type of the associated Property Qualifier, Property, or Association Qualifier is given by the value of the Display Type element. Like the Attribute element, available Display element values are anonymous (not Namespace specific), but the rules of evaluation are somewhat different.
For Qualifiers (Display Types PQ and AQ), the Namespace of the Qualifier Type is the Namespace of the Property Type or Association Type being evaluated (determined at the time of the export).
If the Display Type is P, the Namespace of the Property Type is the Namespace of the Field’s base Attribute’s target Concept.
Editing Profile Fields
To edit an existing Field, simply double-click on the Field’s element. This will open a drop-down selection list. Click on the desired entry. Remember that the Column element is not editable, and that changing the value in some elements, especially the Display Type (DT) element, will set or clear values in other elements.
The five buttons immediately below the Field table (see screen shot at the beginning of this section) modify the contents of the table itself. Some buttons may only be enabled when a Field row is selected (single click on a row).
Up Moves the selected Field row up one position. The Column element is adjusted according.
Down Moves the selected Field row down one position. The Column element is adjusted according.
Add A new Field row is added below the selected row (or at the top) of the table. The Column elements are adjusted according.
Remove Removes (deletes) the selected Field row from the table. The Column elements are adjusted according.
Clear After confirmation, clears the table; all Field rows are removed.
Once a Profile has been modified, the title of the Profile tab shows an asterisk (“*”) and the Export tab is disabled. It is not possible to exit the Profile panel when any modifications are present. To clear the modified state, Save, Reload or Cancel the Profile (see Managing Profiles below), or select another Profile (you will be prompted to confirm this change before the other Profile is loaded).
Managing Profiles
The six buttons at the bottom of the Profile tab assist in managing Profiles.
Save Saves the Profile definition in the file system.
Rename Renames the selected Profile. The panel prompts for the new name, which must be unique.
Copy Creates a copy of the selected Profile under a new name. The panel prompts for the new name, which must be unique.
Reload After confirmation, reloads the Profile discarding any pending changes.
Delete After confirmation, deletes the selected Profile.
Cancel After confirmation, cancels any pending edits and clears the Profile panel. No Profile will be selected. Most often used to cancel a pending new Profile session before saving.
Revision History
Version 1.0 Initial release.
Version 1.1 Updated for DTS Version 4.1.
Version 1.2 Bug fixes. Update for DTS 4.3 Layout Manager. Can be used as a Layout panel.