HL7v2 Output Configuration

Sending results to an EMR or other external system requires a valid EMR license. For assistance with configuring HL7v2 output, please contact AMD Technical Support.

Open Settings

To configure HL7v2 output, open the AGNES Connect application, and press the Settings icon in the lower left.

Select Devices Section

Find and select the entry labeled Devices.

Select HL7v2

Find and select the entry labeled HL7v2.

Edit Configuration

Click on the configuration to edit.

Apply or Cancel

Click Apply to save changes.

Press ESC to cancel without saving.

HL7 Settings

Setting	Description
`enabled`	Set to `true` to enable HL7 output. Set to `false` to disable HL7 output.
`allowQuery`	Set to `true` to enable patient queries.
`allowVitals`	Set to `true` to allow sending vitals snapshots. Set to `false` to block sending vitals snapshots.
`allowDocuments`	Set to `true` to allow sending of documents, such as PDF reports and video snapshots.
`allowedExternalExtensions`	List of file extensions to allow for export.
`destination`	Destination of the HL7 vital messages. Accepts a `mllp://`, `mllps://`, `http://`, `https://`, or `file://` URI.
`fileDestination`	Destination of the HL7 file messages. Accepts a `mllp://`, `mllps://`, `http://`, `https://`, or `file://` URI.
`queryDestination`	Destination of HL7 patient info queries. Accepts a `mllp://`, `mllps://`, `http://`, or `https://` URI. Enables the Patient Search tab in AGNES when defined.
`receivingApplication`	Populates the “Receiving Application” field of all outgoing HL7 messages.
`receivingFacility`	Populates the “Receiving Facility” field of all outgoing HL7 messages.
`rawFileUpload`	Set to `true` to upload files without an HL7 wrapper.
`requiredPatientFields`	List of fields that AGNES should require before sending HL7 messages, such as `patientId`, `firstName`, `lastName`, `middleInitial`, `birthDate`, and/or `sex`.
`timestampFormat`	Format for timestamp. Defaults to the HL7v2 standard.
`hl7_vitals_msg`	Configure individual vital message segments. Can override values in the `MSH`, `PID`, `OBR`, and `OBX` segments.
`hl7_document_msg`	Configure individual document message segments. Can override values in the `MSH`, `PID`, `OBR`, and `OBX` segments.
`queryPatientMessage`	Configure the segments of outgoing HL7 queries. Can override values in the `MSH` and `QPD` segments.

Patient Query

Users can query a list of patients from an EMR over HL7 if the EMR system supports it. The user can provide a partial search string to narrow the results.

HL7 Query Endpoint

To enable the Patient Search Tab, define the address of the server to connect to in the HL7 Configuration as queryEndpoint. Once queryEndpoint has been defined, the Patient Search tab in AGNES will be enabled. A QPD section will need to be defined in the HL7 configuration based on the settings in the connected EMR.

Allow Patient Query

Search functionality in AGNES is enabled once queryEndpoint is defined. This can be disabled by setting allowQuery to false.


        allowQuery: false

Copy to clipboard

Customizing HL7 Segments

AGNES produces valid, comprehensive HL7v2 signals by default, but some users may desire additional data or changes to the output. The values of each segment and each field therein can be overridden using the settings hl7_vitals_msg (for discrete vitals observations), hl7_documents_msg (for documents), and queryPatientMessage (for census queries).

To customize a segment, add the segment code as a key under the message’s associated setting. From there, the individual fields can be customized using their number prefixed by an underscore. For instance, _1 will override the first field of the segment. Nested fields are also modified following the same scheme. Fields will only be overwritten if specified.

As an example, the following settings will capitalize only on the patient’s last name when saving observations:

Copy to clipboard


          hl7_vitals_msg:
  PID:
    _5:
      _0:
        _1: {{ patient.lastName.value.toUpperCase() }}

In some cases, a field in an HL7 segment may have a variable type, such as in the QPD segment’s third field (“User Parameters”). In these cases, AGNES allows defining the structure of the message using _def keys to define custom structures, so that the message may suit the receiving application’s needs. For instance, pass query search parameters by defining the “User Parameters” field of the QPD segment:

Copy to clipboard


          queryPatientMessage:
  QPD:
    _3:
      _0:
        _1:
          _def:
            dt: ST
            opt: R
            rep: 0
          _0: Status
        _2:
          _def:
            dt: ST
            opt: R
            rep: true
          _0: Active

Copy to clipboard


          queryPatientMessage:
  QPD:
    _3:
      _0:
        _1:
          _def:
            dt: ST
            opt: R
            rep: 0
          _0: Status
        _2:
          _def:
            dt: ST
            opt: R
            rep: true
          _0: Active

_def keys must contain the following properties:

Property	Description
`dt`	HL7v2 data type. Refer to the HL7 standard for valid values.
`desc`	Field description. Not transmitted.
`opt`	Optionality. `R` for required, `O` for optional.
`rep`	Repeatability. `0` or `false` for no repetition.

Available Template Variables

When overriding HL7 segments or computing the endpoint for the request, the following template variables are available.

Variable	Returns
`{{document.source}}`	AGNES module which added the document
`{{document.data}}`	Data from document
`{{document.timestamp}}`	Timestamp of document with formatting
`{{document.key}}`	Unique key assigned to document
`{{document.ext}}`	Extension of document
`{{document.filename}}`	Filename of document
`{{document.isValid}}`	Boolean
`{{document.mime}}`	MIME type of file
`{{document.thumbnail}}`	Path of thumbnail file used
`{{document.editable}}`	Boolean
`{{patient.sex.value}}`	Patient Sex
`{{patient.patientId.value}}`	Patient ID (not visible from portal)
`{{patient.middleInitial.value}}`	Patient Middle Initial
`{{patient.extra.value}}`	Patient Extra Field (not visible from portal) used to pass arbitrary values
`{{patient.birthDate.value}}`	Patient Birth Date
`{{patient.patientExternalId.value}}`	Patient External ID (visible to user)
`{{patient.firstName.value}}`	Patient First Name
`{{patient.lastName.value}}`	Patient Last Name
`{{user.firstName}}`	First Name of submitter
`{{user.lastName}}`	Last Name of submitter
`{{user.username}}`	Username of submitter
`{{user.org}}`	Organization ID of submitter
`{{user.sub}}`	User ID of submitter
`{{user.npi}}`	EMR ID of submitter
`{{user.fullName}}`	Full Name of submitter
`{{timestamp}}`	Timestamp of save operation in HL7v2 formatting
`{{docTimestamp}}`	Document creation timestamp in HL7v2 formatting

Sample Configurations

Basic Configuration

Copy to clipboard


          enabled: true

keepOpen: true
destination: file:///hl7/message-{{document.timestamp}}.hl7
fileDestination: file:///hl7/message-{{document.timestamp}}.hl7

allowExternalDocuments: true
allowVideoSnapshots: true
allowPDFReport: true

# This option will disable the HL7 wrapper for file destinations
#rawFileUpload: true

allowVitals: true
combinedVitalsField: 'OBX'

# If you require certain patient fields to be present, specify them here
#requiredPatientFields:
#        - 'patientId'

allowedExternalExtensions:
    - jpg
    - txt
    - pdf
    - tif

timestampFormat: YYYYMMDDHHmmss

hl7_vitals_msg:
    MSH:
    PID:
    OBR:
    OBX:

hl7_document_msg:
    MSH:
    PID:
    OBR:
    OBX:

Example with Variables

Copy to clipboard


          enabled: true

keepOpen: true
destination: file:///hl7/vitals-{{docTimestamp}}.hl7
fileDestination: file:///hl7/file-{{docTimestamp}}.hl7

allowExternalDocuments: true
allowVideoSnapshots: true
allowPDFReport: true

# This option will disable the HL7 wrapper for file destinations
#rawFileUpload: true

allowVitals: true
combinedVitalsField: 'OBX'

# If you require certain patient fields to be present, specify them here
#requiredPatientFields:
#        - 'patientId'

allowedExternalExtensions:
    - jpg
    - txt
    - pdf
    - tif

timestampFormat: YYYYMMDDHHmmss

hl7_vitals_msg:
    MSH:
        '_3': '3)Doc_Timestamp={{document.timestamp}}'
        '_4': '4)Timestamp={{timestamp}}'
        '_5': '5)Patient_Birthdate={{patient.birthDate.value}}'
    PID:
        '_1': '1)Patient_ID={{patient.patientId.value}}'
        '_8': '8)Patient_First_Name={{patient.firstName.value}}'
        '_9': '9)Patient_Middle_Initial={{patient.middleInitial.value}}'
        '_10': '10)Patient_Last_Name={{patient.lastName.value}}'
    OBR:
        '_2': '2)Document_Timestamp={{document.timestamp}}'
        '_3': '3)Document_Filename={{document.filename}}'
        '_4': '4)Patient_Sex={{patient.sex.value}}'
    OBX:
        '_1': '1)User_Full_Name={{user.fullname}}'
        '_4': '4)User_Username={{user.username}}'
        '_7': '7)User_First_Name={{user.firstname}}'
        '_8': '8)User_Last_Name={{user.lastname}}'
        '_10': '10)User_Org={{user.org}}'
        '_11': '11)User_Sub={{user.sub}}'
        '_13': '13)User_Meta={{user.meta}}'
        '_15': '15)User_NPI={{user.npi}}'

hl7_document_msg:
    MSH:
        '_3': '3)Doc_Timestamp={{document.timestamp}}'
        '_4': '4)Timestamp={{timestamp}}'
        '_5': '5)Patient_Birthdate={{patient.birthDate.value}}'
        '_6': '6)User_NPI={{user.npi}}'
    PID:
        '_1': '1)Patient_ID={{patient.patientId.value}}'
        '_8': '8)Patient_First_Name={{patient.firstName.value}}'
        '_9': '9)Patient_Middle_Initial={{patient.middleInitial.value}}'
        '_10': '10)Patient_Last_Name={{patient.lastName.value}}'
    OBR:
        '_2': '2)Document_Timestamp={{document.timestamp}}'
        '_3': '3)Document_Filename={{document.filename}}'
        '_4': '4)Patient_Sex={{patient.sex.value}}'
        '_14': '14)User_First_Name={{user.firstname}}'
        '_15': '15)User_Last_Name={{user.lastname}}'
        '_10': '10)User_Org={{user.org}}'
        '_11': '11)User_Sub={{user.sub}}'
        '_13': '13)User_Meta={{user.meta}}'
    OBX:
        '_1': '1)User_Full_Name={{user.fullname}}'
        '_4': '4)User_Username={{user.username}}'

Patient Query Example

Copy to clipboard


          enabled: true

keepOpen: true
destination: mllps://192.168.1.238:6007
fileDestination: mllps://192.168.1.238:6007
queryEndpoint: mllps://192.168.1.238:6007

allowExternalDocuments: true
allowVideoSnapshots: true
allowPDFReport: true

# This option will disable the HL7 wrapper for file destinations
#rawFileUpload: true

allowVitals: true
combinedVitalsField: 'OBX'

# If you require certain patient fields to be present, specify them here
#requiredPatientFields:
#        - 'patientId'

allowedExternalExtensions:
    - jpg
    - txt
    - pdf
    - tif

timestampFormat: YYYYMMDDHHmmss

queryPatientMessage:
    MSH:
        '_2': 'TeleHealth'
        '_5': 'ApplicationName'
        '_6': 'Facility'
    QPD:
        '_3':
            '_0':
                '_1':
                    '_def':
                        'dt': 'ST'
                        'desc': 'Family Name Segment'
                        'opt': 'R'
                        'rep': 0
                    '_0': 'PID-5-0'
                '_2':
                    '_def':
                        'dt': 'ST'
                        'desc': 'Family Name'
                        'opt': 'O'
                        'rep': 0
                    '_0': '{{patient.lastName}}*'
            '_1':
                '_1':
                    '_def':
                        'dt': 'ST'
                        'desc': 'Given Name Segment'
                        'opt': 'R'
                        'rep': 0
                    '_0': 'PID-5-1'
                '_2':
                    '_def':
                        'dt': 'ST'
                        'desc': 'Given Name'
                        'opt': 'O'
                        'rep': 0
                    '_0': '{{patient.firstName}}*'
            '_2':
                '_1':
                    '_def':
                        'dt': 'ST'
                        'desc': 'Segment'
                        'opt': 'R'
                        'rep': 0
                    '_0': 'PID-2-1'
                '_2':
                    '_def':
                        'dt': 'ST'
                        'desc': 'Patient ID'
                        'opt': 'O'
                        'rep': 0
                    '_0': '{{patient.patientExternalId}}*'

hl7_vitals_msg:
    MSH:
        'ReceivingApplication': 'ApplicationName'
        'ReceivingFacility': 'Facility'
    PID:
    OBR:
    OBX:

hl7_document_msg:
    MSH:
        'ReceivingApplication': 'ApplicationName'
        'ReceivingFacility': 'Facility'
    PID:
    OBR:
    OBX:

Copy to clipboard


          enabled: true

keepOpen: true
destination: mllps://192.168.1.238:6007
fileDestination: mllps://192.168.1.238:6007
queryEndpoint: mllps://192.168.1.238:6007

allowExternalDocuments: true
allowVideoSnapshots: true
allowPDFReport: true

# This option will disable the HL7 wrapper for file destinations
#rawFileUpload: true

allowVitals: true
combinedVitalsField: 'OBX'

# If you require certain patient fields to be present, specify them here
#requiredPatientFields:
#        - 'patientId'

allowedExternalExtensions:
    - jpg
    - txt
    - pdf
    - tif

timestampFormat: YYYYMMDDHHmmss

queryPatientMessage:
    MSH:
        '_2': 'TeleHealth'
        '_5': 'ApplicationName'
        '_6': 'Facility'
    QPD:
        '_3':
            '_0':
                '_1':
                    '_def':
                        'dt': 'ST'
                        'desc': 'Family Name Segment'
                        'opt': 'R'
                        'rep': 0
                    '_0': 'PID-5-0'
                '_2':
                    '_def':
                        'dt': 'ST'
                        'desc': 'Family Name'
                        'opt': 'O'
                        'rep': 0
                    '_0': '{{patient.lastName}}*'
            '_1':
                '_1':
                    '_def':
                        'dt': 'ST'
                        'desc': 'Given Name Segment'
                        'opt': 'R'
                        'rep': 0
                    '_0': 'PID-5-1'
                '_2':
                    '_def':
                        'dt': 'ST'
                        'desc': 'Given Name'
                        'opt': 'O'
                        'rep': 0
                    '_0': '{{patient.firstName}}*'
            '_2':
                '_1':
                    '_def':
                        'dt': 'ST'
                        'desc': 'Segment'
                        'opt': 'R'
                        'rep': 0
                    '_0': 'PID-2-1'
                '_2':
                    '_def':
                        'dt': 'ST'
                        'desc': 'Patient ID'
                        'opt': 'O'
                        'rep': 0
                    '_0': '{{patient.patientExternalId}}*'

hl7_vitals_msg:
    MSH:
        'ReceivingApplication': 'ApplicationName'
        'ReceivingFacility': 'Facility'
    PID:
    OBR:
    OBX:

hl7_document_msg:
    MSH:
        'ReceivingApplication': 'ApplicationName'
        'ReceivingFacility': 'Facility'
    PID:
    OBR:
    OBX: