This page documents the use of admin tools to perform an RF2 release of mapping project data.

Prerequisites

• MySQL database must already exist (e.g. "mappingservicedb").
• MySQL database connection parameters must be defined in the properties file specified by "run.config".
• Create/Update DB mojo must also have already run so that the database schema exists and data is loaded.
• A map project must exist for the specified refset id and have publication ready records.
• IMPORTANT: The Tomcat server must not be running while this is run, otherwise indexes can get corrupted.

Details

There are four stages to the process (see Performing an RF2 Release) and the following tools are used to enact those stages. 

The process starts by beginning a release.  This tool verifies that conditions for release have been met (including that all map records are publication ready and the validation suite passes).  This process also generates a "Release QA" report (which must be a valid report definition for this project) to summarize the state of things (non-publication-ready records, in scope concepts not mapped, validation failures).  Finally, if everything passes, it removes map records for retired or out-of-scope concepts.

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

Project: admin/release

Configuration Parameters

• A profile of "BeginRelease" must be specified
• run.config - the standard configuration file specified as a -D parameter
• refset.id - the refset id of the mapping project to release specified as a -D parameter
  • A map project with this refset id must exist
• test.mode.flag - a flag indicating whether to run in test mode, which avoids making database changes, defaults to false
• NOTE:  this mojo will avoid making database changes if any of the validation steps fail.

Once the "begin release" process has successfully executed, this process can be run to produce the release. This process performs a variety of QA checks and reports failures.  Output includes:

• A delta relative to the previous release
• A complete snapshot file for this release
• An "active" snapshot file
• A human readable form of the map
• A summary of statistics

NOTE: this tool can also be used in "test mode" to produce a daily build release that will create map records for any publication ready records.  The test mode ignores data conditions that are verified by the "begin release" process (thus not all records must be publication ready, in scope, or valid).  Like the daily build from the authoring environment, it creates a delta relative to the previous release. 

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

Project: admin/release

Configuration Parameters

• A profile of "Release" must be specified
• run.config - the standard configuration file specified as a -D parameter
• refset.id - the refset id of the mapping project to release specified as a -D parameter
  • A map project with this refset id must exist
• output.dir - the output directory specified as a -D parameter
• time - the date to use for the effectiveTime of the RF2 files created
• module.id - the moduleId to use for the RF2 files - this is specific to the individual map project.
• test.mode.flag - a flag indicating whether to run in test mode, which avoids making database changes, defaults to false

Once a release is produced and validated, we are ready to "finish release".  This tool changes all READY_FOR_PUBLICATION workflow statuses to PUBLISHED and it takes the final snapshot view of the maps and applies it to the "complex_map_refset_members" table which is used as the point of reference for the previous release.  Thus, in effect we make the current release the previous release so that future delta computations are relative to this.

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

Project: admin/release

Configuration Parameters

• A profile of "FinishRelease" must be specified
• run.config - the standard configuration file specified as a -D parameter
• refset.id - the refset id of the mapping project to release specified as a -D parameter
  • A map project with this refset id must exist
• input.file - the final RF2 snapshot file from the release process to reload
• test.mode.flag - a flag indicating whether to run in test mode, which avoids making database changes, defaults to false

Samples

Sample command line call of the RF2 release tooling to begin a release for refset 447563008:

% cd ~/code/admin/release
% mvn install -Drun.config=/home/ihtsdo/config/config.properties -PBeginRelease -Drefset.id=447563008

Sample command line call of the RF2 release tooling to process a release for refset 447563008:

% cd ~/code/admin/release
% mvn install -Drun.config=/home/ihtsdo/config/config.properties -PRelease -Drefset.id=447563008 -Doutput.dir=/home/ihtsdo/data/doc/release -Dmodule.id=900000000000207008 -Dtime=20150131

Sample command line call of the RF2 release tooling to finish a release for refset 447563008:

% cd ~/code/admin/release
% mvn install -Drun.config=/home/ihtsdo/config/config.properties -PFinishRelease -Drefset.id=447563008 -Dinput.file=/home/ihtsdo/data/doc/release/der2_iisssccRefset_ExtendedMapSnapshot_INT_20150131.txt

Sample command line call of the RF2 release tooling to begin the editing cycle for refset 447563008:

% cd ~/code/admin/release
% mvn install -Drun.config=/home/ihtsdo/config/config.properties -PBeginEditingCycle -Drefset.id=447563008

Sample Eclipse run configuration to begin a release for refset 447563008:

Sample Eclipse run configuration to process a release for refset 447563008:

Sample Eclipse run configuration to finish a release for refset 447563008:

Sample Eclipse run configuration to begin the editing cycle for refset 447563008:

Troubleshooting

If the "begin release" process fails because of either map records not ready for publication, unmapped in scope concepts, or validation errors, then these data conditions must be addressed before proceeding.

When performing a release, there may be QA errors that stop the process.  In this case, those errors must be fixed and if the editing tool is used for that, it would be a good idea to re-run the "begin release" process first.  Then the processing step can be re-run.

A failure in the "finish release" process would most likely be a serious bug and would require analysis.  In other words, there is not a normal or expected failure mode for this step.

RECOMMENDATION: avoid problems in prod by running the process in a cloned environment (e.g. UAT) which supports the ability to revert to the initial state at any time without interfering with production activities.

References/Links

• n/a