Overview

This page documents the use of the index viewer tools.

Prerequisites

• Index viewer data must exist locally.

Details 

These tools are used to generate HTML files and Lucene indexes to feed into the configuration for the index viewer tool.  The code is based around earlier work with a pure-java based index viewer tool.

These tools are really used to build files that should be packaged into a Maven project and be made available as a configuration artifact to the build process. Two configuration artifacts have been provided that can 

When building the application, the version of index viewer data is specified in properties in the config.properties file that corresponds with the config artifact being used for the build.  For example, in config/prod, see that the src/main/resources/config.properties file contains these three entries:

• index.viewer.groupId=org.ihtsdo.otf.mapping
• index.viewer.artifactId=index-viewer-data-icd10
• index.viewer.version=1.0.0

This artifact itself is available via the IHTSDO nexus server (in the "Releases" repository):

The contents of this artifact were created through invocations of these various tools.

The process for creating an index viewer data artifact is this:

• Obtain the original index files (e.g. for ICD10, these are the files TEIL1.ASC, TEIL2.ASC, and TEIL3.ASC).
• Convert to the supported XML form (e.g. for ICD10, we use the AscToXmlMojo).
• Process the supported XML form into HTML (e.g. use the IndexXmlToHtmlMojo)
• Process the supported XML form into Lucene indexes (e.g. use the IndexXmlToLuceneMojo).
• Put all relevant files into a Maven artifact that has this structure
  • src/main/resources/indexViewerData/${terminology}/${terminologyVersion}
    • /html
    • /lucene
• Build/package and perform a Maven release of the artifact so that it can be referenced appropriately from the config.properties file from the config artifact being used to build the application.

Following are some details about these tools:

Mojo: AscToXmlMojoMojo.java (in admin/mojo/src/main/resources/java/org/ihtsdo/otf/mapping/mojo)

Project: admin/lucene

Configuration Parameters

• A profile of "ConvertAscToXml" must be passed
• run.config - the standard configuration file specified as a -D parameter

• input.dir - the input directory containing the native index files specified as a -D parameter

  • It is expected that the path ${input.dir}/${terminology}/${terminologyVersion} will contain an "asc" folder with the actual index files present.
  • NOTE: this mojo takes other parameters but they are hardcoded into the pom.xml for the ICD10 build as the configuration is too complex to invoke using -D parameters.
• Important notes:
  • Each index file gets its own execution of this mojo and the output XML files are written to an "xml" directory at the same level as the "asc" input directory.  
  • The file naming convention of the output file is based on the input file name, the terminology, and the terminology version (e.g. ICD10_TEIL1.ASC.xml)
  • Where indexes contain table data, there is an opportunity to specify a semi-colon separated list of table header values.  e.g. this is used in TEIL1 for the abortion table (under A) and the neoplasms table (under N).

Mojo: IndexXmlToHtmlMojo.java (in admin/mojo/src/main/resources/java/org/ihtsdo/otf/mapping/mojo)

Mojo: IndexXmlToLuceneMojo.java (in admin/mojo/src/main/resources/java/org/ihtsdo/otf/mapping/mojo)

Project: admin/lucene

Configuration Parameters

• A profile of "ConvertXmlToHtmlAndLucene" must be passed and invokes both mojos listed above.
• run.config - the standard configuration file specified as a -D parameter

• input.dir - the input directory containing the supported XML index files specified as a -D parameter

  • It is expected that the path ${input.dir}/${terminology}/${terminologyVersion} will contain an "xml" folder with the actual index files present.
  • NOTE: this mojo takes other parameters but they are hardcoded into the pom.xml for the ICD10 build as the configuration is too complex to invoke using -D parameters
• Important notes:
  • Each index file gets its own HTML and its own Lucene execution and the output files are written to "html" and "lucene" directories at the same level as the "xml" input directory.
  • The resulting structure has a directory for each index "domain".  Thus there is an html/TEIL1 directory for the ICD10 index generation that contains the HTML files corresponding to that index.

Samples

Sample command line call to convert ICD10 ASC files to index viewer XML:

% cd ~/code/admin/lucene
% mvn install -Drun.config=~/config/config.properties -PConvertAscToXml -Dinput.dir=/home/ihtsdo/data/indexViewerData

Sample command line call to convert index viewer XML to HTML and Lucene indexes:

% cd ~/code/admin/lucene
% mvn install -Drun.config=/home/ihtsdo/config/config.properties -PConvertXmlToHtmlAndLucene -Dinput.dir=~/data/indexViewerData

Sample Eclipse run configuration to convert ICD10 ASC files to index viewer XML:

Sample Eclipse run configuration to convert index viewer XML to HTML and Lucene indexes:

Index Viewer Additions (ex. ICD10CM) and Updates

Clone git project  "https://git.ihtsdotools.org/ihtsdo/ihtsdo-mapping-tool-data.git" to local machine e.g.  "C:\workspace-mapping-mars\ihtsdo-mapping-tool-data"

That is a project with 2 sub-modules (empty, and icd10). Add a third, icd10cm
And lay it out like icd10 (e.g. just borrow everything you can).

1. All of the code to actually generate the files for the index viewer is in the mapping project itself. You’ll use that to generate the index files.  (see above)
2. Put the index files into a project like the index-viewer-data project under icd10cm and version it appropriately
(e.g. give it a release version when you’re ready)
3. Build the project which will create a .zip file in the index-viewer-data/icd10cm/target directory.  This can be done in eclipse or in cygwin from the index-viewer-data folder  mvn clean build.
4. Log into nexus and add that .zip file as an artifact with the right groupId, artifactId, version
5. In the mapping project, make a mapping-config-prod-icd10cm config module
Look at how the “mapping-config-prod” works -> it has a dependency to the index veiwer data and imports it directly into there.
Thus, when the config project builds its zip file, it completely contains the index viewer data that is needed for that deployment. Then when that gets unpacked into the .war file, the index data is all in the right place in the deployed war package.

References/Links

• n/a