Installing Mirth and Docbot
Before following this guide, Advanced will need to provide you with a API Consumer that has permissions to your Docman 10 organisation.
Once Advanced have provided you with the API consumer, download the AHC.Mirth.ADT.Setup.exe.
Running the exe with -help or no switches will output the example commands.
Docbot is a commandline utility used for validating and transforming HL7 messages into Docman 10 via a rest API.
Download Installer
The installer does the following;
- The installer is a command tool and will output the installer options when run.
- Start by downloading the AHC.Mirth.ADT.Setup.exe using the link above, this tool needs access to https://apps.docman.com
- It will then install Java, then Mirth Connect.
- During the automated install you may be prompted to install the Mirth Administrator Client manually to accept a license agreement!
- It will then Download Docbot and configure using the credentials provided and create a HL7 and Logs folder. C:\Program Files (x86)\PCTI Solutions Ltd\Docman.Docbot.<Suffix>\
- Once setup it will download a series of test HL7 messages and run them through, on completion it will open the log file in cmtrace tool so you can check the output.
- When the script completes restart the machine.
- On reboot, open Mirth Server Manager and right click the mirth icon in your task tray and select Launch Administrator. The default logins for mirth are admin/admin
Configuring Mirth
Once you have installed Mirth, you will need to import the channel and update the listener address and port if they don’t match what the PAS System has configured.
During the setup of Docbot it will download the Mirth channel template that can be imported inside the Mirth Administrator. Depending on if you set the suffix Test or Live it would have outputted one of the files below.
“C:\temp\Docman.ADT.Sync.Mirth.Channel.Live.xml”
“C:\temp\Docman.ADT.Sync.Mirth.Channel.Test.xml”
On the Source screen, change the connector type to ‘LLP Listener’, change the values for ‘Listener Address’ and ‘Listener Port’. The Listener Address is the IP of the server that the messages are being sent to, the Listener Port is the port that the messages are being sent to. The 127.0.0.1 address will need to be changed to the local machine’s address where the messages are being sent. Next click the Destination tab.
If you haven’t setup using the tool then the destination location will need updating to match your install directory.
The File Name directory should contain the following naming convention:
DMMSG-${message.type}-${date.get(‘yyyyMdH.m.s.mm’)}.${UUID}.hl7
Template field should contain: ${message.rawData}
Next, click Channels, then Deploy Channel.
Mirth is now configured and is actively monitoring the specified port
Docman HL7 Implementation Specification
The purpose of this section is help improve understanding of the HL7 structure, how messages are processed and explanation of error handling.
HL7 messages are consumed by DM10 tool DocBot. This would collect the HL7 messages from a local folder which is provided within the command line. Each message within the folder is processed and depending on successful process or failure, they are moved to folder sub folder within the existing folder.
Below are examples of different HL7 messages:
MSH|^~\&|AccMgr|1|||20050110114442||ADT^A02|59910287|P|2.3|||
EVN|A02|20050110114442|||||
PID||R9999^MRN|9999999999^^^1^NHS^1||DUCK^DONALD^D||19241010|M||1|111^DUCK ST^^FOWL^CA^999990000^^M|1|03304040810||1|2||40007716^^^AccMgr^VN^1|123121234|||||||||||
MSH|^~\&|AccMgr|1|||20050110114442||ADT^A18|59910287|P|2.3|||
EVN|A18|20050110114442|||||
PID||R9999^MRN|9999999999^^^1^NHS^1||DUCK^DONALD^D||19241010|M|||111^DUCK ST^^FOWL^CA^999990000^^M||03304040810||1|2||40007716^^^AccMgr^VN^1|123121234|||||||||||
MRG| R9989^MRN|
So as can see from the examples, a HL7 message is broken down into message segments. These are identified by the keys for each segment i.e MSH, EVN, PID and MRG.
There are more message segments within HL7 standard, but these are the ones we care about.
When we validate a HL7 message we look for these identifier keys, if they do not exist, an exception would be thrown Exception processing ADT file: <filename> Missing <segment key> segment
Page Break
Message Segment Break Down
MSH Segment
The first segment we will break down is MSH. This is the Message Header, the main piece of information we are looking for is the highlighted section below:
MSH|^~\&|AccMgr|1|||20050110114442||ADT^A02|59910287|P|2.3|||
This informs use how that message is separated.
| = Field Separator
^ = Component Separator
~ = Repeat Separator
These are the common separator values, though these can be altered to user discretion.
If this field was empty in the HL7 message, then the below error would be returned
Exception processing ADT file: <filename> MSH Segment: Missing Encoding Characters
EVN Segment
The EVN segment contains information for what event type the HL7 message is. This would dictate if the message were a patient insert, update, delete, merge or a merge documents message. This is dictated by the highlighted section below:
EVN|A02|20050110114442|||||
We would read this field to decide the action which needs to be performed, below is a table of the different event types and the action performed.
| EVENT TYPE ID | ACTION PERFORMED |
| A01 | Insert Patient (Reg status set as ‘Admit’) |
| A02 | Insert Patient (Reg status set as ‘Transfer) |
| A04 | Insert Patient (Reg status set as ‘Register) |
| A08 | Update Patient Details |
| A18 | Merge Patient (Reg status set as ‘Merged – Minor number) |
| A28 | Insert Patient (Reg status set as ‘Referral Received) |
| A29 | Delete Patient (Set patient as Inactive) |
| A31 | Update Patient Details |
| A34 | Merge Patient (Reg status set as ‘Merged – Minor number) |
| A40 | Merge Patient Documents |
Any other event type provided would result in warning been thrown Exception processing ADT file: <filename> Invalid event type <Event Type Id>
If this field was empty in the HL7 message, then the below error would be returned
Exception processing ADT file: <filename> EVN Segment: Missing Event Type
PID Segment
The PID section is what holds the information for the patient this message relates too. This is broken down into multiple data fields, below is an example PID segment and table showing how it’s broken down:
PID||R9999^MRN|9999999999^^^1^NHS^1||DUCK^DONALD^D||19241010|M|||111^DUCK ST^^FOWL^CA^999990000^^M||03304040810|||||40007716^^^AccMgr^VN^1|123121234||||||||||20241010|
| Field Name | Field Value | Field Id |
| Segment Id | PID | 0 |
| Patient Id (External) | R9999^MRN | 2 |
| Patient Id (Internal) | 9999999999^^^1^NHS^1 | 3 |
| Patient Name | DUCK^DONALD^D | 5 |
| Patient DOB | 19241010 | 7 |
| Patient Sex | M | 8 |
| Patient Address | 111^DUCK ST^^FOWL^CA^999990000^^M | 11 |
| Patient Phone Number | 03304040810 | 13 |
| Patient Date of Death | 20241010 | 29 |
The data fields with component separators i.e., ^ would be broken down into their own data values. So, example DUCK^DONALD^D would break down too:
Title = D
Forename = Donald
Surname = Duck
If the field Patient Id (Internal) was empty in the HL7 message, then the below error would be returned
Exception processing ADT file: <filename> PID Segment: Missing Internal Patient ID
If the field Patient Name was empty in the HL7 message, then the below error would be returned
Exception processing ADT file: <filename> PID Segment: Missing Patient Name
If the field Patient Address was empty in the HL7 message, then the below error would be returned
Exception processing ADT file: <filename> PID Segment: Missing Patient Address
If the element Patient Forename was empty in the HL7 message, then the below error would be returned
Exception processing ADT file: <filename> Missing Patient Forename element
If the element Patient Surname was empty in the HL7 message, then the below error would be returned
Exception processing ADT file: <filename> Missing Patient Surname element
MRG Segment
The MRG segment is only used for event types A18, A34 and A40. This segment is used to provide the consumer with a patient’s previous identifier.
This information is highlighted in the below example:
MRG| R9989^MRN|
If this field was empty in the HL7 message, then the below error would be returned
Exception processing ADT file: <filename> MRG Segment: Missing PriorPatientID
This Id is used during the merge process to locate the previous patient details. This would do the lookup on the Patient Reference field.
One thing to be aware with the MRG segment, when we attempt to get this Id value. We priorities an Id value, if it is a ‘PAS’ value. An example of this is below:
MRG| R9989^MRN~P12345^PAS|
As the value has a repeat separator ‘~’ this field is broken into 2 separate values ‘R9989^MRN’ and ‘P12345^PAS’. As the second value supplied is defined as the ‘PAS’ value, we would choose this over the MRN value.
If you wish to try parsing any HL7 message’s there are several online tools which will help break down a message
https://hl7messageparser.azurewebsites.net/
PID Element Mappings
| DT | Required | RP/# | ELEMENT NAME | Docman DB Mapping | Docman UI Mapping | FormatOptions/Notes |
| SI | R | Set ID – Patient ID | 1 | |||
| CX | R | Patient ID (External ID) | Reference | Reference | Varchar | |
| CX | R | Y | Patient ID (Internal ID) | Data11 | NHS Number/CHI Number/IHI Number | Must contain national suffix of NHS for England/Wales, CHI for scotland or IHI for Republic of Ireland. |
| CX | R | Y | Alternate Patient ID – PID | Reference | Required by HL7 Structure but not used by Docman | |
| XPN | R | Y | Patient Name | data3^data2^^^data1 | FamilyName^GivenName^^^Title | |
| XPN | O | Mother’s Maiden Name | ||||
| TS | O | Date/Time of Birth | Data44 | DOB | YYYYMMDD | |
| IS | O | Sex | MALE/FEMALE/OTHER | |||
| XPN | O | Y | Patient Alias | |||
| IS | O | Race | ||||
| XAD | O | Y | Patient Address | data5^data6^data7^data8^Data9^data10 | House^No / Road^Locality^Town^County^Post code | |
| IS | B | Country Code | ||||
| XTN | O | Y | Phone Number – Home | Data20 | Home Telephone | If multiple numbers provided separate with ^ |
| XTN | O | Y | Phone Number – Business | |||
| CE | O | Primary Language | ||||
| IS | O | Marital Status | ||||
| IS | O | Religion | ||||
| CX | O | Patient Account Number | ||||
| ST | O | SSN Number – Patient | ||||
| DLN | O | Driver’s License Number – Patient | ||||
| CX | O | Y | Mother’s Identifier | |||
| IS | O | Ethnic Group | ||||
| ST | O | Birth Place | ||||
| ID | O | Multiple Birth Indicator | ||||
| NM | O | Birth Order | ||||
| IS | O | Y | Citizenship | |||
| CE | O | Veterans Military Status | ||||
| CE | O | Nationality | ||||
| TS | O | Patient Death Date and Time | ||||
| ID | O | Patient Death Indicator | ||||
| Usable PID Section | PID|1|Reference|Data11| Reference|data3^data2^^^data1|| Data44||||data5^data6^data7^data8^Data9^data10|| Data20||||||||||||||||| | PID||Reference|NHS Number/CHI Number/IHI Number||FamilyName^GivenName^^^Title||DOB||||House^No / Road^Locality^Town^County^Post code||Home Telephone||||||||||||||||| |