Open Immunization Software - Spring 2016

Simple Message Mover

Simple Message Mover


The installation process has been greatly simplified by a new installation web page that will guide you through the steps of the process. Once you have obtained credentials from the IIS, installation should take about 15 minutes.

Local Folder Organization

The SMM is designed to move data that is located in files on your local system. To understand how the SMM works you will need to understand how it interacts with your local file system. There are three key folders that you need to understand:

Installation Web Page

The installation process is guided by an interactive installation web page that takes you through the four steps of the process. It is recommended to begin on the first step and follow the process through each step, keeping this page open for reference.

  1. Prepare: Create the local folders needed.
  2. Configure: Create and download the smm.config.txt.
  3. Install: Setup Java and Tomcat.
  4. Download: Get and save SMM application.

Step 1: Prepare

If you have not already done so, begin the process by clicking on the first step list above.

Sections A and B: In the first two sections you will need to identify or create the SMM Root Folder and the IIS Transfer Folder, then copy/paste the folder names into their respective places in the installation web page. You should note that for the SMM Root Folder you should paste in the entire directory address (including the Windows driver letter if on Windows). It is highly recommended that you copy this directory from the address bar of the folder window and past it into the form to ensure that you don't introduce a typo. For the IIS Transfer Folder you only need to indicate the name of the folder without the full path.

Section C: Once you have created the folders you will need to choose a template for configuration. Choose a template that represents the system you are looking to integrate with. The Simple Message Mover has been tested and configured to connect to these systems and a template has been created to make setting up the connection as easy as possible. If you do not see your IIS listed you will have to choose a default template.

Step 2: Configure

Instructions for the configuration page will be shown with instructions specific to the template you chose. Ideally you should have already requested and received credentials for your IIS. If you have not, the form will indicate which information is expected from the IIS so when you request access you can be sure you ask for and receive all that you need to know in order to connect.

Once you have the credentials, please fill in the fields according to the instructions given on the page. You may notice that some fields will already have values filled out. For example, the URL or address for an IIS may already be indicated. You will want to review the values set to ensure they are optimal or correct for your installation. If you see any discrepancies or errors based on what the IIS has given you, please forward these to the SMM development team so we can fix the template.

Please note that the credential information you place in this application is not stored on this site and can not be retrieved for later viewing. You should have your own system for storing and tracking your credentials. This step in the installation creates a configuration file that will include the credentials in the proper form for your local SMM instance to read them. In addition, the password you enter will be hidden with a security hash function so that when you view the resulting file you will not be able to read the password back easily. You must still protect this configuration file as a highly secure document and protect from non-authorized users gaining access, as the password can be decrypted and the other information in plain text be used to gain access in your name.

After filling out the form, click the download button and save the file in the IIS Transfer Folder that you created in Step 1. The file created must be named smm.config.txt . This is the default name you will be given for saving. Windows users should note that by default Windows hides the extension .txt and displays this as smm.config . The name of this file is critical as the SMM determines if a folder is designated as a IIS Transfer Folder only if an smm.config.txt file is found in a directory. Be sure to follow this step correctly or your interface will not be configured by SMM.

Step 3: Install

This step is not specific to SMM but requires that you install the latest version of Java and Apache Tomcat. You likely have Java installed, and you may only need to confirm it is there before installing Apache Tomcat. The instructions for installing Apache Tomcat differ depending on the operating system. Complete instructions are given on the links provided in the installation web page.

When the installation is complete you will need to indicate where Tomcat is installed. You will need to know this information in order to install, start and stop the SMM on Tomcat. Copy and paste the full directory of where Tomcat is installed before continuing to the next step.

Step 4: Download

Now that Tomcat is installed and the SMM directories are ready and configured, you can download and install the SMM application. The SMM is a simple zip file that is saved into a Tomcat directory, when Tomcat sees it, it expands it, installs the application and immediately starts it. This page allows you to configure a specific version of SMM to match your system.

Software Version: The first step is to select the software version you wish to download. Unless otherwise instructed leave it on the one already selected.

SMM Root Folder: This is the folder configured in Step 1. If you have been following the steps in order this should be pre-filled with a complete folder path. If it is empty, it is recommended that you begin back at Step 1.

Support Center: The SMM reports statistics and information about how much data has been sent and the status of the interface to a central support center. The support center is an external web site that is used to help support your use of the SMM. If there are questions about if the SMM is working and what it is doing, your support team can review the support center to confirm current operation. The support center gets up-to-date information but can not receive patient specific information or other confidential information. Instead it collects statistics such as the number of messages sent and how many were rejected because of errors. Use of the Support Center is recommended but optional. Please select OIS if you are unsure about which Support Center you should use.

Support Center Code: Support from the Support Center is organized around project specific codes. For Indian Health Center facilities who are being supported by central IHS staff, please select Indian Health Service . If you are unsure about which to choose, select General. This field is optional.

Clicking download will start the process of downloading and you will be prompted to save the file. It is important that you save it to correct location in order for Tomcat to recognize it. It must be saved into the webapps directory where Tomcat is installed. Tomcat continuously monitors this folder for new files with an extension of .war . Save the file as smm.war directly in the webapps directory. Within a few seconds Tomcat will create a folder called smm in the same directory. This will indicate to you that Tomcat has deployed (installed) SMM. If you have followed the steps corrected SMM should be up and running.

Upgrading SMM

Upgrading SMM can be done by following the installation steps with the following changes:

  1. Prepare: Normally you will want to repeat this step. This will ensure that your configuration file is up-to-date as possible.
  2. Configure: Normally you will want to repeat this step. This will ensure that your configuration file is up-to-date as possible.
  3. Install: Java and Tomcat should be installed previously. This step is only needed if Java or Tomcat is not operating correctly.
  4. Download: Before downloading the latest version, follow these steps:
    • If Tomcat is running, stop it. In Windows this can be done through the Windows service panel. In AIX the process will need to be "kill"ed.
    • Find the Tomcat webapps directory and delete the ssm.war file and the smm folder. This removes the old version of SMM from Tomcat.
    • Follow instructions to download the latest war file.
    • Start Tomcat up.

Frequently Asked Questions

Is my connection information saved on the installation site?

No. Some of the information, such as folder names is saved while you are using the application. But after a certain period of inactivity, or if you close your web browser, this information will be discarded. The website is to assist you during the installation process but should not be used to store or manage connection information.

How can I tell if SMM is actually running and configured properly?

You will first want to examine the IIS Transfer Folder where you saved the smm.config.txt file. If SMM has started up successfully, at least once, you should see a new set of folders created in this folder: request , response , etc. These are the folders that are needed by SMM to transmit files. SMM leaves it's current status in a file that starts with the phrase smm-is ... There is no information in the file, only the name indicates the status. A common status you will see is smm-is-waiting , which indicates that SMM is up and running with no problems and is waiting for data to send. You can see the last timestamp on the file and see when SMM wrote that file. If it hasn't been changed for over a minute or so then you can know that SMM is not running.

What if Tomcat does not deploy/install my smm.war?

You will first want to ensure that Tomcat is up and running. On Windows, Tomcat is started and stopped from the services panel. Open the services panel and if Tomcat is not running, select it and click on the start button. The smm.war should then deploy. On other systems you will need to follow the Tomcat instructions to understand how to start and stop Tomcat. You can also verify if Tomcat is running by opening a web browser on the system it is running on and trying this link: http://localhost:8080/. (Note: during installation you were prompted about which port number to run Tomcat on, 8080 is the default. If you selected a different port number than this default you will need to change the address for Tomcat.) If you see a default Tomcat screen with the Tomcat log then Tomcat is running.

How do I upgrade the SMM?

Upgrade process is similar to the install process except that some of the steps can be skipped if there are no changes. To deploy/install a new war you will need to stop Tomcat, delete the smm.war file and the smm directory, and start Tomcat. This removes the SMM application completely. A new smm.war can be downloaded and installed. from Tomcat.

How do I install more than one connection?

Simply follow Steps 1 and 2, creating a new IIS Transfer Folder in the SMM Root Folder that should already exist. Download and save the smm.config.txt in the new folder, then stop and start Tomcat so that SMM will rescan the SMM Root Folder for the new interface.