{"version":"https:\/\/jsonfeed.org\/version\/1","title":"Docman 10 HL7 Integration > Docman Help","home_page_url":"https:\/\/help.docman.com\/knowledge-base\/docman-10-hl7-integration\/","feed_url":"https:\/\/help.docman.com\/knowledge-base\/docman-10-hl7-integration\/feed\/json","author":{"name":"nextSTL","url":"https:\/\/help.docman.com"},"items":[{"title":"Docman 10 HL7 Integration","date_published":"2021-02-26T10:51:54Z","date_modified":"2021-03-09T18:33:46Z","id":"https:\/\/help.docman.com\/knowledge-base\/docman-10-hl7-integration\/","url":"https:\/\/help.docman.com\/knowledge-base\/docman-10-hl7-integration\/","author":{"name":"Oliver Edwards","url":"","avatar":"https:\/\/secure.gravatar.com\/avatar\/916760a3861c94b0f12d9658070815ac6150c9ba5291c9b5304733d70e0fdb9e?s=96&d=mm&r=g"},"summary":"\nInstalling Mirth and Docbot\n\n\n\nBefore following this guide, Advanced will need to provide you with a API Consumer that has permissions to your Docman 10 organisation. \n\n\n\nOnce Advanced have provided you with the API consumer, download the AHC.Mirth.\u2026","content_html":"\n

Installing Mirth and Docbot<\/h2>\n\n\n\n

Before following this guide, Advanced will need to provide you with a API Consumer that has permissions to your Docman 10 organisation. <\/p>\n\n\n\n

Once Advanced have provided you with the API consumer, download the AHC.Mirth.ADT.Setup.exe.<\/p>\n\n\n\n

Running the exe with -help or no switches will output the example commands.<\/p>\n\n\n\n

Docbot is a commandline utility used for validating and transforming HL7 messages into Docman 10 via a rest API. <\/p>\n\n\n\n

Download Installer<\/strong><\/a><\/h5>\n\n\n\n

The installer does the following;<\/p>\n\n\n\n

  1. The installer is a command tool and will output the installer options when run. <\/li>
  2. Start by downloading the AHC.Mirth.ADT.Setup.exe using the link above, this tool needs access to https:\/\/apps.docman.com <\/li>
  3. It will then install Java, then Mirth Connect.<\/li>
  4. During the automated install you may be prompted to install the Mirth Administrator Client manually to accept a license agreement!<\/li>
  5.  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>\\<\/li>
  6. 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.<\/li>
  7. When the script completes restart the machine.<\/li>
  8. 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<\/li><\/ol>\n\n\n\n
    \"\"<\/figure>\n\n\n\n

    Configuring Mirth<\/h4>\n\n\n\n

    Once you have installed Mirth, you will need to import the channel and update the listener address and port if they don\u2019t match what the PAS System has configured.<\/p>\n\n\n\n

    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.<\/p>\n\n\n\n

    \"C:\\temp\\Docman.ADT.Sync.Mirth.Channel.Live.xml\"<\/p>\n\n\n\n

    \"C:\\temp\\Docman.ADT.Sync.Mirth.Channel.Test.xml\"<\/p>\n\n\n\n

    On the Source screen, change the connector type to \u2018LLP Listener\u2019, change the values for \u2018Listener Address\u2019 and \u2018Listener Port\u2019. 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\u2019s address where the messages are being sent. Next click the Destination tab.<\/p>\n\n\n\n

    If you haven\u2019t setup using the tool then the destination location will need updating to match your install directory.<\/p>\n\n\n\n

    The File Name directory should contain the following naming convention:<\/p>\n\n\n\n

    DMMSG-${message.type}-${date.get('yyyyMdH.m.s.mm')}.${UUID}.hl7<\/p>\n\n\n\n

    Template field should contain: ${message.rawData}<\/p>\n\n\n\n

    Next, click Channels, then Deploy Channel.<\/p>\n\n\n\n

    Mirth is now configured and is actively monitoring the specified port<\/p>\n\n\n\n

    Docman HL7 Implementation Specification<\/h2>\n\n\n\n

    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. <\/p>\n\n\n\n

    Below are examples of different HL7 messages: 
     
    MSH|^~\\&|AccMgr|1|||20050110114442||ADT^A02|59910287|P|2.3||| <\/p>\n\n\n\n

    EVN|A02|20050110114442||||| <\/p>\n\n\n\n

    PID||R9999^MRN|9999999999^^^1^NHS^1||DUCK^DONALD^D||19241010|M||1|111^DUCK ST^^FOWL^CA^999990000^^M|1|03304040810<\/a>||1|2||40007716^^^AccMgr^VN^1|123121234||||||||||| 
     <\/p>\n\n\n\n

     
    MSH|^~\\&|AccMgr|1|||20050110114442||ADT^A18|59910287|P|2.3||| <\/p>\n\n\n\n

    EVN|A18|20050110114442||||| <\/p>\n\n\n\n

    PID||R9999^MRN|9999999999^^^1^NHS^1||DUCK^DONALD^D||19241010|M|||111^DUCK ST^^FOWL^CA^999990000^^M||03304040810<\/a>||1|2||40007716^^^AccMgr^VN^1|123121234||||||||||| <\/p>\n\n\n\n

    MRG| R9989^MRN| <\/p>\n\n\n\n

    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. <\/p>\n\n\n\n

     
    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 <\/p>\n\n\n\n

    Page Break <\/p>\n\n\n\n

    Message Segment Break Down <\/h3>\n\n\n\n

    MSH Segment <\/h4>\n\n\n\n

    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: <\/p>\n\n\n\n

    MSH|^~\\&|AccMgr|1|||20050110114442||ADT^A02|59910287|P|2.3||| <\/p>\n\n\n\n

    This informs use how that message is separated.  <\/p>\n\n\n\n

    | = Field Separator <\/p>\n\n\n\n

    ^ = Component Separator <\/p>\n\n\n\n

    ~ = Repeat Separator <\/p>\n\n\n\n

    These are the common separator values, though these can be altered to user discretion. <\/p>\n\n\n\n

    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 <\/p>\n\n\n\n

    EVN Segment <\/h4>\n\n\n\n

    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: <\/p>\n\n\n\n

     
    EVN|A02|20050110114442||||| <\/p>\n\n\n\n

    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. <\/p>\n\n\n\n

    EVENT TYPE ID <\/td>ACTION PERFORMED <\/td><\/tr>
    A01<\/strong> <\/td>Insert Patient (Reg status set as \u2018Admit\u2019) <\/td><\/tr>
    A02<\/strong> <\/td>Insert Patient (Reg status set as \u2018Transfer) <\/td><\/tr>
    A04<\/strong> <\/td>Insert Patient (Reg status set as \u2018Register) <\/td><\/tr>
    A08<\/strong> <\/td>Update Patient Details <\/td><\/tr>
    A18<\/strong> <\/td>Merge Patient (Reg status set as \u2018Merged \u2013 Minor number) <\/td><\/tr>
    A28<\/strong> <\/td>Insert Patient (Reg status set as \u2018Referral Received) <\/td><\/tr>
    A29<\/strong> <\/td>Delete Patient (Set patient as Inactive) <\/td><\/tr>
    A31<\/strong> <\/td>Update Patient Details <\/td><\/tr>
    A34<\/strong> <\/td>Merge Patient (Reg status set as \u2018Merged \u2013 Minor number) <\/td><\/tr>
    A40<\/strong> <\/td>Merge Patient Documents <\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    Any other event type provided would result in warning been thrown Exception processing ADT file: <filename> Invalid event type <Event Type Id> <\/em><\/strong><\/p>\n\n\n\n

    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 <\/strong><\/p>\n\n\n\n

    PID Segment <\/h4>\n\n\n\n

    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\u2019s broken down: <\/p>\n\n\n\n

    PID||R9999^MRN|9999999999^^^1^NHS^1||DUCK^DONALD^D||19241010|M|||111^DUCK ST^^FOWL^CA^999990000^^M||03304040810<\/a>|||||40007716^^^AccMgr^VN^1|123121234||||||||||20241010| <\/p>\n\n\n\n

    Field Name<\/strong> <\/td>Field Value<\/strong> <\/td>Field Id<\/strong> <\/td><\/tr>
    Segment Id <\/td>PID <\/td>0 <\/td><\/tr>
    Patient Id (External) <\/td>R9999^MRN <\/td>2 <\/td><\/tr>
    Patient Id (Internal) <\/td>9999999999^^^1^NHS^1 <\/td>3 <\/td><\/tr>
    Patient Name <\/td>DUCK^DONALD^D <\/td>5 <\/td><\/tr>
    Patient DOB <\/td>19241010 <\/td>7 <\/td><\/tr>
    Patient Sex <\/td>M <\/td>8 <\/td><\/tr>
    Patient Address <\/td>111^DUCK ST^^FOWL^CA^999990000^^M <\/td>11 <\/td><\/tr>
    Patient Phone Number <\/td>03304040810<\/a> <\/td>13 <\/td><\/tr>
    Patient Date of Death <\/td>20241010 <\/td>29 <\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    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: <\/p>\n\n\n\n

    Title = D <\/p>\n\n\n\n

    Forename = Donald <\/p>\n\n\n\n

    Surname = Duck <\/p>\n\n\n\n

    If the field Patient Id (Internal) <\/strong>was empty in the HL7 message, then the below error would be returned 
    Exception processing ADT file: <filename> PID Segment: Missing Internal Patient ID <\/em><\/strong><\/p>\n\n\n\n

    If the field Patient Name <\/strong>was empty in the HL7 message, then the below error would be returned 
    Exception processing ADT file: <filename> PID Segment: Missing Patient Name <\/em><\/strong><\/p>\n\n\n\n

    If the field Patient Address <\/strong>was empty in the HL7 message, then the below error would be returned 
    Exception processing ADT file: <filename> PID Segment: Missing Patient Address <\/strong><\/em><\/p>\n\n\n\n

    If the element Patient <\/strong>Forename<\/strong> <\/strong>was empty in the HL7 message, then the below error would be returned 
    Exception processing ADT file: <filename> Missing Patient Forename element <\/p>\n\n\n\n

    If the element Patient Surname <\/strong>was empty in the HL7 message, then the below error would be returned 
    Exception processing ADT file: <filename> Missing Patient Surname element <\/em><\/strong><\/p>\n\n\n\n

    MRG Segment <\/em><\/strong><\/h4>\n\n\n\n

    The MRG segment is only used for event types A18, A34 and A40. This segment is used to provide the consumer with a patient\u2019s previous identifier. 
     <\/p>\n\n\n\n

    This information is highlighted in the below example: 
    MRG| R9989^MRN| <\/p>\n\n\n\n

    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 <\/strong><\/em><\/p>\n\n\n\n

    This Id is used during the merge process to locate the previous patient details. This would do the lookup on the Patient Reference field.  <\/p>\n\n\n\n

    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 \u2018PAS\u2019 value. An example of this is below:  <\/p>\n\n\n\n

     
    MRG| R9989^MRN~P12345^PAS| <\/p>\n\n\n\n

    As the value has a repeat separator \u2018~\u2019 this field is broken into 2 separate values \u2018R9989^MRN\u2019 and \u2018P12345^PAS\u2019. As the second value supplied is defined as the \u2018PAS\u2019 value, we would choose this over the MRN value. <\/p>\n\n\n\n

    If you wish to try parsing any HL7 message\u2019s there are several online tools which will help break down a message 
     
    https:\/\/hl7messageparser.azurewebsites.net\/<\/a> <\/p>\n\n\n\n

    https:\/\/hl7.cc\/farser<\/a><\/p>\n\n\n\n

    PID Element Mappings<\/h2>\n\n\n\n
    <\/th><\/th><\/th><\/th><\/th><\/th><\/th><\/tr><\/thead>
    DT<\/td>Required<\/td>RP\/#<\/td>ELEMENT NAME<\/td>Docman DB Mapping<\/td>Docman UI Mapping<\/td>FormatOptions\/Notes<\/td><\/tr>
    SI<\/td>R<\/td><\/td>Set ID \u2013 Patient ID<\/td>1<\/td><\/td><\/td><\/tr>
    CX<\/td>R<\/td><\/td>Patient ID (External ID)<\/td>Reference<\/td>Reference<\/td>Varchar<\/td><\/tr>
    CX<\/td>R<\/td>Y<\/td>Patient ID (Internal ID)<\/td>Data11<\/td>NHS Number\/CHI Number\/IHI Number<\/td>Must contain national suffix of NHS for England\/Wales, CHI for scotland or IHI for Republic of Ireland. <\/td><\/tr>
    CX<\/td>R<\/td>Y<\/td>Alternate Patient ID \u2013 PID<\/td>Reference<\/td><\/td>Required by HL7 Structure but not used by Docman<\/td><\/tr>
    XPN<\/td>R<\/td>Y<\/td>Patient Name<\/td>data3^data2^^^data1<\/td>FamilyName^GivenName^^^Title<\/td><\/td><\/tr>
    XPN<\/td>O<\/td><\/td>Mother\u2019s Maiden Name<\/td><\/td><\/td><\/td><\/tr>
    TS<\/td>O<\/td><\/td>Date\/Time of Birth<\/td>Data44<\/td>DOB<\/td>YYYYMMDD<\/td><\/tr>
    IS<\/td>O<\/td><\/td>Sex<\/td><\/td><\/td>MALE\/FEMALE\/OTHER<\/td><\/tr>
    XPN<\/td>O<\/td>Y<\/td>Patient Alias<\/td><\/td><\/td><\/td><\/tr>
    IS<\/td>O<\/td><\/td>Race<\/td><\/td><\/td><\/td><\/tr>
    XAD<\/td>O<\/td>Y<\/td>Patient Address<\/td>data5^data6^data7^data8^Data9^data10<\/td>House^No \/ Road^Locality^Town^County^Post code<\/td><\/td><\/tr>
    IS<\/td>B<\/td><\/td>Country Code<\/td><\/td><\/td><\/td><\/tr>
    XTN<\/td>O<\/td>Y<\/td>Phone Number \u2013 Home<\/td>Data20<\/td>Home Telephone<\/td>If multiple numbers provided separate with ^<\/td><\/tr>
    XTN<\/td>O<\/td>Y<\/td>Phone Number \u2013 Business<\/td><\/td><\/td><\/td><\/tr>
    CE<\/td>O<\/td><\/td>Primary Language<\/td><\/td><\/td><\/td><\/tr>
    IS<\/td>O<\/td><\/td>Marital Status<\/td><\/td><\/td><\/td><\/tr>
    IS<\/td>O<\/td><\/td>Religion<\/td><\/td><\/td><\/td><\/tr>
    CX<\/td>O<\/td><\/td>Patient Account Number<\/td><\/td><\/td><\/td><\/tr>
    ST<\/td>O<\/td><\/td>SSN Number \u2013 Patient<\/td><\/td><\/td><\/td><\/tr>
    DLN<\/td>O<\/td><\/td>Driver\u2019s License Number \u2013 Patient<\/td><\/td><\/td><\/td><\/tr>
    CX<\/td>O<\/td>Y<\/td>Mother\u2019s Identifier<\/td><\/td><\/td><\/td><\/tr>
    IS<\/td>O<\/td><\/td>Ethnic Group<\/td><\/td><\/td><\/td><\/tr>
    ST<\/td>O<\/td><\/td>Birth Place<\/td><\/td><\/td><\/td><\/tr>
    ID<\/td>O<\/td><\/td>Multiple Birth Indicator<\/td><\/td><\/td><\/td><\/tr>
    NM<\/td>O<\/td><\/td>Birth Order<\/td><\/td><\/td><\/td><\/tr>
    IS<\/td>O<\/td>Y<\/td>Citizenship<\/td><\/td><\/td><\/td><\/tr>
    CE<\/td>O<\/td><\/td>Veterans Military Status<\/td><\/td><\/td><\/td><\/tr>
    CE<\/td>O<\/td><\/td>Nationality<\/td><\/td><\/td><\/td><\/tr>
    TS<\/td>O<\/td><\/td>Patient Death Date and Time<\/td><\/td><\/td><\/td><\/tr>
    ID<\/td>O<\/td><\/td>Patient Death Indicator<\/td><\/td><\/td><\/td><\/tr>
    <\/td><\/td><\/td><\/td><\/td><\/td><\/td><\/tr>
    <\/td><\/td><\/td>Usable PID Section <\/td>PID|1|Reference|Data11|
    Reference|data3^data2^^^data1||
    Data44||||data5^data6^data7^data8^Data9^data10||
    Data20|||||||||||||||||<\/td>    		PID||Reference|NHS Number\/CHI Number\/IHI Number||FamilyName^GivenName^^^Title||DOB||||House^No \/ Road^Locality^Town^County^Post code||Home Telephone|||||||||||||||||<\/td><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    PID Element Generator<\/h2>\n\n\n\n
    GenerateHL7-PID-Section<\/a>Download<\/a><\/div>\n\n\n\n

    <\/p>\n","tags":[]}]}