Common configuration
tasks
This section describes the most common configuration tasks.
Specifying
event notification
This section describes the following:
Specifying event directories and extensions
If you send more than one type of business object to the
connector for processing, and each business object type has its
own top-level meta-object, the combination of values you specify
for the EventDir and EventExt attributes must be unique for each directory/extension pair
for each business object.
In other words, if you specify the same event directory for two
business object types, you must specify different event extensions
for these business objects. If you specify the same extension for
two business object types, you must specify different event directories
for these business objects.
For example, assume you have created the MO_JTextConnector_Customer and MO_JTextConnector_Item meta-objects to provide configuration values for the Customer
and Item business objects, respectively. If you instruct the connector
to locate the input files for both business objects in the same
directory (by specifying the same path in the EventDir attribute), you must uniquely identify the input files by
specifying different values for the EventExt attribute.
Therefore, if the EventDir attribute evaluates to C:\temp\event for both Customers and Items, the value of the EventExt attributes for these two business objects must be different
(such as in for Customer input files and inp for Items).
Note:
A new Connector-specific boolean property, "NoPoll",
has been introduced, to optionally turn off polling. The default
value is false. When set to true, the adapter only processes requests
and does not poll.
Configuring
polling behavior
To configure polling behavior, perform the following steps:
- Configure the following attributes of the MO_JTextConnector_Default meta-object:
- EventDir--Specify the absolute path of an existing directory
whose files trigger event notification.
- EventExt--The connector looks for files with the delivered-default
extension of in. If you use this attribute to specify a different
extension, the connector looks for the specified extension. If you
leave this attribute empty, the connector polls for files with no
extension.
- EventDataHandler--Specify the data handler to use for data conversion
during event notification.
- Use Connector Configurator Express
to configure the following connector properties:
- PollFrequency--Specify the interval frequency.
- PollQuantity--Specify the number of events for each polling interval.
- PollEndTime--Specify the time to complete the polling of events.
- PollStartTime--Specify the time to begin the polling of events.
- Establish read permissions on the event directory.
Specifying
event archiving
Depending on whether all or some of the business objects
in the event file process successfully, the JText connector uses
different extensions when it creates the archive file for successfully
processed business objects. The connector also writes business objects
that fail processing and those that are unsubscribed to differently named
archive files.
This section describes the following:
Local
archive filenames
If you retain the delivered default values for the archive
extension attributes, the connector creates archive files named
as shown below:
- Event file has a single business object
After the JText connector processes an event file that contains
a single business object, it creates one of following files in the
archive directory:
- filename_timestamp.success, to archive a successfully processed business object
- filename_timestamp.fail, to archive a business object that was not successfully processed
- filename_timestamp.unsub, to archive a business object to which it does not subscribe
If the business object fails processing or is unsubscribed, the
connector also creates the filename_timestamp.orig file, which preserves the event file as the connector originally
received it.
- Event file has multiple business objects, all of which process
successfully
After the JText connector successfully processes an event file
with multiple business objects, it creates filename_timestamp.success in the archive directory.
- Event file has multiple business objects, some of which are
unsubscribed or fail processing
After the JText connector processes an event file that contains
multiple business objects, it may create all of the following files
in the archive directory:
- filename_timestamp.partial, to archive all business objects whose processing was successful
- filename_timestamp.fail, to archive all business objects whose processing was unsuccessful
- filename_timestamp.unsub, to archive all business objects to which the connector does
not subscribe
- filename_timestamp.orig, to preserve the event file as the connector originally received
it
For example, assume that the LegacyApp.in file contains four business objects:
- Contract, which is successfully processed
- Customer, which fails formatting
- Order, which is successfully processed
- Item, to which the connector does not subscribe
In such a case, the connector creates the following files in
the archive directory:
- LegacyApp_timestamp.partial, which contains Contract and Order
- LegacyApp_timestamp.fail, which contains Customer
- LegacyApp_timestamp.unsub, which contains Item
- LegacyApp_timestamp.orig, which contains Contract, Customer, Order, and Item
Configuring
local archiving
To configure the connector for archiving, follow these
steps:
- Configure the following attributes of the MO_JTextConnector_Default meta-object:
- ArchiveDir--Specify the absolute path of an existing local or
FTP server directory into which the connector is to place events
(with file extensions that indicate processing status) after they
are processed.
- SuccessArchiveExt--Specify the extension for the file that contains
the successfully processed business objects (when all business objects
process successfully).
- PartialArchiveExt--Specify the extension for the file that contains
all the successfully processed business objects (when some of the
business objects in the event file do not process successfully).
- UnsubscribedArchiveExt--Specify the extension for the file that contains
the business objects to which the connector does not subscribe.
- OriginalArchiveExt--Specify the extension for the file that preserves
all the business objects that were contained in the event file.
- FailArchiveExt--Specify the extension for the file that contains
the business objects that failed processing.
- Use Connector Configurator Express
to configure the ArchivingEnabled connector property.
- Establish write permissions on the archive directory.
Specifying
request processing
You can cause the JText connector to write business objects
to files whose names are specified dynamically (in each business
object instance) or statically (through meta-objects). You can also
cause the connector to return each filename that it generates statically;
this feature is useful to obtain filenames generated with a unique sequence
number. This section contains the following subsections:
Dynamic file
naming
To cause the connector to dynamically generate an output
filename for each type of business object, create a dynamic child
meta-object. Use the child meta-object:
- either to specify the name of the output file or to receive
the name of the generated filename
- to specify whether to append to or overwrite the output file
Important:
In addition to creating the dynamic child meta-object
to enable the connector to generate or return the output filename,
if you are using InterChange Server Express as the integration broker,
you must also modify your maps or collaboration logic to insert
into the dynamic child meta-object's InFileName attribute a path and filename for each business object, and,
if required, unique sequence numbers.
For more information, see Using a dynamic child meta-object.
For information about how the connector processes the meta-object,
see Request processing.
For information on configuring the connector to use a dynamically
generated output filename, see Configuring
the output file.
Static file
naming
When you use meta-objects to specify the name of output
files, you must restart the connector for any changes to take effect.
You can specify whether the connector appends all business objects
of a given type to a single file or creates a separate file for
each business object.
When it uses the delivered default configuration, the connector
creates an output file for each business object it processes. It
names the output file for the incoming business object and adds
a sequence number to make the name unique; it gives it the extension
of .out. For example, if it receives the Customer and Item business objects,
the connector writes their data to the Customer_1.out and Item_1.out output files. For information on obtaining the names of generated
output files, see Returning a file's name. For information
on the file that stores the sequence numbers, see OutputLog.
To use the meta-object to configure the name of output files,
do the following:
- Configure the following attributes of the MO_JTextConnector_Default meta-object:
- OutputDir--Specify the absolute path of an existing directory
to which the connector is to write files when it processes requests.
For more information, see Configuring
the output file.
- OutputExt--Use this attribute to specify your own extension
if you want to change the delivered default configuration, which
causes the connector to create files with the out extension.
- FileSeqEnabled--Keep set to true to cause the connector to output one business object per
file, each with a unique sequence number. Set to false to cause the connector to output all business objects of
a given type to a single file, either by overwriting or appending.
For information on configuring overwrite or append behavior, see Table 9.
- OutputFileName--To the cause the connector to append business objects
to a single output file rather than overwrite the data in the file
or generate unique files for each business object, specify the output file's
full path and filename.
To cause the connector to overwrite the output file each time
it receives the same type of business object, do not specify a value
for OutputFileName.
In each of these cases, set FileSeqEnabled to false.
For information on configuring overwrite or append behavior,
see Table 9.
- Establish write permissions on the output directory.
Note:
You must create meta-objects for specific business
objects if the connector is to use different data formats or file
naming conventions for different business objects.
Returning a file's name
To cause the connector to return the names of the files
it generates, do the following:
- Use meta-objects to specify path and filenames and to cause
the connector to generate a unique sequence number for each output
file. For more information, see Static file
naming.
- Use a dynamic child meta-object to cause the connector to return
the name of each file it generates. Follow the steps in Using a dynamic child meta-object, but do not specify a value for its InFileName attribute. When the connector receives a business object
whose dynamic child meta-object specifies OutFileName=CxIgnore, it creates a filename based on the configuration
of its top-level meta-object, and returns the full path and filename
as a value in the InFileName attribute.
Note:
The connector populates the InFileName attribute only with a local path, even when processing files over
an FTP server.
Important:
In addition to creating the dynamic child meta-object
to enable the connector to generate or return the output filename,
if you are using InterChange Server Express as the integration broker,
you must also modify your maps or collaboration logic to insert
into the dynamic child meta-object's InFileName attribute a path and filename for each business object, and,
if required, unique sequence numbers.
Differences between local and remote processing
The connector processes files remotely in much the same
way that it processes them locally. There are, however, a few differences:
- When processing events and generating filenames dynamically,
the connector populates the InFileName attribute of the dynamic child meta-object only with a local
path name and not with a remote path.
- When processing requests, if the connector is not configured
for dynamic file naming and FileSeqEnabled evaluates to false and the output file already exists:
- If processing locally, the connector overwrites the existing
file.
- If processing remotely, the connector throws an exception.
- In addition to configuring the standard archive extension attributes
for local event processing, when using the connector to process
files remotely over an FTP server, you can also configure the FTPArchiveDir and FTPRenameExt attributes. These attributes enable you to rename and move
the remotely archived file independently of the success of the processing.
For further information see Specifying
remote archiving
Configuring
the output file
Table 9 illustrates the
possible configuration options for the output file:
Table 9. Specifying output files
Desired output condition |
Attributes/property requiring configuration |
Attribute/property value |
Each business object
of a given type is appended to a file whose absolute path and filename
is derived at runtime from an attribute in the business object. |
Use a dynamic child meta-object |
|
AppSpecificInfo (at business-object level) |
cw_mo_JTextConfig = DynChildMOName |
For dynamic child meta-object: OutFileName |
user-specified pathname and filename |
FileWriteMode |
a or append |
Each business object of a given
type overwrites the output file whose absolute path and filename
is derived at runtime from an attribute in the business object. |
Use a dynamic child meta-object |
|
AppSpecificInfo (at business-object level) |
cw_mo_JTextConfig = DynChildMOName |
For dynamic child meta-object:OutFileName |
user-specified pathname and filename |
FileWriteMode |
o or overwrite |
Each business object of a given type is written
to its own unique file whose name is derived from the business object's
name and a generated unique sequence number. |
OutputDir |
user-specified pathname |
|
FileSeqEnabled |
true |
|
OutputFileName |
Native |
The connector returns the name
of each file it generates. Each business object of a given type
is written to its own unique file whose name is derived from the
business object's name and a generated unique sequence
number. |
Use a dynamic child meta-object
|
|
AppSpecificInfo (at business-object level) |
cw_mo_JTextConfig = DynChildMOName |
InFileName (in dynamic child
meta-object) |
CxIgnore |
FileWriteMode (in dynamic child
meta-object) |
N/A |
Use meta-object configuration: MO_JTextConnector_businessobjectname: |
|
OutputDir |
user-specified pathname |
FileSeqEnabled |
true |
OutputFileName |
Native |
All business objects of a given type are
appended to a single file whose name is user-specified. |
FileSeqEnabled |
false |
|
OutputFileName |
user-specified pathname and filename |
Each business object of a given type is written
to its own unique file whose name is user-specified plus a unique sequence
number. |
FileSeqEnabled |
true |
If the connector is processing more than
one type of business object and OutputFileName is set to a string other than Native, each business must have its own top-level meta-object. For more
information, see Specifying the name of the output file. |
OutputFileName |
user-specified pathname and filename |
Each business object of a given type overwrites
the output file, whose name is derived from the business object's
name. |
OutputDir |
user-specified pathname |
|
FileSeqEnabled |
false |
|
OutputFileName |
Native |
The connector returns the name
of each file it generates. Each business object of a given type
is written to its own unique file whose name is user-specified plus
a unique sequence number. |
Use a dynamic child meta-object
|
|
AppSpecificInfo (at business-object level) |
cw_mo_JTextConfig = DynChildMOName |
InFileName (in dynamic child meta-object) |
CxIgnore |
FileWriteMode (in dynamic child
meta-object) |
N/A |
Use meta-object configuration: MO_JTextConnector_BOName. |
|
FileSeqEnabled |
true |
OutputFileName |
user-specified pathname and filename |
Specifying
multiple event files or multiple
event directories
You can configure the connector to pick up only files
with a specified extension. You can also configure the connector
to pick up files from multiple directories.
Important:
The use of an asterisk (*) for the EventExt attribute to specify that the connector poll for all files in
a single event directory regardless of their extension is no longer
supported.
To specify a separate event directory for each business object
type, perform the following steps:
- Create a separate meta-object for each supported business object;
for example, create MO_JTextConnector_Customer and MO_JTextConnector_Item. For more information, see Creating a JText
meta-object for a specific business object.
- Specify the appropriate directory in each meta-object's EventDir attribute.
Note:
The JText connector processes event files in the
order of their time stamps, from the earliest to the most recent,
regardless of their location. In other words, the JText connector
processes files located in separate directories in the chronological
order of their time stamps.
Polling for specific business objects
Configuration of the JText connector differs depending
on whether all your event files are in a single directory, they
all have the same extension, they contain a single business object
or multiple business objects, they contain business objects of one
type or multiple types, and they represent each business object
on a single line or on multiple lines.
This section explains the following:
Using
EndBODelimiter parsing method
If no value is specified for the EndBODelimiter meta-object attribute, the connector:
- expects the event file to delimit business object strings with <EndBO:BOName>
- specifies <EndBO:BOName> as the delimiter when it writes business object strings to
output files.
If an event file contains only one business object, you can specify EOF (end of file) for this attribute.
If you set the value of the EndBODelimiter attribute to a non-empty string, the string is assumed to
be the business object delimiter for every file. If the value is
not set or is cleared, the connector assumes the delimiter is <EndBO:BOName>.
Important:
If DataProcessingMode is set to binary and if there is no value specified for EndBODelimiter, JText will set the default EndBODelimiter to FF01 (2 bytes) and EndOfFileDelimiter to FF02 (2 bytes).
Table 10 illustrates delimiter options.
Table 10. Using the EndBODelimiter attribute
Conditions |
Delimiter |
Notes |
File contains one or more business
object strings with one or more types of business object or File
contains multiple business object strings of the same type of business
object; each string runs over several lines. |
<EndBO:BOName>or EOL or user-specified
value |
- Specify as many semicolon-separated EOLs as there are new lines between business object strings.
- Specify a custom delimiter in conjunction with EOLs. A custom delimiter must always be the first element when
used with EOL. The following example is valid: customEndBO;EOL;EOL. The following example is not valid: EOL;customEndBO;EOL.
|
Each file contains only one business object string |
EOL
For user-specified value |
- Specify as many semicolon-separated EOLs as there are new lines between business object strings.
- Specify a user-specified delimiter in conjunction with EOLs and EOF if required by the input strings. A custom delimiter must
always be the first element when used with EOL. The following example is valid: customEndBO;EOL;EOL. The following example is not valid: EOL;customEndBO;EOL
|
File contains multiple business object strings, one
per line |
EOL |
|
File contains multiple business object strings
of the same type of business object; each string runs over several
lines without any separators between business-object strings |
None |
Can use the delivered default meta-object or
a custom meta-object
Note:
This option is available only during service call
requests and not for event notification. Do not use this delimiter
in conjunction with any other delimiter. |
Note:
If the source file contains empty lines, the connector
ignores them.
Using non-printable characters for
an EndBODelimiter
To poll for files in multiple directories, you must create
a meta-object for each supported business object. The value you
specify for each meta-object's EndBODelimiter attribute depends on whether your source file contains a
single business object or multiple business objects.
- Files that contain a single business object
You can specify EOF as the EndBODelimiter if the entire data file contains only one business object
string.
- Files that contain multiple business objects
If your input file contains multiple business objects that have
only a new line as the business object delimiter, specify the string EOL in the EndBODelimiter attribute. In this case, the source file contains strings
representing multiple business objects of the same type.
Important:
To poll from a file that contains multiple business object
types, you must use the MO_JTextConnector_Default meta-object, and must ensure that its EventExt and EventDir attributes correctly point to the directory where this event
file is located. To poll for business object types that are represented
in separate event files or whose event files are located in different
directories, you must create a separate top-level meta-object for
each type. Use the EventExt and EventDir attributes to point to the appropriate directory.
To use a custom data handler when polling files that contain
multiple business objects of different types, see Reading multiple business objects of different types from
the same file.
If using a name/value format, you cannot specify the EOL business object delimiter if the event file splits business
object data over multiple lines. For more information, see the Data Handler Guide.
The following examples illustrate the delimiter to use for different
event file formats:
- File contains four business object strings and uses the non-printable
character EOL as the end of business object delimiter:
Sample_BO~Create~1~TableGenKey5~strange~TextConnector_924055528_0
Sample_BO~Create~2~TableGenKey5~strange~TextConnector_924055528_0
Sample_BO~Create~3~TableGenKey5~strange~TextConnector_924055528_0
Sample_BO~Create~4~TableGenKey5~strange~TextConnector_924055528_0
Note:
The connector is case-sensitive to the string that
you specify, except for the EOL and EOF delimiters.
For more information on creating your own meta-objects, see Creating a JText
meta-object for a specific business object.
Using
FixedBOSize parsing method
This meta-object property is only valid in the following
instances:
- When performing event processing.
- When DataProcessingMode is set to Binary.
When present with a valid value, this meta-object property overrides
the EndBODelimiter property, and provides users an alternative to the traditional
delimiter based business object parsing. This property enables the
connector to correlate a fixed number of bytes with a single business
object. For example, if a file consisted of 300 bytes, and the FixedBOSize property was set to 100, the JText Adapter would convert
these three 100 byte length packets through a binary enabled data
handler and send them to the InterChange Server Express.
If both FixedBOSize and EndBODelimiter have a value set, then Jtext will take FixedBOSize for file parsing and it will ignore EndBODelimiter.
Specifying
a remote FTP file system
This section describes how to configure the JText adapter
to use a remote FTP file system for event and request processing.
Important:
To enable the connector to use a remote FTP file system,
you must specify an FTP URL in the
EventDir attribute
(for event processing) or
OutputDir attribute
(for request processing). You must also resolve all firewall issues
before using the connector to perform FTP operations.
This section describes the following:
Remote
event processing
To configure the connector to use a remote FTP file system
for event processing, you must specify the FTP URL, FTP login information,
a local directory into which the connector downloads the event files
from the remote directory, archiving information, and information
related to how the connector behaves when the FTP server is unavailable.
This section describes all of these configurations as well as additional
optional configurations.
Specifying
the FTP URL and login information
The connector polls for events from the directory specified
in the EventDir meta-object
attribute. To configure the connector to use a remote FTP file system
for event processing, specify the FTP URL as the value of this attribute.
The FTP URL must conform to IETF standards.
In addition to specifying the FTP server in the URL, you can
optionally specify the following information in the EventDir meta-object attribute:
- Name of a user with privileges to connect to the FTP server
and perform FTP operations--If you do not specify the username
in EventDir, specify it in the FTPUserId meta-object
attribute.
- Password of a user with privileges to connect to the FTP server
and perform FTP operations--If you do not specify the password
in EventDir, specify it in the FTPPassword meta-object
attribute.
- Port number--If the port is not specified in EventDir, the connector uses the default port.
- Remote event directory--If you do not specify the remote
event directory in EventDir, the connector polls the event files from the directory to
which the connection is established to the FTP server.
Important:
You can specify the FTP values either in a static top-level
meta-object or in a dynamic child meta-object. If the username and
password are not specified in any meta-object attribute, the connector
terminates when attempting to connect to the FTP server. For more
information, see
Using a dynamic child meta-object.
The examples below illustrate three different formats for EventDir attribute values:
URL only with required values:
ftp://ftp.companyA.com
URL with optional username and port number values:
ftp://companyA:admin@ftp.companyA.com:1433
URL with optional username, port number, and remote event directory values:
ftp://companyA:admin@ftp.companyA.com:1433/temp/JTextConn/Default/Event
URL for Linux / MVS related FTP setup
ftp://ftpuser:ftppwd@ftpserver.in.ibm.com:21/home/ftpuser/JText/event
Specifying
the local directory
In addition to specifying the FTP URL and related login
information, you must specify the location of the local directory
into which the connector downloads the event files from the remote
directory. To specify the local directory, use the FTPLocalEventDir meta-object attribute.
Important:
If the connector finds a proper FTP URL in EventDir, but does not find the FTPLocalEventDir meta-object attribute or finds an invalid or a blank value
for this attribute, the connector does not start. The connector
does not evaluate the FTPLocalEventDir attribute when configured to run locally.
Specifying
remote archiving
You have several options in specifying how the connector
handles remote archiving. To specify a remote archive directory,
use the FTPArchiveDir meta-object attribute.
This attribute specifies the relative path of the archive directory
on the FTP server. The directory must already exist. There are several
options for using this attribute to specify archiving:
- Specifying a value for the FTPArchiveDir attribute but no value for the FTPRenameExt attribute
causes the connector to append a timestamp to the event filename
and move it to the remote FTP server archive directory specified
in the FTPArchiveDir attribute.
- Specifying a value both for the FTPArchiveDir attribute and the FTPRenameExt attribute causes the connector to rename the processed event
filename, adding a timestamp and ignoring the FTPRenameExt, then move it to the FTP server archive directory specified
in the FTPArchiveDir attribute.
- Specifying no value either for the FTPArchiveDir or the FTPRenameExt attributes causes the connector to delete the processed event
file without archiving it.
- Specifying no value for the FTPArchiveDir attribute but specifying a value for the FTPRenameExt attribute causes the connector to rename the processed event
filename with the value specified in FTPRenameExt, and move it to the directory specified in the EventDir attribute.
File naming with timestamping for remote FTP servers
Support for host file systems (MVS) using Sequential datasets
has been enhanced by providing for time stamping to avoid duplicate
file names. MVS doesn't support special characters, such
as "_", in a dataset or recordset name. On Windows, Linux, or i5/OS platforms,
we use a time stamp in the original filename while archiving the
file This avoids duplicate filenames in an archive folder, thereby
preventing the overwriting of an existing file.
We use the following format for MVS systems to overcome this
limitation:
Event File: Test.in
Archived file: Test.TSyyyyMM.TSDDHHMM.TSSsSss
Where: yyyy -- year
MM -- month
DD -- date
HH -- hour
MM -- minutes
Ss -- seconds
Sss -- milliseconds
On MVS platforms the dataset or recordset separator
is "." (dot) and maximum number of '.' (dots) allowed in a dataset
or recordset is 6 (six) The dataset or recordset name must not exceed
8 characters per "." (dot) and the total number of characters must
not exceed 44 characters. Here is an example of a file name in this
format:
FTPRenameExt -- ARCHIVE
Archived File -- (SAMPLE).ARCHIVE.TS200304.TS290535.TS42234
Note:
The members of PDS cannot be renamed with time
stamps while archiving. Hence, an alternate mechanism is provided
for PDS archival. Each member of a PDS that falls into the FTPEventFileMask is
archived under the parent PDS, with filename specified as the FTPRenameExt.
The archival file will be rewritten each time with the latest processed
file.
Specifying
remote polling
You can use the FTPPollFrequency configuration
property to set how frequently the connector polls an FTP server
measured in the number of standard poll cycles. This setting is
useful if the connector is still reading files from the local event
directory when it starts the next polling cycle.
For example, if PollFrequency is
set to 10000, and FTPPollFrequency is set to 6, the connector polls the local event directory every 10 seconds
and polls the remote directory every 60 seconds. The connector performs
FTP polling only if you specify a value for this property. If FTPPollFrequency evaluates to 0 or blank, the connector does not perform FTP polling.
For more information, see Tuning
the performance of the JText connector.
How
the connector processes events from a remote site
When polling for events from a remote site, the connector
performs the following steps:
- Obtains the server name, port number, username, password, and
remote event directory from meta-object attributes or default values.
- Establishes a connection to the remote FTP site to get event
files from the remote event directory.
- Downloads the event files from the remote directory to the local
directory specified in the FTPLocalEventDir meta-object attribute.
Note:
To enable the connector to process events using
FTP, this attribute must have a value.
- Polls the local directory.
Figure 6 illustrates local and remote
event processing.
Figure 6. Local and remote event notification operation
Identifying files on a mainframe: Optional configuration
Use the FTPEventFileMask attribute
to identify file extensions on a mainframe that do not adhere to
the same naming standards that apply to Windows, Linux,
or i5/OS systems. If no value is provided for this attribute, the connector
uses the value specified in the EventExt attribute.
When specifying a value for FTPEventFileMask, you can include wildcard characters. The following example illustrates
several possible formats for this attribute:
ACT.Z1UC.*
ACT.*.INPT
*.Z1UC.INPT
If the connector finds more than one file at the remote site
that meets the criteria specified for FTPEventFileMask, it does the following:
- Downloads all specified remote event files to the directory
specified in the FTPLocalEventDir attribute.
- Renames the extension of the remote files with the value specified
in the FTPRenameExt meta-object attribute.
Renaming the files prevents the connector from polling the same
file in the next poll cycle.
- Disconnects from the FTP server.
- Processes the files locally in the directory specified in the FTPEventFileMask meta-object attribute.
Summary of configuration operations
for event processing
To configure the connector to use a remote FTP file system
for event processing, specify the following configuration values:
- Specify the FTP URL in the EventDir meta-object
attribute. Optionally, specify the name and password of a user with
privileges to connect to the FTP server and perform FTP operations.
- If you do not specify the login name and password in the EventDir meta-object attribute, do so in the FTPUserId and FTPPassword meta-object
attributes.
- If you do not specify the port in the EventDir meta-object attribute, the connector uses the default FTP port.
- Use the FTPLocalEventDir meta-object
attribute to specify the local system directory into which the connector
downloads event files from the FTP site.
- On a mainframe that does not adhere to the same naming standards
that apply to Windows, Linux,
or i5/OS systems, use the FTPEventFileMask meta-object
attribute to identify files to be polled.
- To configure the connector to work with an MVS FTP server when
the remote system is MVS, specify MVS in the FTPOSPlatform attribute.
Remote
request processing
To configure the connector to use a remote FTP file system
for request processing, you must specify the FTP URL, FTP login
information, and a remote directory into which the connector uploads
the request files from the local directory. This section describes
all of these configurations as well as additional optional configurations.
Specifying the FTP URL and Login Information
The connector uploads service call request files into
the directory specified in the OutputDir meta-object
attribute. To configure the connector to use a remote FTP file system
for request processing, specify the FTP URL as the value of this
attribute. The FTP URL must conform to IETF standards.
In addition to the FTP URL, you can optionally specify the following
information in the OutputDir meta-object attribute:
- Name of a user with privileges to connect to the FTP server
and perform FTP operations--If you do not specify the username
in OutputDir, specify it in the FTPUserId meta-object
attribute.
- Password of a user with privileges to connect to the FTP server
and perform FTP operations--If you do not specify the password
in OutputDir, specify it in the FTPPassword meta-object
attribute.
- Port number--If the port is not specified in EventDir, the connector uses the default port.
- Remote output directory--If you do not specify the remote
output directory in OutputDir, the connector loads the request files into the default connection
directory (the directory on the FTP server to which the connection
is established).
Important:
You can specify the FTP values either in a static top-level
meta-object or in a dynamic child meta-object. If the username and
password are not specified in any meta-object attribute, the connector
terminates by throwing an exception. For more information, see
Using a dynamic child meta-object.
The examples below illustrate three different formats for OutputDir attribute values:
URL only with required values:
ftp://ftp.companyA.com
URL with optional username and port number values:
ftp://companyA:admin@ftp.companyA.com:1433
URL with optional username, port number, and remote output directory values:
ftp://companyA:admin@ftp.companyA.com:1433/temp/JTextConn/Default/Out
How the connector processes service call requests to a remote
site
When the connector is configured for FTP processing and
it receives a service call request, it performs the following steps:
- Obtains the server name, port number, username, and password
from meta-object attributes or default values.
- Establishes a connection to the remote FTP site to place service
call request files from the local directory.
- Uploads the request files from the local directory to the remote
directory.
- Disconnects from the remote server.
Figure 7 illustrates local and remote
request processing.
Figure 7. Local and remote request operations
Summary of configuration operations
for request processing
To configure the connector to use a remote FTP file system
for request processing, specify the following configuration values:
- Specify the FTP URL in the OutputDir meta-object
attribute. Optionally, specify the name and password of a user with
privileges to connect to the FTP server and perform FTP operations.
- If you do not specify the login name and password in the OutputDir meta-object attribute, do so in the FTPUserId and FTPPassword meta-object
attributes.
- If you do not specify the port in the OutputDir meta-object attribute, the connector uses the default port.
- To configure the connector to work with an MVS FTP server when
the remote system is MVS, specify MVS in the FTPOSPlatform attribute.
Notes on configuring the connector for
FTP transfer
The following features apply to FTP transfer of data:
- The connector uses Binary mode of data transfer when doing FTP
operations.
- The connector does not use FTP transfer of data if the value
of the EventDir or OutputDir meta-object attribute does not begin with ftp://.
- During event processing, if the event business object contains
a dynamic child meta-object with an InFileName attribute, the connector populates this attribute with the
full path of the file specified in the FTPLocalEventDir, but not the path on the remote system.
- Values entered in the EventExt and FTPRenameExt meta-object attributes cannot be same; if they were the same,
the connector would continuously pick up files that it had already
picked up earlier.
- The connector does not support file sizes that are not supported
by FTP.
- You must consider case sensitivity for file names, extensions,
and other components in accordance with the platform of the FTP
site.
- Transferring files from a remote FTP site might impact the connector's
performance.
- When data is exchanged to or from the remote FTP site, there
is a chance that data can be corrupted or lost due to loss of network
connection or similar problems.
- The integration broker does not maintain any type of connection
cache or pool. Connections are opened and closed for each polling
cycle and request processing. Network latency and other configuration outside
the control of the connector can impact its performance.
- The value specified for the FTPLocalEventDir meta-object attribute can not be specified as the value of
the EventDir meta-object attribute of any meta-object that does not specify
FTP values. This restriction prevents the connector from using values
specified in different types of business objects in same directory
that require totally different types of processing.
- If the remote event directory or output directory specified
at the end of the FTP URL does not exist, the connector shuts down
when it interacts with the FTP site. It does not shut down at the
time of connector startup.
- When configuring the connector for processing files over an
FTP server, you must configure the FTP server to use the Linux settings
required by the Apache Commons Net API.
Configuring
secure FTP
JText adapter uses the SSL (Secure Socket Layer) protocol
to establish a secure communication channel between the adapter
and the FTP server. For this feature, the FTP server needs to be
a secure FTP server supporting this protocol. JText adapter makes
use of the IBM JSSE package that is an implementation of the SSL
protocol. The adapter works in passive FTP mode and implicit SSL
mode.
This section describes the additional configurations required to
use the secure FTP feature of JText adapter.
To configure secure FTP:
- Install and configure a secure FTP server supporting SSL protocol.
JText adapter uses a SSL protocol to transfer data between client
application and FTP server. Therefore, a secure FTP server needs
to be installed which supports SSL protocol and configured appropriately
for SSL communication. The server should have a private key and
a certificate.
- If applicable, configure the Firewall settings. JText adapter
uses a passive FTP mode of data transfer with secure FTP server.
Therefore, if there is a firewall between the client and the server,
the firewall settings may need to be configured to enable this mode.
- Set the client trust store. During SSL communication, the server
sends its certificate to the client for verification. The client
verifies the certificate to ascertain that it is communicating with
the intended server. To enable this verification process, the server's
certificate should be present in the client's trust store. The server's
certificate can be imported into the client's trust store using
the keytool utility, for example:
keytool -import -v -alias serverCert -file server.cert
-keystore clientTrustStore
where server.cert is the certificate of the server and clientTrustStore
is the trust store of the client.
- Set the trustStore system property in the adapter startup script.
The adapter startup script should include the following system property,
-Djavax.net.ssl.trustStore=C:\MyKeyStore\clientTrustStore
where clientTrustStore is the trust store of the client as specified
in Step 3.
- Make sure that you use ftps in the FTP URL. For secure communications,
the FTP URL should have ftps as the protocol, for example: ftps://host:port/ftpdir
Specifying
a data handler
To specify a data handler to be used by the JText Connector,
perform the following steps:
- Determine the format used by the application with which the
JText connector communicates. Note that only one data handler class
can be registered for any given format type.
- Configure the following child objects of the top-level JText
meta-object:
- EventDataHandler--To specify the data handler meta-object to be used
for event processing (business object string or byte array to business
object conversion).
- OutputDataHandler--To specify the data handler meta-object to be used
for the request processing (business object to business object string
or byte array conversion).
To change the data handler from the delivered default
(either to a different delivered one or to a custom data handler),
do the following:
- Verify that the connector supports the business object specified
as the default value in the EventDataHandler and OutputDataHandler attributes.
- Verify that the class or jar file that contains the data handler
is included in the class path when the connector is started. If
you use a delivered data handler, or you add a custom data handler
to the CustDataHandler.jar file (as recommended in the Data Handler Guide),
the file is included in the delivered startup script (start_JText.bat or connector_manager_JText.sh).
- Make sure you specify an appropriate EndBODelimiter value for the data handler that you are using.
For information on creating a data handler, see the Data Handler Guide.
Creating a JText
meta-object for a specific business object
When you create a JText meta-object for a specific business
object, rename the meta-object to identify the particular business
object. For example, to create meta-objects for the Customer and
Item business objects, you might name the meta-objects MO_JTextConnector_Customer and MO_JTextConnector_Item.
Tip:
Use default meta-objects when all business objects to
be written to files have exactly the same configuration. In other
words, all text files reside in the same event directory and are
written to the same output directory, use the same data handler,
and have the same file extension (or should be put into the same
file). Create your own meta-objects if the connector must use different
processing for different business objects on requests, or if specific
processing instructions are required for polling. If you create
separate meta-objects for specific business objects, the connector
uses your meta-objects for both integration-broker requests and
subscription delivery operations.
Any business object for which you do not create a meta-object
is configured by the values in the default MO_JTextConnector_Default meta-object. For the business object definition for this default
meta-object, see the \repository\JText directory.
Reading multiple business objects of different types from
the same file
If a text file contains multiple business objects of different
types, you must use the MO_JTextConnector_Default meta-object, and must ensure that its EventExt and EventDir attributes correctly point to the directory where this event
file is located. Each business object in the file must be separated
by the same delimiter.
The delivered data handlers can determine the name of each business
object from the input string. In other words, when using the default
top-level JText meta-object and the delivered data handlers, you
need not use the <EndBO:BOName> delimiter
to identity each type of business object in a file that contains
multiple types.
If you develop a custom data handler to convert business object
strings to business objects, ensure that it can interpret the business
object's type from the input string.
Specifying values for ObjectEventID attributes
You do not have to add ObjectEventId attributes to business object strings. For event notification
business objects, the connector framework populates these business
object attributes if the IDs are not populated by the connector.
For service call request business objects, ObjectEventId attributes are either ignored or included in the string written
to a file. Whether ObjectEventId attributes are included in the output file depends on the
data handler that is used.
Setting up a second instance
of a JText connector
To set up a second instance of the JText connector, follow
these steps:
- Make a copy of the JText connector directory and its repository
directory and rename them. For example, assume you name the second
connector definition JText2. After you create the second directories, your directory
structure looks like the following:
\connectors\JText
\connectors\JText2
\repository\JText
\repository\JText2
- Copy all the meta-objects for the JText connector (there should
be at least two of them) and modify the name of the business objects.
For example, for the JText2 connector, change the names from MO_JText2ConnectorBOName to MO_JText2ConnectorBOName.
There are two ways you can copy the meta-objects:
- In Connector Configurator Express,
copy the connector's definition and rename it to JText2Connector. Change the supported meta-objects and business objects.
- Copy any new definition files into the repository. To use Business Object Designer Express to
copy business object definitions into the repository, select the
Save To Server submenu from the File menu. Alternatively, on InterChange
Server Express, perform the following steps to copy business object definitions
into the repository from the operating system:
- Copy the text from the top of the \repository\ReposVersion.txt file to the top of every definition file.
- Use the following repos_copy command to copy in the new meta-objects and business objects:
repos_copy -sServerName -iFileName
- Refresh the integration broker's administration utility
to verify the new business objects.
- For Linux, make a copy of
the existing connector manager script for the JText connector and
change the parameters to refer to JText2. For Windows, make a copy of the existing shortcut for the
JText connector and change the parameters to refer to JText2, and modify it to point to the JText2 directory rather than the JText directory.
- For i5/OS systems, add the new connector instance to the Console.
- Restart the integration broker.
- In Linux, run the connector
manager script. In Windows, click on the new shortcut. In i5/OS, use the Console to start the connector.
Tuning
the performance of the JText connector
To tune the polling performance of the JText connector,
set the following connector configuration properties as described
below.
- PollQuantity - This property sets the maximum number of business
objects that the connector can deliver to the integration broker
in a single call to poll for events. If you set PollQuantity to a high value, the connector tries to submit more business
objects in one poll. This can improve performance and helps to clear
up internal queues and memory usage.
Enabling the connector to post large quantities of business objects
to the integration broker, however, can affect other business-integration
components. For example, if the message queuing system has been
set up with default values, the queues can fill up quickly if the
JText connector sends many large business objects through the system.
Therefore, when tuning performance, keep in mind that there is an
optimal performance setting for PollQuantity.
- PollFrequency - This connector configuration property specifies
the amount of time between polling actions. Setting this property
to a longer time slows down the connector during event processing.
Setting it to a shorter time ensures that events are picked up,
converted to business objects, and delivered quickly.
In other words, the connector picks up new files during each
poll call. If the connector does not poll often, it takes longer
for it to deliver the files that accrue in the event directory.
If the connector polls frequently, it picks up the files more often
and delivers them more frequently.
The more frequently the connector polls for events, however,
the less time it has for processing requests. If you use the connector
primarily for request processing, set PollFrequency to
a lower value than if you use the connector primarily for event
processing.
As with the PollQuantity configuration property discussed above, setting PollFrequency to
an extreme value, such as a very long or short time, can affect
the performance of other business-integration components.
- FTPPollFrequency - This connector configuration property specifies
how frequently the connector polls an FTP server measured in the
number of standard poll cycles. For example, if PollFrequency is
set to 10000, and FTPPollFrequency is set to 6, the connector polls the local event directory every 10 seconds
and polls the remote directory every 60 seconds. The connector performs
FTP polling only if you specify a value for this property. If FTPPollFrequency evaluates to 0 or blank, the connector does not perform FTP polling.
In summary, the best approach to improving performance
in polling is to set PollQuantity, PollFrequency, and FTPPollFrequency so that they complement each other.
Generating
sample files for testing
You might want to generate a file that looks like the
input file that the JText connector expects. This file can assist
you in setting up the output formats in the source application.
A sample file can also be used for testing.
On InterChange Server Express, the easiest way to generate a
file similar to the input file is as follows:
- Create a pass-through collaboration that takes as input and
sends to the destination the business object that is to be written
out to a file.
- Bind the source port to a connector that supports that business
object and can be emulated by Test Connector.
- Bind the destination port to the JText connector.
- Input sample values for the business object into Test Connector,
and send that business object to the JText connector. The JText
connector writes the values to the output file in the configured
format.
This process enables you to see multiple business objects written
to a single file, which you can use as input during testing.
Generating
sample business objects for testing
You might want to generate business objects that look
like ones the JText connector expects. You can populate the business
objects with values to use during testing.
To cause the connector to automatically generate business object
templates, use the GenerateTemplate configuration property. You can generate a definition for
each business object that the connector supports.
The connector uses the value of the GenerateTemplate property to create an instance of a serialized business object
when the connector starts up. A serialized business
object is the string representation of the business object that
the data handler creates. Use Connector Configurator Express to
specify the names of the business objects for this property.
The syntax for this property is BOName;BOName,
where the name of a specific business object name is substituted
for BOName. Case is significant. To specify
more than one business object, separate the names with a semicolon,
as in Customer;Item. Ending punctuation is not required. Templates for these
business objects are created the next time you start the connector.
The generated templates contain the delivered default values
that are set for the attributes of the business objects in the business
object's definition. If there is no delivered default value
for an attribute, it is either ignored (using CxIgnore) or left blank (using CxBlank). One child business object is created for each single-cardinality
child business object and two identical instances of a child business
object are created for multiple-cardinality business objects.
To begin generating templates for a specified business object,
start the connector. The connector writes the template to the same
file as the output file. If you do not want to use this feature,
leave the GenerateTemplate property empty.
