Installing HCM 0.1 through 0.3

Installing HCM

For versions 0.1-0.3 only, for other versions, please see the links to the right under the HCM page.

The requirements for running HCM are some recent version of Java JDK (6 is highly recommended) and Apache Tomcat 6.0. Those must be installed properly for your platform, including whatever mechanism you would use to install Tomcat as a daemon or service. I’m not an expert on your platform necessarily, but hopefully installing those won’t be too difficult for you.

Preliminary Configuration

HCM requires users set-up on Tomcat and roles which allow those users to either view the status only, or to view the status, the current logs and to start and stop the processor agents. Within the directory you installed Tomcat to there is a file located at conf/tomcat-users.xml. The two roles you will have to add are “hcmAdmin” and “hcmUser”.

  <role rolename="hcmAdmin"/>
  <role rolename="hcmUser"/>

There may be other roles there, and they should be retained. In particular the admin role can be used with the Tomcat management console to start and stop the HCM application, which could be useful to force a reload of configurations.

With the roles defined, you should create at least an hcmAdmin user, and probably an admin user. Roles can be combined for a single user.

  <user username="adminuser" password="pw" roles="hcmUser,hcmAdmin"/>
  <user username="viewonlyuser" password="pw" roles="hcmUser"/>
  <user username="superuser" password="pw" roles="admin"/>

So your entire tomcat-users.xml should look something like this:

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
  <role rolename="hcmAdmin"/>
  <role rolename="hcmUser"/>
  <role rolename="admin"/>
  <user username="adminuser" password="pw" roles="hcmUser,hcmAdmin"/>
  <user username="viewonlyuser" password="pw" roles="hcmUser"/>
  <user username="superuser" password="pw" roles="admin"/>
</tomcat>

With users setup, we have to tell HCM which HL7 Comm configurations to run. To do so create a file in the “lib” directory called “hcm.properties”. This file only needs to contain a list of configuration names with the location of configuration files. Here is a sample with two configurations:

conf1=/Users/mike/simplesender.conf
conf2=/Users/mike/cleanfields.conf

The configuration name is only used if the configuration itself doesn’t contain a name. This portion of the file can’t have spaces in it. The second half, after the “=” is the location of the configuration file. This is a Unix system (OS X, in particular), but Windows systems would be similar. You can specify the configuration file locations like this:

conf1=c:/HCM/Configs/myconfig1.conf

Note that the directory separators use the normal Unix style slash instead of the Windows style. You can use either, but you have to use two Windows slashes instead of just one, like “c:\\HCM\\Configs\\myconfig1.conf”.

Lastly, all you need to do is download the HCM archive from the main HCM page here and unzip the archive. Inside is just one file, “Hl7CommMulti.war”. Put this file into your Tomcat’s webapps folder. Now start your Tomcat instance, either using your service manager or by running the startup file in the bin directory (“bin/startup.sh” or “bin/startup.bat”). That’s it, you have a running HCM.

Using HCM

Hopefully your HCM has started without problem and that once it’s running it will continue to do so without difficulty. The management of the application occurs through the web interface, which to connect to, you’ll point your web browser to the machine you installed HCM on:

http://<ip or host name>:8080/Hl7CommMulti/

You’ll be prompted to enter the username and password you provided previously.

If, for some reason you can’t connect or you wish to have more information about the configurations that have loaded (or why they couldn’t load), there is more information particularly about the startup and shutdown processes in the Tomcat log files. The place to start looking is in the “logs/catalina.<date>.log”. There, if you’re running the default logging configuration, HCM related messages should all be tagged with “org.nule.hcm”, and applicable messages should be easy to search for.

If all else fails, contact me via the “contact me” link on the top right of this page, and I’ll try to help you out.