Simple Message Mover
The user guide assumes that you have followed the instructions to install the SMM and would now like to understand how to use it.
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
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:
- Label: This is a short label or description for this interface that makes sense to the SMM user.
- Type: Indicates what basic type of transport is to be used.
- URL: Indicates the address of the IIS where the data should be sent.
- User Id: Value assigned by IIS.
- Password: Value assigned by IIS. Can be entered as plain text but if generated during installation the password will be hidden in an encrypted string.
- Facility Id: Value assigned by IIS.
SMM Log File
When SMM discovers the
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:
- Software Version: This is the current version of SMM that is running and which created this file.
- Login Username: This username can be used to login to the SMM directly using your local browser. If Tomcat has been installed on the default port 8080 then you can login by going to http:\\localhost:8080\smm\.
- Login Password: The password is temporary and changes every time SMM is restarted.
- Connection Id: This is a unique id that identifies this specific connection for tracking at the Central Support Center (if enabled).
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-is-waiting: running normally but has no data to send.
- smm-is-starting: configuring folders and connection settings.
- smm-is-looking: looking in the folder to see if there is data to send.
- smm-is-preparing: reading the data to be sent and preparing it to be sent.
- smm-is-sending: actively connecting to the IIS and submitting data.
- smm-has-problem: unable to connect with external because of an unexpected problem during transmission.
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:
- 1st: wait 30 seconds.
- 2nd: wait 1 minute.
- 3rd: wait 2 minutes.
- 4th: wait 4 minutes.
- 5th: wait 8 minutes.
- 6th: wait 16 minutes.
- 7th: wait 30 minutes.
- 8th: wait 1 hour.
- 9th: wait 2 hours.
- 10th: wait 4 hours.
- 11th: wait 8 hours.
- 12th: wait 12 hours.
- 13th: wait 1 day.
- 14th, 15th, etc.: wait 1 day.
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.
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
. The presence of this directory indicates one of the following possibilities:
- SMM is in the process of preparing to send data.
- SMM is in the process of sending data to the IIS.
- SMM was stopped before it could finish sending data to the IIS and the prepared data is waiting to be sent.
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
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
and places it in the
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
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
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".
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
folder. If a file with the same name is sent again, SMM automatically renames it to keep it unique.
Before SMM processes a file it puts an exact copy of the file here for backup purposes.
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.
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.
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.