Open Immunization Software - Spring 2016
Home Interfacing Data Quality Forecasting Matching

Simple Message Mover

Simple Message Mover

User Guide

The user guide assumes that you have followed the instructions to install the SMM and would now like to understand how to use it.

Folder Scanning

When SMM is started by Tomcat it starts a process to recursively scan the SMM Root Folder for folders that have a smm.config.txt file in them. If it finds a folder like this it adds it to a list of connections that the SMM should start. SMM can support as many connections as folders can be configured.

Note: In the current version of SMM, the folders are only scanned when SMM first starts. While changes to an existing smm.config.txt are read automatically within seconds new folders with new smm.config.txt files are not automatically recognized. You will need to restart SMM to have them recognized.

SMM Configuration File

The configuration of an SMM connection to an IIS is defined by a configuration file named smm.config.txt located in the IIS Transfer Folder. This file is key to SMM operation as the SMM will not send data unless this file is present.

The format of this file is both human and SMM readable. Changes can be made by the SMM user, but normally this file is created in the installation process and is not changed during operation. Here is a a quick explanation of some of the common configuration items:

SMM Log File

When SMM discovers the smm.config.txt file it puts the folder on a processing queue and attempts to process the data every 15 seconds. When it attempts to process it writes a log file with details about what it did. This log file is replaced every time it attempts and normally does not contain a lot of information unless there is a problem. However, there are a few pieces of information at the top that can be helpful in administering the application:

SMM Status file

For a quick status check, SMM also creates an empty file with the name indicating the current status of SMM. It always begins with smm- and has no extension. The system timestamp on the file indicates when SMM set the status. Here is a list of possible status and what they indicate that SMM is:

SMM has a Problem: Transmission Issues

This can happen when the IIS receiver is not available (Internet is down) or because it returns an exception. This does not however indicate if there are problems with the data itself. Messages that are rejected with negative HL7 acknowledgement messages are not considered problems by SMM. The SMM considers that a successful transmission and indicates a problem with the message itself using a different process.

If SMM is unable to connect to an IIS it waits for a certain period of time and then tries again. If at each try the same problem occurs SMM delays retrying longer and longer. SMM will retry on the following schedule until successful:

The exact time of the retry will be indicated in the log file and if a successful transmission occurs the retry waiting will restart at the 1st position. To have the SMM retry sooner that the scheduled retry time you must stop and restart Tomcat. When starting SMM will again attempt to send and if not successful will begin back at the first position for setting delays between retries.

This status only indicates if there are transmission problems. SMM will try to send data again if there are transmission issues but not if the message is properly rejected. SMM is responsible for properly transmitting messages but is not responsible if the IIS does not like or accep the message. Farther down in this user guide there is an explanation of how these errors are noted by SMM so they can be resolved.

Request Folder

All data to be sent must be placed in the request folder. SMM looks for files in this folder and sends them to the IIS. Do not place any other files in this folder, except ones that contain data you wish to send to the IIS.

SMM supports batches of messages in a single file. SMM recommends that each file begin with a FHS segment and end with a FTS segment. This allows SMM to ensure that the entire file is present before sending it. If a file begins with FHS and does not end with FTS, SMM will skip the file and not process. This is an important safety mechanism. Otherwise, SMM will process files that do not have FHS segment at the top but will not require a terminating FTS segment. Each HL7 message can be placed one after the other.

Once a file has been identified it is read by SMM and prepared for transmission. SMM creates a new folder in the requests director called .work . The presence of this directory indicates one of the following possibilities:

  1. SMM is in the process of preparing to send data.
  2. SMM is in the process of sending data to the IIS.
  3. SMM was stopped before it could finish sending data to the IIS and the prepared data is waiting to be sent.

The .work can be examined to see how many messages have yet to be sent to the state. Since every message is placed in a single file, simply counting the number of files indicates how many messages there are yet to send. In addition the file name is made up of the original file name plus an ordinal number and so it is very easy to see the total number of messages that were found in the file. SMM processes the file in strict alpha-numerical order. This means that all the files within a single batch will be sent in the order they appeared in the file. Multiple files will be sent in the order of how they sort.

Once SMM has transmitted a single message it deletes the corresponding message file in the .work directory. This is SMM's method of tracking whether a particular messages has been sent or not. If there is an exception or problem in transmission the file will not be deleted.

If there is an error SMM creates a new file with a similar name to the original file but with piece reading .rejected and places it in the request folder. This is SMM's way of indicating to the user which messages were rejected by the IIS. SMM will not retransmit this information unless the name of the file is change to remove the .rejected part of the name. The user should note that the SMM also writes comments and the acknowledgement message in the same rejected file. These comments and the acknowledgement will be ignored and never sent to the IIS if you rename the file and attempt to retransmit.

Once a file has been transmitted it is deleted from the request folder. A clean and empty folder indicates that all data has been transmitted. The presence of rejected files indicates that some or all of the messages were rejected. Rejected files never contain messages that were accepted positively by the IIS. The SMM does not consider a file accepted positively by the IIS unless the IIS specifically acknowledges receipt of the message and indicates that it was "Accepted".

Response Folder

The response folder holds the acknowledgement or query response messages received from the IIS. The name of the files match the names of the files put in the request folder. If a file with the same name is sent again, SMM automatically renames it to keep it unique.

Backup Folder

Before SMM processes a file it puts an exact copy of the file here for backup purposes.

Sent Folder

This is a copy of what exactly was sent to the IIS. The SMM can be configured to make minor changes to the HL7 message before being sent, and the SMM will strip out any comments or Acknowledgment messages included in the request file. The sent folder documents exactly what was sent. In most common configurations this will mirror what is in backup.

Test Folder

The Simple Message Mover is bundled with the DQA Testing tool and the DQA Testing tool uses this folder to save test cases and test messages that have been generated. Under normal SMM operation this folder is not used.

Update Folder

The SMM has been partially configured to support Reciprocal Batch Update but this work is not yet complete. For now, if VXU updates are received in response to any data sent the IIS it is placed here in this folder. Those updates back will never appear in the response folder. SMM is not yet ready to fully support Reciprocal Batch Update and so the IIS account should not be configured for this at this time.