File interfaces accept files which are CDA documents, or files with defined formats which are converted to standard HL7 messages. In addition, HL7Connect is able to write outgoing messages or documents to files which can be later sent to other systems.

File settings vary considerably between incoming, and outgoing interfaces, and for this reason, the settings for each are documented in separate sections, despite there being considerable overlap between the configuration options.

File Formats

Valid file formats for both incoming and outgoing interfaces are:

When used with CDA documents, the only format this is supported is One CDA document per file.

Incoming File Configuration

The incoming interface checks each specified location for incoming files. The files will be converted to one or more messages which are then delivered to the HL7Connect kernel, which processes the messages, and then forwards them to the database and any selected outgoing interfaces.

HL7Connect will reply with a response to each message. Depending on the circumstances, and how HL7Connect is configured, this reply may be a simple acknowledgement which can be discarded, or a reply that needs to be returned to the application which generated the file.

When the responses are captured to a file, one file is produced for each file received. If the response file is empty, it will not be saved. If the incoming file is a batch, then the batch format is preserved.

Settings

Field    Description    Notes
Source    File location can be either on a local drive or a FTP server.      
[File] File For Messages    "Path" and "Filename" for incoming files.    WildCards (*) can be used in the file name portion.

It is recommended that files be located on the same computer as the HL7Connect database, as Windows security issues may prevent HL7Connect using UNC paths.

[File] File For Responses    The filename for any stored responses.    See Tokens (below) for use in filenames.
If the path does not exist, it will be created.
Server    IP address or DNS-resolvable name of the FTP server.      
Port    TCP Port on which to contact the server    Leave blank to use the default FTP port which is 21
Username    Valid "Username" for the FTP server.      
Password    Valid "Password" for the FTP account.      
[FTP] File For messages    FTP path and filename for incoming messages.    Use forward slash ("/").
WildCards (*) can be used in the file name portion.
[FTP] File for responses    The name of the file for any stored responses.    See Tokens (below) which can be used in this filename.
The path must exist.
Poll Interval    The frequency with which the incoming interface scans for incoming files.      
File Format    The format of the file.    File formats are described in File Specifications. (v2 Messaging only)
Script    If the format is ASCII text, then a script will be required.    See Script Settings for further information.
Internal Buffer Size    If the format is ASCII text, the internal buffer size used when loading the file.    The default buffer size is 4096 bytes. This value must be longer than the longest single line expected. Larger values lead to reduced performance for large files with many short lines.
Delay Period    Prevents the default processing delay between each message received which restricts CPU usage.      
Working Directory    A directory where transitory files are placed by the interface during processing. Each file interface must have a different working directory.    This directory will be created by HL7Connect if it does not exist.
Responses    Controls which HL7Connect response messages will be written to the response file. (v2 Messaging only)      
Archive Directory    The directory in which incoming files that have been received and processed are archived.    If the archive directory is not provided, then the files will be deleted.

Outgoing File Configuration

Outgoing interfaces write messages to files in the valid formats mentioned above.

HL7Connect does not accept replies to messages already written to files. Once they are in the file, and an implicit internal ACK message generated, the message is considered successfully sent.

Settings

Field    Description    Notes
Destination    The destination can be either an FTP server, or a local file.      
[File] FileName    Path and Filename for incoming files. Tokens can be used in the filename portion (see Tokens below for details).    Files should be located on the same computer as the HL7Connect database, as Windows security issues may prevent HL7Connect from using UNC paths.
NOTE: If the path does not exist, it will be created.
[FTP] FileName    FTP path and filename for incoming filenames.    Use forward slash ("/"). Tokens can be used in the file name portion, see below for details.
NOTE: The path must exist.
Server    IP address or DNS-resolvable name of the FTP server.      
Port    TCP Port on which to contact the server    Leave blank to use the default FTP port which is 21
Username    Valid "Username" on the FTP server.      
Password    Valid "Password" for the FTP account.      
File Format    The format of the file. File formats are described in File Specifications.      
Script    If the format is ASCII text, then a script is required. See Script Settings for further information.      
Determine Filename    This section controls the way in which files are created.    When the filename is determined, tokens in the filename are evaluated.
Everytime (Appending)    Each time a message is written, the filename will be determined, and the message will immediately appended to the file.    Note: Appending messages to files is potentially dangerous if other processes also work with the files.
When file is full    Once the file reaches the defined size, either by messages or physical file size, the filename will be determined, and the file will overwrite any file at the name destination      

File and Path names for details on naming outbound files.

The filenames of response files, and outgoing files can contain tokens that will be replaced by other text when the filename is used. For instance, the following filename in the HL7Connect configuration:

 c:\temp\$D(yymmdd)\$I(9).$H(MSH-9.1)

when used with an ORM message on 10-Oct 2001 will produce a file with the name:

 c:\temp\011001\000000001.orm

Each time the filename is determined, the numerical portion will increment (i.e. 00000002,00000003 and so forth), with a different directory being used each day.

If the token value contains a ")" character (i.e. XPath) then the token may be marked with a quote character (' or ") around it. Tokens contained by a quote character cannot themselves contain the same quote character.

File names can include wildcards in them ("*" / "*.*"), with the usual meaning. For incoming files, match any file with a matching name, and for outgoing files, use the name of the original incoming file.

Tokens

Tokens which are able to be used for generating filenames:

Token    Description    Examples and Notes
$I(#)    When this variable is included in a file or path name, each message will generate a unique number, where # is the number of digits   

Examples: C:\Pathology\ADT$I(4).hl7

Generates a file in the c:\pathology\ADT directory called ADT0001.hl7, with a new file being created for each message.

C:\PIMS\ADT\hl7.$I(3)

Generates a file in the c:\PIMS\ADT directory called hl7.001, with a new sequential file being created for each message.

NOTE: The unique number will start at one. The number will return to zero when the number exceeds the value which can be represented in the digits specified.
For example, $I(3) and $I(2) give maximal of 999 and 99 respectively, before returning to zero.

$D([yyyy] [mm] [dd] [hh] [nn] [ss])    Inserts the current date in the format, shown in brackets to the left.   

NOTE: The default format for the date is mmddhhnnss.

yyyy = year

mm = month

dd = date

hh = hours

nn = minutes

ss = seconds

More information on tokens that can be used is found at Date/Time Tokens

Example: C:\ADT\$D(yyyymmdd)\HL7.$I(3)

The example above creates a new directory using the current date, then places files called HL7.??? (where ??? is a number) in the directory. A new directory is created each day, with a new file being created for each message.

$N(#)    The computer name, defined in networking properties in the control panel, where # is the number of characters used when naming files.    NOTE:The default, if not specified, is zero which uses an infinite number of integers.

Example: C:\Pharmacy\$N(8)\ADT.HL7

Using this format, several messages may be included in the same file, as the naming method creates a directory with the servers' PC name, then places files called ADT.HL7 in the directory.

$H(segment-field.component.subcomponent)
NOTE: This can only be used for outgoing interfaces (not in response file names).
   Uses information from the HL7 message in the file. The segment and field parameter are required. (v2 messages only)   

Example: E:\Path\Results\$H(OBR-2.1).hl7

Generates a file with the contents of the placer order number as the file name. The placer order number is the OBR segment (second field, first component of that field). All messages with the same value (OBR-2.1) will be placed in the same file.

$F(#)    # characters from the name of the file being responded to. #=0 is the default, and means the full name, including the file extension.   

Example: E:\Path\Results\$I(0).ack

Assuming that the file to which the responses were made is E:\Path\Results\path033.orm, then the file name will be E:\Path\Results\path033.orm.ack.

$T(#)    Same as $F(#), but without the file extension.      
$X('c')    An XPath expression (CDA documents only).    Example: C:\Pharmacy\$X('*/v3:id/@root')-$X('*/v3:id/@extension').xml

This creates a file with the document identifier root and extension in the name, separated by a dash.

If the contents of the () portion of the token include a ^ character, the portion of the token following the ^ will be interpreted as a substring specifier, and must either be a single number, or two numbers separated by a ':' (no whitespace allowed). For example, $H(OBR-2^1:4) means the first four characters of the OBR-2 field (4 characters starting at the first one), and $H(OBR-2^5) means all the characters of the OBR-2 field after (and including) the fifth character. Using a substring specifier like this works with all tokens, though it generally only makes sense with $H and $X.


© Kestral Computing P/L 2000-2015. HL7Connect v2.00-063 generated on 30-Nov 2015
Keywords: File Interfaces, Batch, FTP, Filename, File Format, Batch Files, Events, File Interfaces / Configuring, LLP, Text Files