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).

Configuring polling behavior

To configure polling behavior, perform the following steps:

  1. Configure the following attributes of the MO_JTextConnector_Default meta-object:
  2. Use Connector Configurator to configure the following connector properties:
  3. 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:

Configuring local archiving

To configure the connector for archiving, follow these steps:

  1. Configure the following attributes of the MO_JTextConnector_Default meta-object:
  2. Use Connector Configurator to configure the ArchivingEnabled connector property.
  3. 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:

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 ICS 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:

  1. Configure the following attributes of the MO_JTextConnector_Default meta-object:
  2. 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:

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 ICS 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:

For further information see Specifying remote archiving

Configuring the output file

Table 6 illustrates the possible configuration options for the output file:

Table 6. 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 _businessobjectname:
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:

  1. 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".
  2. 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:

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 7 illustrates delimiter options.

Table 7. 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.

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:

  1. When performing event processing.
  2. 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 ICS.

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 Connector 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:

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
 
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 absolute 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:

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 or Unix 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 JText adapter does not support PDS in MVS as the members of PDS can not be renamed with time stamps while archiving.
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:

  1. Obtains the server name, port number, username, password, and remote event directory from meta-object attributes or default values.
  2. Establishes a connection to the remote FTP site to get event files from the remote event directory.
  3. 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.
  4. 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 UNIX or Windows 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:

  1. Downloads all specified remote event files to the directory specified in the FTPLocalEventDir attribute.
  2. 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.
  3. Disconnects from the FTP server.
  4. 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:

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:

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:

  1. Obtains the server name, port number, username, and password from meta-object attributes or default values.
  2. Establishes a connection to the remote FTP site to place service call request files from the local directory.
  3. Uploads the request files from the local directory to the remote directory.
  4. 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:

Notes on configuring the connector for FTP transfer

The following features apply to FTP transfer of data:

Specifying a data handler

To specify a data handler to be used by the JText Connector, perform the following steps:

  1. 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.
  2. Configure the following child objects of the top-level JText meta-object:

Changing the specified data handler

To change the data handler from the delivered default (either to a different delivered one or to a custom data handler), do the following:

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:

  1. 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

  2. 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_JTextConnector_BOName to MO_JText2Connector_BOName.

    There are two ways you can copy the meta-objects:

  3. In Connector Configurator, copy the connector's definition and rename it to JText2Connector. Change the supported meta-objects and business objects.
  4. Copy any new definition files into the repository. To use Business Object Designer to copy business object definitions into the repository, select the Save To Server submenu from the File menu. Alternatively, on ICS, perform the following steps to copy business object definitions into the repository from the operating system:
    1. Copy the text from the top of the \repository\ReposVersion.txt file to the top of every definition file.
    2. Use the following repos_copy command to copy in the new meta-objects:
      repos_copy -sServerName -iFileName
       
      
  5. Refresh the integration broker's administration utility to verify the new business objects.
  6. For UNIX, 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.
  7. Add a new MQ queue for the new connector. See the Implementation Guide for WebSphere MQ Integrator Broker or System Administration Guide for information on doing this.
  8. Restart the integration broker.
  9. In UNIX, run the connector manager script. In Windows, click on the new shortcut.

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.

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 ICS, the easiest way to generate a file similar to the input file is as follows:

  1. 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.
  2. Bind the source port to a connector that supports that business object and can be emulated by Test Connector.
  3. Bind the destination port to the JText connector.
  4. 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 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.

Copyright IBM Corp. 1997, 2003