HL7 Connectors support generating HL7 documents from XML and converting HL7 documents into XML.
When receiving HL7 documents, HL7 Connectors validate interchange headers and convert the HL7 document into XML. This is useful as a staging step, as XML is the primary format that ArcESB uses to manipulate data within a flow. The HL7 Connector automatically reads the input file to determine the appropriate schema, then parses the document according to this schema.
When generating HL7 documents, HL7 Connectors convert XML into HL7 document syntax and apply the appropriate interchange headers. This is useful as the final step for creating an HL7 document, after the XML data has been fetched and transformed elsewhere in the flow.
This section contains all of the configurable connector properties.
Settings related to the core operation of the connector.
- Connector Id The static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.
- Connector Description An optional field to provide free-form description of the connector and its role in the flow.
- Translation Type Whether the connector should convert HL7 documents into XML, or generate HL7 documents from XML.
Settings related to the message headers. When converting HL7 documents into XML, the document headers will be validated against these settings; when generating HL7 documents from XML, these settings will be used to generate document headers.
- Sending Application Namespace Id (MSH3.1) In conjunction with the other 3.X elements, identifies the application sending the HL7 document.
- Sending Application Universal Id (MSH3.2) In conjunction with the other 3.X elements, identifies the application sending the HL7 document.
- Sending Application Universal Id Type (MSH3.3) In conjunction with the other 3.X elements, identifies the application sending the HL7 document.
- Sending Facility Namespace Id (MSH4.1) In conjunction with the other 4.X elements, identifies the facility sending the HL7 document.
- Sending Facility Universal Id (MSH4.2) In conjunction with the other 4.X elements, identifies the facility sending the HL7 document.
- Sending Facility Universal Id Type (MSH4.3) In conjunction with the other 4.X elements, identifies the facility sending the HL7 document.
- Receiving Application Namespace Id (MSH5.1) In conjunction with the other 5.X elements, identifies the application receiving the HL7 document.
- Receiving Application Universal Id (MSH5.2) In conjunction with the other 5.X elements, identifies the application receiving the HL7 document.
- Receiving Application Universal Id Type (MSH5.3) In conjunction with the other 5.X elements, identifies the application receiving the HL7 document.
- Receiving Facility Namespace Id (MSH6.1) In conjunction with the other 6.X elements, identifies the facility receiving the HL7 document.
- Receiving Facility Universal Id (MSH6.2) In conjunction with the other 6.X elements, identifies the facility receiving the HL7 document.
- Receiving Facility Universal Id Type (MSH6.3) In conjunction with the other 6.X elements, identifies the facility receiving the HL7 document.
Settings related to generating and requesting acknowledgments.
- Acknowledgment Type Whether or not acknowledgments should be generated and requested.
- Route ACKs to Connector The specified connector will generate acknowledgments using the transaction data received by the current connector. The specified connector adds interchange headers and passes the acknowledgment along in the flow like any other message. Thus this should typically be set to a pre-configured HL7 Connector that generates outbound documents for the intended recipient.
Settings related to the automatic processing of files by the connector.
- Send A toggle that instructs the connector to automatically send files when they are ready.
- Retry Interval The interval the connector will wait before retrying a failed send.
- Max Attempts The number of attempts the connector will make to send the message. Setting this value to 1 instructs the connector to only make the initial send attempt without retrying. The connector waits the duration specified by Retry Interval between each attempt.
Settings that determine where on disk files will be processed from, and where they will be placed after processing.
- Input Folder (Send) Files placed in this folder will be processed by the connector. If Send Automation is enabled, the connector will automatically poll this location for files to process.
- Output Folder (Receive) Files will be placed here after being processed by the connector. If the connector is connected to another connector in the flow, files will not remain here and will instead be passed along to the Input/Send folder for the connected connector.
- Processed Folder (Sent) After processing a file, the connector will place a copy of the processed file in this folder if Save to Sent Folder is enabled. This copy of the file will not be passed along to the next connector in the flow.
Settings that specify which characters separate elements, segments, etc.
- Data Element Separator The character that separates individual data elements within the document.
- Component Element Separator The character that separates elements within a composite data structure in the document.
- Segment Terminator The character that indicates the end of a segment within the document.
- Release Char The character that ‘releases’ or ‘escapes’ the next character, overriding its usual meaning. This allows reserved characters to appear as data withing documents, as long as they are preceded by the Release Char.
- Repetition Char The character that indicates repetition of element values.
- Suffix Appended to the Segment Terminator to distinguish segments.
Settings related to the allocation of resources to the connector.
- Max Workers The maximum number of worker threads that will be consumed from the threadpool to process files on this connector. If set, overrides the default setting from the Profile tab.
- Max Files The maximum number of files that will be processed by the connector each time worker threads are assigned to the connector. If set, overrides the default setting from the Profile tab.
Settings not included in the previous categories.
- Transmission Control Whether the connector should wait for a transmission to be acknowledged before beginning the next transmission.
- Batch Transactions Whether multiple transactions should be grouped together in a single output file. If false, each transaction found in the interchange will result in a separate output document.
- Expand Qualifier Values When translating EDIFACT into XML, whether elements containing an EDI qualifier will have child elements ‘Code’ and ‘Value’ to express the qualifier code and value. For example:
- Send Filter A glob pattern filter to determine which files in the Send folder will be processed by the connector (e.g. *.edi). Negative patterns may be used to indicate files that should not be processed by the connector (e.g. -*.tmp). Multiple patterns may be separated by commas, with later filters taking priority except when an exact match is found.
- Local File Scheme A filemask for determining local file names as they are processed by the connector. The following macros may be used to reference contextual information:
%ConnectorId%, %Filename%, %FilenameNoExt%, %Ext%, %ShortDate%, %LongDate%, %RegexFilename:%, %DateFormat:%, %ControlNumber%, %TransactionControlNumber%, %TransactionCode%, %StandardVersion%.
As an example: %FilenameNoExt%_%ControlNumber%%Ext%
- Parent Connector The connector from which settings should be inherited, unless explicitly overwritten within the existing connector configuration. Must be set to a connector of the same type as the current connector.
- Strict Schema Validation Whether the connector should Ignore, Warn, or Fail when the following are detected: Repeat counts above the allowed number; missing required elements/segments; invalid qualifier and code values; disallowed element lengths; invalid element values.
Settings for specific use cases.
- Other Settings Allows configuration of hidden connector settings in a semicolon-separated list, like
setting1=value1;setting2=value2. Normal connector use cases and functionality should not require use of these settings.
XML to HL7
When generating HL7 files, you must select the Translation Type to be
XML to HL7. The application will read all of the header information from the settings configured in the Settings page for this connector.
Once you have configured the connector with the settings from your trading partner agreement, click the Input tab and select Create Test Files from the More menu. The application will create various test XML files, which provide example data of what the XML should look like for the connector to generate a HL7 document. You can also then select the documents and then click Send to see the generated HL7 documents.
HL7 to XML
When generating XML, you must select the Translation Type to be
HL7 to XML. The application will only process HL7 files when this option is selected. You will need to set the settings for the trading partner agreement on this page for the application to validate the information in HL7 documents during processing. XML files will be generated into the Output folder for this connector.
Click the Input tab and select Create Test Files in the More menu to create test HL7 files for several HL7 documents. You can select these documents and click Send to see the generated XML.
Acknowledgements can be automatically generated and processed by the application.
Original Mode Acknowledgements
This is an indication that an interchange has taken place between the two parties (though not necessarily that any individual message has been exchanged) and is generated automatically in response to a request in the interchange.
HL7 Connectors in XML-to-EDI can be configured so that original mode acknowledgements can be requested for an interchange. Select “Original Mode” in the
Acknowledgement Type setting in the Settings tab of the connector to direct the connector to maintain a Pending ACK status for the transmission until the appropriate acknowledgements have been returned and processed.
The above sketch shows a complete message exchange from the standpoint of the message originator. An HL7 Connector in EDI-to-XML mode generates the document to be exchanged (1) and holds it in a Pending ACK state. The trading partner processes the transmission in their business logic and creates acknowledgements in accordance with the configured exchange parameters and the bidirectional agreement between parties (2). When the acknowledgements are returned, they are parsed with an HL7 Connector (EDI-to-XML) and routed to the original HL7 Connector (XML-to-EDI) to resolve the status of the transfer (3).
Note that the
Transmission Control setting in the advanced tab controls the flow of documents as it relates to their acknowledgements. When this is set to True, the connector will wait for an acknowledgement of the current message before beginning to process the next message.
When HL7 acknowledgements are received at an HL7 Connector in EDI-to-XML mode, the connector can be configured to automatically route any detected acknowledgements to the HL7 Connector (in XML-to-EDI mode) that originated the transmission: Select the originating HL7 Connector (XML-to-EDI) in the Route ACKs to Connector menu in the settings for the receiving HL7 Connector (EDI-to-XML).
The configured receiving HL7 Connector (XML-to-EDI) will then pair the acknowledgements to the original message and resolve the matching message.
When a HL7 Connector in EDI-to-XML mode is processing received messages from the originator and generating XML, you can tell the connector to automatically generate original mode acknowledgements by selecting the Original Mode option in the
Acknowledgement Type setting in the Settings tab. You must route these acknowledgements to an HL7 Connector in XML-to-EDI mode to generate the HL7 acknowledgement: In the Route ACKs to Connector menu, select the HL7 Connector (XML-to-EDI) that generates HL7 documents for this partner.
As shown in the above diagram, when a partner sends a message where an acknowledgement is expected (1), the HL7 Connector (EDI-to-XML) configured for that partner will automatically generate an acknowledgement (2) as an XML file containing the transactional information relevant for that file. This XML acknowledgement must be routed back to an HL7 Connector in XML-to-EDI mode (3) so that all of the EDI party agreement settings will be used when generating the HL7 file that will be sent back to your trading partner.