iWay Adapter for File

In this section:

Reference:

Many technology adapters rely heavily upon polling to originate events. The iWay Adapter for File can monitor a well-known directory for the presence of a file. After it is found, the file is parsed according to metadata from the repository. Events can then be created from this parsed data.

The iWay Adapter for File is designed for the local file system. The adapter polls the local file system in user-defined directories for new files. The contents of the file can be either XML data or non-XML data structures. The adapter can monitor a given directory for the presence of a specific file or series of files.

iWay provides a direct file support to and from the iWay system. Transactionality is maintained at all times. The engine can accept files arriving in any named directory and route these messages to either another directory or to a non-file destination. Similarly, messages received through any of the other engine listeners can be directed to a directory or file. During the flow, the standard document analysis, validation, transformation, and business logic capabilities offered by the iWay server can be applied to the document.

The iWay Adapter for File accepts and processes files arriving on any local file system. As messages arrive, they are accepted by Service Manager and processed. An optional pending facility ensures that messages are retried if appropriate resources are not available at the time of execution.

Service Manager also has the capability to emit a message (either XML or non-XML, for example, HIPAA, SWIFT, HL7) to any file, regardless of the inbound protocol of the message. The adapter deletes the file after it is processed, ensuring that each request is executed only once.

The iWay Adapter for File is extremely useful for systems that can communicate only through batch files. This enables complete integration with old legacy systems.


Top of page

x
iWay Adapter for File Listener Properties

The following table lists and describes the File listener properties. For instructions on creating a listener, see, Configuring Listeners.

Property

Description

Input Path (required)

The directory in which input messages are received. A specific file name or DOS-style pattern can be used. Do not use file suffix.

Destination (required)

The directory to which output files are received. Specific file name is optional. Use an asterisk (*) in file name to be replaced by time stamp; # by sequential counter.

Removal Destination

Once a file has been processed by the server, it is removed from the input location. The removal destination is configured as a directory to which the handled file is to be moved. If this is not configured, the file is deleted.

Suffix In

This limits input files to those with this extension, for example, xml. Do not insert a period (.) before the suffix. A dash (-) indicates no extension, that is, the field is not used.

Scan subdirectories

If set to true, all subdirectories are scanned for files to process.

Do not unzip ZIP files

This property dictates whether ZIP files are passed as a single file for processing. Requires that Accepts non-XML (flat) only be turned on.

Suffix Out

The extension for output files (name is the same as input file unless specified in destination property).

Sort Order

If set to true, sort incoming documents by Name or Arrival Time. Maintains sequence, but slows performance.

Pending Queue

The queue to hold documents pending retry.

Duration

The maximum time that a document can remain in the retry pending queue.

Retry

The interval between retrying pending requests.

Maximum File Size

Only files smaller than this value will be processed by the listener. If left blank or set to zero, there will be no limit. The value can be entered with KB or MB, such as 23MB for 23 megabytes, or enter with no suffix to specify size in bytes.

Large File Directory

Full path file pattern asserting where files exceeding the maximum file size will be moved. Use an asterisk (*) in the file name to be replaced by timestamp, # by sequential counter.

Batch Mode

If set to true, do not poll until all files from the previous poll have finished processing.

Accept Zero Length Files?

If set to true, the listener will accept empty files. The listener must be configured for flat documents if this option is selected.

Inbound Header Namespace

The special register namespace to which metadata values for the input file will be saved.

Maximum Inputs

The maximum number of files that can be accepted for processing in a single poll. Note that if the number of files in the input directory exceeds this, sorting options may not work as expected. Enter 0 or leave blank for no limit.

Whitespace Normalization

Specifies how the parser treats whitespace in element objects. Select preserve (default) to turn off all normalization as prescribed by the XML Specification. Select condense to remove extra whitespaces in pretty printed documents and for compatibility with earlier versions.

Accepts non-XML (flat) only

If set to true, the input data is sent directly to the business logic step. The data is not preparsed, parsed, or validated. This flag is used primarily to send non-XML to the business logic or replyTo without processing it.

Optimize Favoring

Use this option to customize how the listener performs. For smaller transactions, select performance. For large input documents that could monopolize the amount of memory used by iWay Service Manager, select memory.

Multithreading

This property indicates the number of worker threads (documents or requests) that iWay Service Manager can handle in parallel. Setting this to a value of greater than 1 enables the listener to handle a second request while an earlier request is still being processed. The total throughput of a system can be affected by the number of threads operating. Increasing the number of parallel operations may not necessarily improve throughput.

Default: 1

Max Value: 99

Maximum threads

Parallel threads can grow to this count automatically on demand. Over time, the worker count will decrease back to the multithreading level. Use this parameter to respond to bursts of activity.

Execution Time Limit

The maximum time that a request may take to complete. Used to prevent runaway requests. Any request that takes longer to complete than this value will be attempted to be terminated. (See the kill interval for related information in Global Options.)

Polling Interval

The maximum time (in seconds) between checks for the presence of files to be processed or for commands. The higher this value, the longer the interval, and the fewer system resources that are used. The side effect of a high value is that the worker thread will not be able to respond to a stop command or accept a file awaiting processing. If timeout is set to 0, the listener will run once and terminate.

Default: 2.0 seconds.

Default Java File Encoding

The default encoding if an incoming message is not self-declaring (that is, XML).

Agent Precedence

Sets the order by which iWay Service Manager selects agents. iWay Service Manager selects the agent or agents to process the document by searching through the configuration dictionary. Usually, it looks for a document entry in the configuration and when a match is found, the agent specified in that document entry is selected. If a matching document entry is not found, or no agent is specified, the engine looks in the input protocol configuration (listener). To have the processing agent taken directly from the listener (thus ignoring the document entry), use <listener> overrides <document>.

Possible values are <document> overrides <listener> and <listener> overrides <document>.

The default value is: <document> overrides <listener>

Always reply to listener default

If set to true, the default reply definition is used in addition to defined reply-to and error-to destinations.

Error Documents treated normally

If set to true, error documents are processed by any configured preemitters.

Listener is Transaction Manager

If set to true, agents run in a local transaction. Agents can roll back uncompleted transactions.

Record in Activity Log(s)

If set to true, activity on this channel will be recorded in the activity logs, or else the activity will not be recorded.

Note: The File listener supports streaming. Streaming is used for large documents or documents for which the application needs to split the input into sections under the same transaction. For more information on streaming and configuring streaming preparsers, see the iWay Service Manager Component and Functional Language Reference Guide.



x
Reference: iWay Adapter for File Listener Special Registers

The following table lists and describes the special registers (SREGs) available on the iWay Adapter for File listener.

Name

Level

Type

Description

basename

Document

String

The file name without an extension.

extension

Document

String

The extension to the file name (mime type).

filename

Document

String

The file basename.extension.

iwayconfig

System

String

The current active configuration name.

iwayhome

System

String

The base at which the server is loaded.

iwayworkdir

System

String

The path to base of the current configuration.

msgsize

Document

Integer

The physical length of the message payload.

name

System

String

The assigned name of the master (listener).

parent

Document

String

The path to the file name.

protocol

System

String

The protocol on which the message was received.

source

Document

String

The full name of the input file.

tid

Document

String

Unique transaction ID.



x
Configuring a File Emitter

Messages are sent to particular destinations at the completion of a workflow. The state of the document determines which destination is used. The order in which the destinations are used cannot be predicted.

This configuration designates where to send response documents when the adapter receives an incoming record that was triggered by a listener.



x
File Emitter Properties

The following table lists and describes the File emitter properties. For instructions on creating an emitter, see Configuring Emitters.

Property

Description

Destination (required)

Type a destination path. For example, c:\tempout\*.xml. This value indicates where the Reply-to document resides. This entry yields document names that include a date and time stamp, such as 2006-11-10T18_57_59_823Z.xml, saved to the c:\tempout directory.

Other destination formats include:

Directory. MyDirectory (relative to the iWay home), or c:\MyDirectory (fully qualified).

Directory and file name. MyDirectory\MyFile.xml

Directory and file name with a time stamp. MyDirectory\MyFile*.xml. The asterisk is replaced by a time stamp when the file is written, accurate to a millisecond. This feature can be used to prevent overwriting of previous files since a unique name is guaranteed.

Create Directory

If set to true, the emitter creates the destination directory if it does not already exist. If set to false, then the emitter does not create the destination directory or the ref file emit Agent (this is the default).


iWay Software