Introduction

This guide serves as a reference for users of the Cancer Report Validator (CRV).

Requirements

System and Software Requirements

System and Software Requirements

Installation

There are two ways to install CRV. The first is to build the project locally as described in the Source Build Guide. The second is to obtain the latest version of the WAR here.

Source Build Guide

Source Build Guide

Configuration

Logging Configuration

The following optional system properties control logging:

Name	Value Type	Default Value	Description
crigtt.logging.console.tty	boolean	<availability of an interactive console to the JVM>	Flag for whether logging to compatible terminals will contain colorized highlighting.
crigtt.logging.file.dir	string (directory path)	CLI: <executable directory>/../logs Webapp: <webapp container log directory>	Path to the log directory. When using Tomcat as the webapp container, defaults to: ${catalina.base}/logs This is Tomcat's standard log directory.
crigtt.logging.file.name	string (file name)	CLI: crigtt-cli Webapp: crigtt-web	Base name of the log file (no extension).
crigtt.logging.file.ext	string (file extension)	.log	File extension suffix of the log file name.
crigtt.logging.file.size.max	string (file size)	50MB	Maximum size that a log file can reach before it is "rolled over" (i.e. the current log file is renamed with a timestamp and a new file assumes it's place).

Tomcat Configuration

Install Tomcat 9.0

If the file ${TOMCAT9_INSTALLATION_PATH}/bin/setenv.sh does not exist, create it by running:

${TOMCAT9_INSTALLATION_PATH}/bin/setenv.sh

Append the following lines to the file ${TOMCAT9_INSTALLATION_PATH}/bin/setenv.sh:

CATALINA_OPTS="$CATALINA_OPTS -Dcrigtt.data.db.dir=<path to database directory> -Dcrigtt.data.validate.vocab.dynamic.dir=<path to vocab file directory>"

<path to database directory>: path to a directory where you want data to be persisted.
<path to vocab file directory>: path to a directory where you want to place the vocab files that will be persisted.

Java Version 8.0

Install Java 8.0 and point JAVA_HOME environment variable to the install location of Java 8.0.

Code System and Value Set Configuration

The code systems and value sets that are collected according to the Vocabulary Data Sets Source Documentation are available in the vocab.tar.gz file, unzipped and placed in a specific directory structure within the <path to vocab file directory>.

The code system files collected from the Code Systems tab ("File Name(s)" column) need to be placed in the following structure:

codes/
	ICD-O-3/
	ICD10CM/
	ICD10PCS/
	ICD9CM_DX/
	LOINC/
	RXNORM/
	SNOMED-CT/

The value set files collected from the Value Sets tab ("File Name(s)" column) need to be placed in the following structure:

valueSets/
	PHVS/
	VSAC/

The files with the .txt extension should be placed in PHVS and the files with the .xls extension should be placed in VSAC.

Deployment

Once the configuration has been complete, the WAR file should be deployed. There are several methods to deploy WAR files in Tomcat, as described in the Tomcat Configuration.

The first time the WAR is deployed, the data in the code system and value set files placed in the directory described in the Code System and Value Set Configuration section will be loaded into the OrientDB database, which can take up to an hour. The log can be monitored to determine when that process has been completed.

Refreshing the Vocabulary Files

If any code system or value set files need to be updated, the contents of the <path to database directory> should be removed, the updated vocab.tar.gz should be unzipped to <path to vocab file directory>, and the webapp should be restarted. This will cause the vocabulary files to be loaded anew.

Usage

CLI Usage

To build the tools from source, run:

mvn -pl="crigtt-parent,crigtt-core,crigtt-cli"

The tools can be found in ~/crigtt/crigtt-cli/target/crigtt-cli/bin or extracted from ~/crigtt/crigtt-cli/target/crigtt-cli-<version>-cli.tar.gz

Within the crigtt-cli directory, a data directory should be added so that the directory structure looks like:

crigtt-cli/
	bin/
	conf/
	data/
		db/
		validate/
			vocab/
				codes/
				valueSets/
	lib/

The vocabulary files need to be obtained as indicated in the Code System and Value Set Configuration section and the codes and valueSets directory should be placed under the vocab directory as indicated above.

Usage: crigtt-cli [options]

Option(s)	Required (Y/N)?	Default Value	Description
-f, --format	N	true	Flag for whether to format the output.
-h, --help	N	false	Display help.
-i, --in-file	Y		Input file or "-" for standard input.
-n, --in-file-name	N		Input file name.
-d, --out-dir	N	${crigtt.app.home}/out	Output directory.
-o, --out-file	N		Output file or "-" for standard output.
-c, --testcase	N	testcase0	Test case for running conformance against test data. Possible Values: [testcase0, testcase1a, testcase1b, testcase2, testcase3, testcase4]
-t, --type	Y		Output render type. Possible Values: [HTML, JSON, XML]

Webapp Usage

Web Front-end Usage

An interactive web front-end is available at the root of the deployed webapp's context (ex. http://localhost:8080/crigtt-web/).
All modern (if Internet Explorer, at least v11) browsers are supported (Firefox and Chrome being tested the most).

RESTful Web Service Usage

A RESTful web service endpoint is available at: <path to the webapp context>/service/validator/validate
The associated WADL is available at: <path to the webapp context>/service/validator/validate.wadl
Request: A HTTP POST with optional query parameters:
- Content:
  - multipart/form-data (i.e. a HTML form submission) with a single body part (id = file) consisting of the document to be validated.
  - multipart/form-data with a single body part (id = testcase) consisting of the test case against which the document is to be validated. Options are testcase0 (no test case selected - IG conformance validation only), testcase1a, testcase1b, testcase2, testcase3, or testcase4.
- Path Parameters:
  - Response Type: Appending .html, .json, or .xml to the web service endpoint address will result in the response being returned as HTML, JSON (the default), or XML, respectively.
- Query Parameters (Optional):

Name	Value Type	Default Value	Description
format	boolean	false	Flag for whether the response content should be formatted (indented).
timeZone	string, time zone offset	<the local time zone of the JVM>	Used to generate localized human-readable timestamps (only applicable to HTML responses).

Response:
- Content: The rendered response.
- HTTP Headers:

Name	Value Type	Description
X-Crigtt-Response-File-Name	string (file name)	A generated file name for saving the response via the web front-end (the default value in the associated browser/OS file save dialog).