flatfiles book

IBM WebSphere AdaptersVersion 7 Release 5 Fix Pack 3 (7.5.0.3)

IBM WebSphere Adapter for Flat FilesUser GuideVersion 7 Release 5 Fix Pack 3(7.5.0.3)

��

NoteBefore using this information and the product it supports, read the information in “Notices” on page 225.

November 2012

This edition applies to Version 7, Release 5, Fix Pack 3 (7.5.0.3) of IBM WebSphere Adapter for Flat Files and to allsubsequent releases and modifications until otherwise indicated in new editions.

To send us your comments about this document, email mailto://[email protected]. We look forward tohearing from you.

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in anyway it believes appropriate without incurring any obligation to you.

© Copyright IBM Corporation 2006, 2012.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

mailto://[email protected]

Contents

Chapter 1. Overview of WebSphereAdapter for Flat Files . . . . . . . . . 1Hardware and software requirements . . . . . . 1Technical overview of the WebSphere Adapter forFlat Files. . . . . . . . . . . . . . . . 2

Outbound processing . . . . . . . . . . 3Inbound processing. . . . . . . . . . . 13Business objects . . . . . . . . . . . . 29WebSphere Application Server environmentvariables . . . . . . . . . . . . . . 31The external service wizard . . . . . . . . 31

Chapter 2. Planning for adapterimplementation . . . . . . . . . . . 33Before you begin . . . . . . . . . . . . 33Security . . . . . . . . . . . . . . . 33Support for protecting sensitive user data in log andtrace files . . . . . . . . . . . . . . . 33Deployment options . . . . . . . . . . . 34WebSphere Adapters in clustered environments . . 38Migrating to version 7.5.0.3 of WebSphere Adapterfor Flat Files . . . . . . . . . . . . . . 40

Migration considerations . . . . . . . . . 41Performing the migration. . . . . . . . . 43Upgrading but not migrating a project . . . . 46

Migrating WebSphere Business Integrationapplications . . . . . . . . . . . . . . 46

Migrating applications from WebSphereInterChange Server . . . . . . . . . . . 47Migration considerations for WebSphere BusinessIntegration adapters . . . . . . . . . . 48Migrating application artifacts from WebSphereInterChange Server . . . . . . . . . . . 49Migrating adapter-specific artifacts . . . . . 50Changes to the import, export, and WSDL filesafter migration . . . . . . . . . . . . 52

Chapter 3. Samples and tutorials . . . 55

Chapter 4. Configuring the module fordeployment. . . . . . . . . . . . . 57Road map for configuring the module . . . . . 57Creating the required local folders . . . . . . . 58Creating the module . . . . . . . . . . . 59Defining WebSphere Application Serverenvironment variables . . . . . . . . . . . 60Defining business objects . . . . . . . . . . 62Converting business objects to COBOL copybookfiles during outbound processing . . . . . . . 63Converting COBOL copybook files to businessobjects during inbound processing. . . . . . . 69Creating a simple service with the adapter patternwizard . . . . . . . . . . . . . . . . 74Starting the external service wizard . . . . . . 79

Configuring the module for outbound processing . 80Setting deployment and runtime properties. . . 80Selecting the operation and data type. . . . . 83Configuring the data binding . . . . . . . 85Configuring data handlers . . . . . . . . 87Setting interaction properties and generating theservice . . . . . . . . . . . . . . . 90

Configuring the module for inbound processing . . 93Setting deployment and runtime properties. . . 93Selecting the operation and data type . . . . 102Configuring the data binding . . . . . . . 103Configuring data handlers . . . . . . . . 105Setting deployment properties and generatingthe service . . . . . . . . . . . . . 107

Chapter 5. Changing interactionspecification properties . . . . . . . 111

Chapter 6. Deploying the module . . . 113Deployment environments . . . . . . . . . 113Deploying the module for testing. . . . . . . 113

Generating and wiring a target component fortesting inbound processing . . . . . . . . 113Adding the module to the server . . . . . . 114Testing the module for outbound processingusing the test client . . . . . . . . . . 115

Deploying the module for production . . . . . 115Installing the RAR file (for modules usingstand-alone adapters only) . . . . . . . . 116Exporting the module as an EAR file . . . . 117Installing the EAR file . . . . . . . . . 118

Deploying the module in a clustered environment 119Deploying module embedded in the application 119Deploying module at node level with embeddedactivation specification . . . . . . . . . 121Deploying module at node level with JNDIactivation specification . . . . . . . . . 124

Chapter 7. Administering the adaptermodule . . . . . . . . . . . . . . 129Configuring logging and tracing . . . . . . . 129

Configuring logging properties . . . . . . 129Changing the log and trace file names . . . . 131

Changing configuration properties for embeddedadapters . . . . . . . . . . . . . . . 132

Setting resource adapter properties forembedded adapters . . . . . . . . . . 132Setting managed (J2C) connection factoryproperties for embedded adapters . . . . . 134Setting activation specification properties forembedded adapters . . . . . . . . . . 136

Changing configuration properties for stand-aloneadapters . . . . . . . . . . . . . . . 138

Setting resource adapter properties forstand-alone adapters . . . . . . . . . . 138

© Copyright IBM Corp. 2006, 2012 iii

Setting managed (J2C) connection factoryproperties for stand-alone adapters . . . . . 139Setting activation specification properties forstand-alone adapters . . . . . . . . . . 140

Starting the application that uses the adapter . . . 141Stopping the application that uses the adapter . . 142Monitoring performance using PerformanceMonitoring Infrastructure . . . . . . . . . 143

Configuring Performance MonitoringInfrastructure . . . . . . . . . . . . 143Viewing performance statistics . . . . . . 145

Enabling tracing with the Common EventInfrastructure . . . . . . . . . . . . . 146

Chapter 8. Troubleshooting andsupport . . . . . . . . . . . . . . 149Techniques for troubleshooting problems . . . . 149Adapter returns version conflict exception message 151Log and Trace Analyzer . . . . . . . . . . 151Known issues in editing the Rule Table. . . . . 152Support for global elements without wrapper . . 152Global elements in SDOX mode throw exceptions 153First-failure data capture (FFDC) support . . . . 154Incomplete file processing in UNIX environments 155Out of memory exception . . . . . . . . . 155XAResourceNotAvailableException . . . . . . 156Unable to invoke adapter through webservices . . 157org.xml.sax.SAXParseException . . . . . . . 158Disabling end point applications of the passiveadapter . . . . . . . . . . . . . . . 158Solutions to common problems . . . . . . . 159Frequently Asked Questions . . . . . . . . 160

Support . . . . . . . . . . . . . . . 161Searching knowledge bases (Web search) . . . 161Getting Fixes . . . . . . . . . . . . 162Self-help resources. . . . . . . . . . . 163

Chapter 9. Reference information . . . 165Business object information. . . . . . . . . 165

Business object structures . . . . . . . . 165Attribute properties . . . . . . . . . . 169Naming conventions . . . . . . . . . . 169

Business faults . . . . . . . . . . . . . 170Custom file splitting . . . . . . . . . . . 171Configuration properties . . . . . . . . . 173

Outbound configuration properties . . . . . 173Inbound configuration properties. . . . . . 191

Globalization . . . . . . . . . . . . . 217Globalization and bidirectional datatransformation . . . . . . . . . . . . 218Bidirectional transformation in business objects 219Properties enabled for bidirectional datatransformation . . . . . . . . . . . . 221

Adapter messages . . . . . . . . . . . . 222Related information . . . . . . . . . . . 222

Video samples . . . . . . . . . . . . 222

Notices . . . . . . . . . . . . . . 225Programming interface information . . . . . . 227Trademarks and service marks . . . . . . . 227

Index . . . . . . . . . . . . . . . 229

iv IBM WebSphere Adapters: IBM WebSphere Adapter for Flat Files User Guide

Chapter 1. Overview of WebSphere Adapter for Flat Files

With WebSphere® Adapter for Flat Files, you can create integrated processes thatcan exchange data with the local file system, without special coding.

You can use the adapter to read data from a file in the local file system, use it inan application on IBM® Business Process Manager or WebSphere Enterprise ServiceBus, and send it back to the local file system. You can also use the adapter to poll adirectory in the local file system for new files and send them to an application forprocessing.

The adapter can be used to read and write any type of file stored in the local filesystem. It can:v Create new filesv Append or overwrite existing filesv Retrieve the content of a given file, retrieve a list of file names in a directory, or

delete a filev Check whether a particular file exists or notv Poll a directory for new files and send them to an application for processing

The following illustration shows the adapter as part of an SOA implementation.

Hardware and software requirementsThe hardware and software requirements for WebSphere Adapters are provided onthe IBM Support website.

To view hardware and software requirements for WebSphere Adapters, seehttp://www.ibm.com/support/docview.wss?uid=swg27006249.

Additional information

The following links provide additional information you might need to configureand deploy your adapter:v The compatibility matrix for WebSphere Business Integration Adapters and

WebSphere Adapters identifies the supported versions of required software foryour adapter. To view this document, go to the WebSphere Adapters supportpage: http://www.ibm.com/support/docview.wss?uid=swg27006249.

Figure 1. Adapter overview

© Copyright IBM Corp. 2006, 2012 1

http://www.ibm.com/support/docview.wss?uid=swg27006249


v Technotes for WebSphere Adapters provide workaround and additionalinformation that are not included in the product documentation. To view thetechnotes for your adapter, go to the following Web page, select the name ofyour adapter from the Product category list, and click the search icon:http://www.ibm.com/support/search.wss?tc=SSMKUK&rs=695&rank=8&dc=DB520+D800+D900+DA900+DA800+DB560&dtm.

Technical overview of the WebSphere Adapter for Flat FilesIBM WebSphere Adapter for Flat Files makes it possible for services running onIBM Business Process Manager or WebSphere Enterprise Service Bus to exchangedata with the local file system.

Services can use the adapter to exchange data with the local file system in twoways:v Through outbound processing, services running on IBM Business Process Manager

or WebSphere Enterprise Service Bus use the adapter to perform operations onfiles in the local file system, for example, to update an order document.

v Through inbound processing, services running on IBM Business Process Manageror WebSphere Enterprise Service Bus use the adapter to receive events from thelocal file system, for example, to be notified that a customer record has beenupdated.

You configure the adapter to perform either outbound or inbound processingthrough the external service wizard, launched through IBM Integration Designer.Using the external service wizard, you can create a module, which consists of aproject in IBM Integration Designer and a unit of deployment to IBM BusinessProcess Manager or WebSphere Enterprise Service Bus. Each module containscomponents that make up a service for either an import or an export:v An import is the point at which a SCA module accesses an external service (a

service outside the Service Component Architecture (SCA) module) as if it werelocal. An import defines interactions between the SCA module and the serviceprovider. An import consists of a binding and one or more interfaces.

v An export, also known as an endpoint, is an exposed interface from a SCAmodule that offers a business service to the outside world. An export has abinding that defines how the service can be accessed by service requesters, forexample, as a web service.

The module is packaged and deployed to IBM Business Process Manager orWebSphere Enterprise Service Bus as an enterprise archive (EAR) file.

To represent files that are exchanged between a module and the local file system,the adapter uses business objects. A business object is a logical data container thatcontains the data that is processed by the adapter. You can create business objectsusing the external service wizard or by using the business object editor in IBMIntegration Designer.

The adapter uses adapter-specific data bindings and data handlers to transformdata from one format to another during inbound and outbound processing. Databindings are essentially maps that define how a business object is to be formatted.A data binding reads the fields in a business object and populates thecorresponding fields in the file. The data binding that is used depends on theinternal format of the file. Each data type has an equivalent data binding. You usethe external service wizard to configure the data binding.

2 IBM WebSphere Adapters: IBM WebSphere Adapter for Flat Files User Guide

http://www.ibm.com/support/search.wss?tc=SSMKUK&rs=695&rank=8&dc=DB520+D800+D900+DA900+DA800+DB560&dtm


Data handlers perform the conversions between a business object and a nativeformat. When you select a data type that contains business objects, you mustspecify the data handler that performs the conversion. Data handlers are providedby IBM Business Process Manager or WebSphere Enterprise Service Bus.

Outbound processingDuring outbound processing, the adapter receives a request from the module, inthe form of a business object, to perform an operation on a file in the local filesystem. The adapter performs the requested operation and returns a businessobject, if applicable, that represents the result of the operation to the component.

The following illustration shows the outbound processing flow for WebSphereAdapter for Flat Files.

Outbound operationsAn operation is the action that an adapter can perform on the local file systemduring outbound processing. The name of the operation indicates the type ofaction that the adapter takes.

The adapter supports the following operations during outbound processing.

Append operation:

The Append operation appends content to a specified file.

If you select the Enable response type for the operation check box in the externalservice wizard, the file name is returned to the component in a business object.

You can specify a delimiter between business objects in a file by using theIncludeEndBODelimiter property. When this property is not specified, its defaultvalue <EndBO> gets appended at the end of each business object in a file.

Note: If required, you can define any escape sequence character and Unicodeescape characters as the value for the endBODelimiter property in the “Interactionspecification properties” on page 185.

If the CreateFileIfNotExists property is set to true and the file does not exist, theadapter creates a file. If the GenerateUniqueFile property is set to true, the adaptergenerates a unique file and ignores the value in the Filename property.

Note: The GenerateUniqueFile property is deprecated. Although you can currentlyset this property, but the adapter always treats the value for this property as false.

Figure 2. Outbound processing

Chapter 1. Overview of WebSphere Adapter for Flat Files 3

If a staging directory is specified in the StagingDirectory property, the file to beappended is copied from the output directory to the staging directory, and thecontent is added for that file in the staging directory. The file is then moved backto the output directory. If a staging directory is not specified, the content is addedon the file in the output directory.

If the file that is to be appended does not exist and the CreateFileIfNotExistsproperty is set to false, the adapter generates a RecordNotFoundException error.

If the Filename property has no value, the adapter generates aMissingDataException error.

Note: For a wrapper business object, if you do not specify the value for theCreateFileIfNotExists property on the wrapper, then the adapter uses the valuespecified in its interaction specification property.

Create operation:

The Create operation creates a file with the specified name. You can modify the filename by specifying different properties. For example, you can attach a sequencenumber to the file.

If you select the Enable response type for the operation check box in the externalservice wizard, the file name is returned to the component in a business object. If afile with the specified name exists, the adapter generates aDuplicateRecordException error, and no file is created.

If a staging directory is specified in the StagingDirectory property, the file that is tobe created is copied from the output directory to the staging directory, and thecontent is written for that file in the staging directory. The file is then moved backto the output directory. If a staging directory is not specified, the content is writtenon the file in the output directory.

Note: You can configure a staging directory only if the file content is to be writtenbefore the Create operation returns the resultant values. You cannot use a stagingdirectory if the Create operation returns an output stream and the componentwrites to this stream.

Generate unique file name during Create operation

You can configure the adapter to generate a unique file name in the wrapperbusiness object during run time. If you specify the GenerateUniqueFile property asTrue in the wrapper business object, the adapter generates a unique file name andignores the value specified in the Filename property. The name of the unique filethat is generated by the adapter is in the form of a random number. You canspecify a prefix and suffix (file extension) for the file name. For example, a filename with an abcd prefix and a suffix of .xyz, can be: abcd23423.xyz, where 23423is the randomly generated number by the adapter.

Note: You can also specify a staging directory, when configuring the adapter togenerate a unique file name during the Create operation.

The adapter selects the values for the unique file name by using the followingorder of precedence:v Wrapper business object propertiesv Interaction specification properties


v Managed connection factory propertiesv If no values are found from the preceding three properties, the adapter uses the

default values.

Note: You must specify a minimum of three letters for the prefix. If you do notspecify the prefix and suffix for the unique file name, the adapter uses ffa as theprefix and .tmp as the file extension during the unique file name generation.If you do not specify the GenerateUniqueFile property at the wrapper level, theadapter sets the value as False and does not generate a unique file name.

Sequence file

The adapter appends a sequence number to the output file name to create asequence file along with the output file. For example, if the output file name in therequest is Customer.txt, a file with the name Customer.n.txt is created, where n isthe sequence number for the request. If another request with an output file nameof Order.txt is received, the sequence number increments by 1 and Order.n+1.txtis generated.

If the FileSequenceLog managed connection property is specified, the adapterappends a sequence number to the output file name specified in the request andthe next request uses the sequence number in the sequence file.

No new sequence number is created for each individual file name. If the outputfile name does not have an extension, the sequence is appended at the end of thefile name. For example, if the output file name in the request is Customer, a filewith the name Customern is created.

To avoid setting the output directory and file name in the business object for eachrequest, you can generate file sequencing for a particular type of request by settingthe output directory and file name at the managed connection level. When theadapter receives a request to create a file, it checks the file sequence log to seewhether a file with that name exists. If one does, the adapter uses the file sequencenumber to create a file name.

Note: The directory path and file name specified in the business object takeprecedence over the managed connection property values.

In a clustered environment, an environment in which you have one instance of theadapter running on several systems, the sequence file specified by theFileSequenceLog property must be on a mapped drive that is accessible by all thenodes in the cluster. The adapter must have write permission for the sequence logfile, or an IOException error is returned.

Note: In the Windows operating systems, such as, Windows 7, Windows Vista,and Windows Server 2008, there are issues faced in the mapped drive connection.Due to this issue, in a clustered environment, where the nodes are running ondifferent machines, the files in the mapped event directory might not be processedcorrectly during outbound operations. For more information about working withmapped drives, refer to articles on mapped drive connection to network sharing,for your operating system.

If the FileSequenceLog property is specified and the GenerateUniqueFile propertyis enabled, the GenerateUniqueFile property takes precedence over the


FileSequenceLog property. The sequence number will continue to increment afteran adapter restart. If the sequence file is deleted manually, the sequencing startsagain from 1.

Delete operation:

The Delete operation deletes a specified file.

Delete

Optionally, you can select to return the output of the delete operation to acomponent in a business object. If you select the Enable response type for theoperation check box in the external service wizard, the adapter returns true if thefile is deleted successfully. If the file permission for delete is not present, theadapter returns false.

If the file does not exist, the adapter generates a RecordNotFoundException error.

Note: In z/OS® environment, the WebSphere Adapter for Flat Files also deletes afile configured with the No Delete permission, if the file is marked for deletionduring the delete operation.

Exists operation:

The Exists operation checks to see whether a specified file exists.

Exists

If the file that is indicated exists in the specified directory or any of the subfolders, a successful response is returned to the component in the form of abusiness object. The business object has one attribute, which is set to true if the fileexists or false if the file does not exist. If the file does not exist, or if the directorydoes not exist, the adapter returns false.

List operation:

The List operation lists the file names in the specified directory.

List

If the directory does not exist, the adapter generates a RecordNotFoundExceptionerror.

Overwrite operation:

The Overwrite operation overwrites the specified file with the content specified inthe request.

If you select the Enable response type for the operation check box in the externalservice wizard, the file name is returned to the component in a business object. If astaging directory is specified in the StagingDirectory property, the file that is to beoverwritten is copied from the output directory to the staging directory, and thecontent is overwritten for that file in the staging directory. The file is then movedback to the output directory. If a staging directory is not specified, the content isoverwritten on the file in the output directory.


Note: You can configure a staging directory only if the file content is to be writtenbefore the Overwrite operation returns the resultant values. You cannot use astaging directory if the Overwrite operation returns an output stream and thecomponent writes to this stream.

When the input request is received as a FlatFileOutputStreamRecord record, theadapter returns an output stream.

If the CreateIfFileNotExists property is set to true, the adapter creates a file. TheGenerateUniqueFile property is deprecated. Although you can currently set thisproperty, but the adapter always treats the value for this property as false.

If the file to be updated does not exist and the CreateFileIfNotExists property is setto false, the adapter generates a RecordNotFoundException error.

Note: For a wrapper business object, if the value is not specified for theCreateFileIfNotExists property on the wrapper, the adapter uses the value specifiedin its interaction specification property.

Retrieve operation:

The Retrieve operation retrieves the content of the specified file and returns it inthe form of a business object. During outbound processing, you can also delete andarchive the file returned during the retrieve operation.

During a retrieve operation, the adapter retrieves the content of the file specified inthe Retrieve request and returns it in the form of a generic or a content-specificbusiness object. The adapter uses the file splitting feature to divide a large file intosmaller chunks, which are then retrieved separately. The file content is splitaccording to the SplittingFunctionClassName and SplitCriteria properties definedin the interaction specification. These properties contain the outbound connectionproperties the adapter uses to interface with the file system. If you configure a datahandler, the adapter returns a content-specific business object; otherwise, it returnsa generic business object.

To delete the original file after it is retrieved, set the DeleteOnRetrieve property inthe interaction specification. To archive the file before it is deleted, set theArchiveDirectoryForDeleteOnRetrieve property.

During the retrieve operation, if the file that is specified in the Retrieve requestdoes not exist, the adapter generates a RecordNotFoundException error.

Note: For a wrapper business object, if the value is not specified for theDeleteOnRetrieve property on the wrapper, the adapter uses the value specified inits interaction specification property.

Outbound data transformationDuring outbound processing, the adapter performs data transformation based onthe adapter-specific data binding and data handler you select when you configurethe adapter for outbound processing in the external service wizard.


Outbound processing with data transformation

During outbound processing, the adapter transforms business objects to the dataformat expected by the application. The process is controlled by an adapter-specificdata binding and data handler that you select when you configure the module foroutbound processing.

Figure 3 illustrates the way data is transformed during outbound processing.

The following steps describe outbound processing with data transformation.1. For all operations except Retrieve, the adapter performs data transformation

based on the input data type and the configured data handler. If the input typeis not a generic type (FlatFile or FlatFileBG), the adapter transforms the data.For the Retrieve operation, the adapter transforms the data only if the datahandler property of the data binding is configured.

2. The configured data binding is invoked to process the business object.3. The data binding checks the value specified for the data handler property in

the data binding properties, and invokes a content-specific data handler basedon the value set for the data handler property.

4. The adapter performs the requested operation on the file and can return aresponse business object:v For the Create, Append, and Overwrite operations, if output is configured,

the response business object contains the file name.v For the List operation, the response business object contains a list of files in

the specified directory.v For the Exists operation, the response business object contains a value of

either true or false.

Figure 3. Data transformation during outbound processing


v For the Retrieve operation, the content of the retrieved file is returned in theform of a generic or content-specific response business object.

v For the Delete operation, if output is configured, the response business objectcontains a value of either true or false

Outbound processing without data transformation

For all operations except Retrieve, if the input data type is a generic type (FlatFileor FlatFileBG), the adapter performs outbound processing without datatransformation. For Retrieve operations, if no value is set for the data handlerproperty of the data binding, no data transformation takes place. During this typeof processing, a special data structure, UnstructuredContent, is used to hold thecontent.

Figure 4 illustrates outbound processing without data transformation.

The following steps describe outbound processing without data transformation.1. For all operations except Retrieve, the adapter checks the input type of the

request data object. If the input type is a generic type (FlatFile or FlatFileBG),the adapter does not perform any data transformation on the incoming object.For the Retrieve operation, the adapter checks for the data handler property. Ifno value is specified, it does transform the data.

2. The configured data binding is invoked to process the business object.3. For the Retrieve operation, the adapter checks the data handler property. If no

value is set for the data handler, the adapter does not transform the data.4. The adapter performs the requested operation on the file and can return a

response business object as follows:v For the Create, Append, and Overwrite operations, if output is configured,

the response business object contains the file name.v For the List operation, the response business object contains a list of files in

the specified directory.v For the Exists operation, the response business object contains a value of

either true or false.

Figure 4. Outbound processing without data transformation


v For the Retrieve operation, the content of the retrieved file is returned in theform of a generic or content-specific response business object.

v For the Delete operation, if output is configured, the response business objectcontains a value of either true or false.

File splittingTo support files that contain multiple records, the adapter provides an optional filesplitting feature. When you use this feature during the Retrieve operation, theadapter divides large files into smaller chunks, which are then retrieved separately.

Depending upon the type of content contained in the file, the file can be split bydelimiter or by size.v When the content of the business object has a definite structure, for example, if

it contains elements such as name, address and city, the file is split by delimiter.v When the business object contains unstructured data, such as plain text or

binary files, the file is split by size.

By default, the adapter splits files by size.

The value specified in the SplitCriteria property determines the method that isused. The default value for SplitCriteria property is zero, which means that nosplitting is performed. You can also leave the values of the SplitCriteria andSplittingFunctionClassName properties empty if no splitting is required.

You can optionally provide a custom file splitter class. Set theSplittingFunctionClassName property to the name of the class.

File splitting by delimiter

When one or more characters such as a comma (,), semicolon (;), quotation mark( ", ’ ), brace ({}), or slash ( / \ ) (delimiters) are used to separate thebusiness objects in a file, the adapter can split the file into smaller chunks based onthe delimiter. You define the delimiter that separates the business objects in the filein the SplitCriteria property.

You can enable file splitting by delimiter by specifying the value of theSplittingFunctionClassName property ascom.ibm.j2ca.utils.filesplit.SplitByDelimiter.

The following rules apply to the use of delimiters:v All new lines in the delimiter are represented by platform-specific newline

characters. The platform-specific newline characters are shown in Table 1.

Table 1. Platform-specific newline characters

Platform Newline character

Macintosh \r

Microsoft Windows \r\n

UNIX \n

v If there is more than one delimiter, each delimiter must be separated by asemicolon (;). The delimiters are matched in the order in which they are given. Ifthe semicolon is part of the delimiter, it must be escaped as \;. For example, ifthe delimiter is ##\;##, it is processed as ##;##.


v To skip content that is part of the delimiter, specify a double semicolon (;;) infront of it so that the content between the delimiters is skipped. For example, ifthe event file contains a business object in the following format and thedelimiter is ##;;$$, the adapter considers ##$$ as the delimiter and skipscontent skipped by the adapter:Name=SmithCompany=IBM##content skipped by the adapter$$

v The delimiter can have any value, and there are no restrictions on it. Thedelimiter is a combination of a valid string, the newline character (for example,\n), and a semicolon separator if there is more than one delimiter. A delimiterdoes not have to comprise the newline character and a semicolon. The newlinecharacter is used only when a newline is to be considered when splitting thecontents of the file. Examples of valid delimiters include:– ####;\n;\n

– ####;$$$$;\n;####

– %%%%;$$$$$;#####

– \n;\n;$$$$

– ####\;####;\n;$$$$$

– \n;\n;\n

– ####;;$$$$

– \r

– \r\n

– $$$$;\r\n

v If the delimiter is at the end of the file, the SplitCriteria property usesEND_OF_FILE to determine the physical end of the file.

Example of a common scenario and the recommended delimiter format:

Table 2. Delimiter format for a scenario

Databinding BO content Recommended delimiter format

XML <?xml version="1.0" encoding="UTF-8"?><customer:Customer xsi:type="customer:Customer"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:customer="http://www.ibm.com/xmlns/prod/websphere/j2ca/flatfile/customer"><CustomerName>Deepa</CustomerName><Address>IBM</Address><City>Bangalore</City><State>KA</State></customer:Customer>

\n

File splitting by size

The value specified in the SplittingFunctionClassName property determineswhether a file is split by size. If the SplittingFunctionClassName property is set tocom.ibm.j2ca.utils.filesplit.SplitBySize, the SplitCriteria property mustcontain a valid number that represents the maximum file size, in bytes. If the file islarger than the value specified in the SplitCriteria property, the file is split intochunks and each chunk is posted to the import separately. If the file is smaller thanthe SplitCriteria value, the entire file is posted to the import.


When event files are split into chunks, each chunk becomes a business object. Thismeans that the value specified for the PollQuantity property and the number ofbusiness objects delivered to the import can be different. Although the adapterpolls according to the PollQuantity value, it actually processes the number ofbusiness objects in the file one at a time. For example, if an event file is chunkedinto three parts, one file is polled and the three business objects are delivered tothe import (because each chunk creates a single business object).

At the import, the adapter does not reassemble the chunked data into a single file,but it provides information about the chunks to enable IBM Business ProcessManager or WebSphere Enterprise Service Bus to reassemble them into a singlefile. The chunk information is included in the ChunkFileName property of theFlatFileInputStreamRecord record, and includes the chunk size in bytes and theevent ID. The event ID of a chunk uses the following form: eventFileLocation_/_timestampStr_/_MofN, where M is the current chunk number and N is the totalnumber of chunks. An event ID would look like the following example:

C:\flatfile\eventdir\eventfile.in_/_2005_01_10_10_17_49_864_/_3of5, wheretimestampStr has the following format:year_month_day_hour_minutes_seconds_milliseconds.

Generating unique file namesTo generate unique file names during Create operations, add a persistent sequencenumber to the default file name or use random numbers to generate file names.

There are two ways to generate unique file names during Create operations:1. Add a persistent sequence number to the default file name. This method is

recommended, especially in a clustered environment.2. Use random numbers to generate unique file names without any persistence.

Generating unique file names using a persistent sequence number

To generate unique file names using a persistent sequence number, specify:v The sequence file, which is the complete path of the file where the sequence

numbers are storedv The default target file name

The adapter generates a file name that consists of the default target file name withthe sequence number appended to it.

Note: By default, the sequence number starts from one and continues until thenumber 9223372036854775807. When this number is reached, the sequence numberis reset and the numbering starts automatically from one.

The properties that control the generation of unique file names are present in threeplaces:v The managed connection factory properties (the Default target file name and

Sequence file properties)v The interaction specification properties (the Default target file name and

Generate a unique file properties)v The wrapper business object

The properties in the business object take precedence over the properties in theinteraction specification, which take precedence over the managed connection


factory properties. Unless you want to specify properties for individual businessobjects, use the properties in the managed connection factory to control thegeneration of file names.

If the default file name has an extension, the sequence number is appended beforethe extension. For example, if the default file name is Customer.txt in the managedconnection factory, the output file names created are Customer.1.txt,Customer.2.txt, and so on.

For each request, the adapter increments the number in the sequence file, and theinput type takes the sequence number that is currently stored in the sequence file.Sequence numbers are not maintained separately for different input data types.

For compatibility with sequence files generated with previous versions of theadapter, where sequence numbers were maintained separately for different inputdata types, the adapter checks for all entries in the file that have the older format(<dirPath>/Customer.txt = 2, where Customer.txt is the default file name and 2 isthe sequence number to be used when the adapter receives another Create requeston the same file). The adapter searches for all such sequence numbers for eachinput type and uses the highest sequence number as the sequence number for thenext input type. The adapter then overwrites the entire file with the new(increments) sequence number.

Important: Unless they are part of a cluster, two adapter instances must not accessthe same sequence file, because it might result in delayed processing of batchrequests.

Generating unique file names using random numbers

To generate unique file names using random numbers, set the GenerateUniqueFileproperty in the managed connection factory, interaction specification, or in thewrapper business object to true. When generating unique file names, you canspecify a prefix and suffix (file extension) for the file name. This setting enables theadapter to generate file names that are unique but with a predefined prefix andsuffix to its file name. For instance, if you specify the prefix as ffaa and the fileextension as .abc, the adapter generates unique file names with the followingformat: ffaa[RandomNumber].abc, where RandomNumber is the random number thatthe adapter generated. For example, ffaa23423.abc.

Inbound processingWebSphere Adapter for Flat Files supports inbound event processing. It polls thelocal file system at specified intervals for events, such as the creation of a file.When it detects an event, it converts the event data into a business object andsends it to the module for processing.

The following illustration shows the inbound processing flow for WebSphereAdapter for Flat Files.


When a change occurs in the local file system, an event file, which is a new orchanged file, is created in a specific directory. You configure this directory as theevent directory for the adapter. Although an event file can represent one or moreevents in the file system, it forms a single unit of transfer to the adapter.

The adapter polls the event directory on the file system at regular intervals, basedon the value set in the PollPeriod property. When a file arrives in the eventdirectory, the adapter sends the content of the file to the export. The file contentcan be sent in its entirety or split into several business objects, or chunks. Theadapter sends the business objects to the export by using a function selector, whichselects an operation to invoke on the component and provides the correct databinding.

The inbound processing flow is described in the following steps.1. Events, in the form of files, are generated in the file system.2. The adapter polls the event directory.3. The adapter assigns each event an event ID and stores the event ID in the

event store. The event store is a persistent cache where event records are saveduntil a polling adapter can process them. You must create this database beforeyou configure the adapter. The default name of the database is FFDB.

4. The adapter reads each event file as bytes. If file splitting is enabled, theadapter parses the event file based on the values set in theSplittingFunctionClassName and SplitCriteria properties:v If splitting is based on a delimiter, the class that performs this functionality

and the split criteria are provided.v If splitting is based on file size, the class name that performs this

functionality is provided.5. If the configured data type is object-specific, for example, CustomerWrapper,

the data handler is configured on the DataBinding, and the adapter transformsthe data. If the configured data type is FlatFile or FlatFileBG, the adapter passesthe content of the file as a byte array within a FlatFile business object, and notransformation is performed.

Note: If file splitting is enabled, the business object contains the file size andthe event ID.

6. The adapter sends the business object to the export through a function selector,which selects an operation to invoke on the component and provides thecorrect data binding. After the business object reaches the export, the event isdeleted from the event store. If archiving is enabled, the event is moved to anarchiving table before it is deleted.

Figure 5. Inbound processing


Polling files in subdirectories

By default, when the adapter polls files in the event directory, it polls files from theroot directory only and ignores files in the subdirectories. If you set thePollSubDirectories property in the activation specification to True, the adapter firstpolls the files in the root directory and then polls the files in the subdirectories.After the adapter retrieves all the files, it sorts them according to the value set forthe SortEventFiles property. The adapter then processes the files according to thevalue set for the PollQuantity property and sends the business objects to thedownstream components.

Event archiving

To track successfully polled events, you can configure an archive directory on thefile system by using the ArchiveDirectory activation specification property in theexternal service wizard. The files are copied to the archive directory with either asuccess or fail extensions, as specified in the activation specification.

Event file locking

File locking behavior is operating system dependent. On Windows, if the adapterpolls any file from the event directory that another application is using and the fileis in the process of being copied to the event directory, they are not made availableto the adapter for processing.

However, in UNIX environments, such as AIX®, there is no file locking mechanismthat prevents applications from accessing files that are being written to. A file thatis being copied to the event directory by another application is made available tothe adapter for processing, causing erroneous results. There is no platformindependent way in Java™ to check whether a file is being written to.

To prevent this situation from occurring, you can first copy the event file to astaging directory and then move it to the event directory using the movecommand. Some sample UNIX scripts are provided as part of the adapter. Thescript file named CheckIfFileIsOpen.sh is available in the Unix-script-file folder inthe adapter installer.

Rule-Based filtering of events

The adapter supports the rule-based filtering of events, which is optional forinbound processing. You can filter the events based on multiple rules. You candefine a combination of these rules, group them with Boolean logic, and filter theevents using the following metadata:v FileNamev File Sizev Directoryv Last Modified

For example, you can use FileName "MatchesFilePattern" *.txt, where FileName isthe property type, "MatchesFilePattern" is the operator and "*.txt" is the value.

The rule is applied to the files that are filtered by the event file mask criteria. Bydefault, event file mask will have "*.*" as default value.


Rule-based filtering does not support the logical "OR" operator values betweenmultiple rules.

Note: Adapter does not support rule-based filtering when the EIS is on MVS™

platform.

Table 3. Metadata filtering properties

Property Valid operators Value Prerequisites

FileName Matches_File_Pattern For example: *.txt Nil

Matches_RegExp Java Regular Expression

FileSize Greater than, Less than, Greaterthan or equal to, Less than orequal to, Equal to, Not equal to.

Numeric value in Bytes. Forexample: 10000

Nil

Directory Matches_RegExp Java regular expression pollSubDirs = true

LastModified Greater than, Less than, Greaterthan or equal to, Less than orequal to, Equal to, Not equal to.Note: Select the 'Equalto' operator when youchoose the days of a week.

Day of the week or Time. Forexample : MONDAY or 20:41:10

Nil

END-OF-RULE END-OF-RULE END-OF-RULE Nil

Event persistence

The adapter supports event persistence for inbound processing in case of abrupttermination. Event persistence (or assured-once delivery) is a way to ensure thatevents are delivered only once to the export in the case of a failure. During eventprocessing, the adapter maintains the event state in an event store on the datasource. You must setup the data source using IBM Business Process Manager orWebSphere Enterprise Service Bus before you create the event store. To use therecovery feature provided by IBM Business Process Manager or WebSphereEnterprise Service Bus, set the AssuredOnceDelivery property in the activationspecification to True. This recovery feature is enabled by default.

The adapter also provides for event persistence by using an in-memoryrepresentation of the event store. When you use this feature, you do not need tocreate a JNDI data source or an external event store, and event processing is faster.However, with this feature there is no support for event recovery. If there is aserver failure, the in-memory event stores are lost. To prevent the loss of events inthe case of server failure, the recommended approach is to use the database eventstore.

To use the in-memory event persistence capability of the adapter, you must set theAssuredOnceDelivery property to false, or the adapter will log a warningmessage.

Event storeThe event store is a persistent cache where event records are saved until thepolling adapter can process them. The adapter uses event stores to track inboundevents in the system. Each time a file is created, updated, or deleted, the adapterupdates the status of the event in an event store. The status of each event iscontinuously updated by the adapter for recovery purposes until the events aredelivered to the export.


If the adapter detects that there is no event store for the inbound module in thelocal file system, it automatically creates one when the application is deployed tothe runtime environment. Each event store created by the adapter is associatedwith a specific inbound module. The adapter does not support multiple adaptermodules pointing to the same event store.

When the adapter polls the local file system, it creates an entry in the event storefor each event that matches the search criteria specified in the activationspecification properties. The adapter records the status of each new entry as NEW.

If an event is successfully posted, event store entries are deleted. For failed events,the entries remain in the event store. Optionally, the adapter can archivesuccessfully polled event files in an archive directory. The adapter supportsprocessing of event files without any restriction on the file size.

Note: Failed events can result from incorrect data in the event file. For example, afield named fname might appear as fnam. The only way to correct the situation is tosend the event file again with the correct data.

The adapter provides assured-once event delivery. This means that each event isdelivered once and only once. If you set the AssuredOnceDelivery activationspecification property to True, the adapter stores an XID (transaction ID) value foreach event in the event store. When an event is obtained for processing:1. The XID value for the event is updated in the event store.2. The event is delivered to its corresponding export.3. The event is deleted from the event store.

The following figure illustrates the event management flow for the adapter.

Event store structure:

The event store is used by the adapter to track events.

The following event table notes the values that are stored for each event.

Figure 6. Event management flow


Table 4. Event store structure

Column name Type (length) Description

EVNTID Varchar (255) Used to track events duringinbound processing. Eachevent requires an event IDfor tracking purposes. Thisevent ID must be a uniqueidentifier in the table.

EVNTSTAT Integer The status of the event. Theadapter uses the status todetermine whether an eventis new or in process.

Event status values:

NEW (0)

The event is ready to beprocessed.

FETCHED (3)

The adapter picked up theevent for processing.

PROCESSED (1)

The adapter successfullyprocessed and delivered theevent.

FAILED (-1)

The adapter was unable toprocess this event due to oneor more problems.

XID Varchar (255) Used by the adapter forassured event delivery andrecovery.

EVNTDATA Varchar (255) Used to track failed eventsso that they are notprocessed again duringrecoveries. Failed events aremarked "ARCHIVED."

BOSRTPOS Long Used to store the starting filepointer position of thebusiness object associatedwith this event.

BOENDPOS Long Used to store the ending filepointer position of thebusiness object associatedwith this event.

TIMESTMP Timestamp Used to represent the timewhen the event was pickedup for processing.

Event archival values:


You can configure the adapter to archive processed event files in a directory, whichyou can then access to obtain a list of processed events. The file extension reflectswhether an archived event was successful or not.

All archived events in the specified archive directory are stored with success,failure, and original file extensions. Success is used when the event processing issuccessful. If the event processing fails, the file is archived with failure and originalextensions. If the event file has multiple business objects and some of them aresuccessful, there is also a file with a success extension.

The archive extensions are configurable based on the following activationspecification properties: FailedArchiveExt, OriginalArchiveExt, andSuccessArchiveExt.

The following table lists the archive extensions used by the adapter.

Table 5. Event archive values

Extension Definition Format

SUCCESS The event file was delivered to theexport.

<filename>_<timestamp>.SUCCESS

FAIL The event file was not delivered tothe export.

<filename>_<timestamp>.FAIL

ORIGINAL The original event file that waspicked up for processing.

<filename>_<timestamp>.ORIGINAL

File storeThe file store is a persistent cache where event files are saved until the pollingadapter can process them. The adapter uses file store to track inbound files in thesystem. Each time a file is created, updated, or deleted the adapter updates thestatus of the file in the file store.

The file store mechanism provides the following advantages for the adapter:v When multiple adapters are running in a clustered environment, the file store

enables sharing of file processing work. Also, it avoids duplicate file processingby multiple adapter instances.

v The adapter can process large files (files of any size).

When the adapter polls the local file system, it creates an entry in the file store foreach event file that matches the search criteria specified in the activationspecification properties. The adapter records the status of each new entry as NEW inthe event table.


File table structure:

The adapter uses the file table to read, track, and record the details of the eventfiles that are being polled from the event directory.

File table

The file table contains the entries for the files to be polled by the adapter. Theentries in the table support the adapter to read only the file content required bythe polling quantity. In addition, the last position of the file pointer after the partialread is recorded in this table.

The following table describes each file table column.

Table 6. File table structure

Columnname Type Description

FILENAME Varchar(255)

Name of the event file to be processed.

Figure 7. File management flow


Table 6. File table structure (continued)

Columnname Type Description

FILESTAT Integer Status of the file entry. The adapter uses the status to determinewhether the file is a new event to be processed or if the event isbeing currently processed.

UNPROCESSED (0)The new file is ready to be processed. WebSphereAdapter for Flat Files polls the event directory for filesand creates an entry in the file table.

IN-PROCESS (1)A file is in-process if the adapter is reading the filecontent. When the file status is 1, no other adapter isallowed to process the file. The timestamp is updatedwhen the file is picked up for processing.

EVENTS UPDATED (2)The adapter reads only the file content required by thepolling quantity and generates the new events for thecurrent set of business objects.

PROCESSED (3)The file processing is complete and the event entries aregenerated in the event table for the business objects.

FAILED (4)The adapter was unable to read the file because of anunexpected error. The file might be corrupted or invalid.

ARCHIVING (5)The archiving process for this file is in progress.

EOF REACHED (6)Shows the end of file status, when the adapter isenabled to poll for the modified file content.

LBOCOUNTLong Specifies the number of business objects that were processeduntil the file was previously read.

LREADPOS Long Specifies the end position of the file pointer after when the filewas previously read.

TIMESTAMPTimestamp Indicates the time when the file was picked up for processing.

LMDFTIME Timestamp Indicates the last modified time of the file.

Function selectorsDuring inbound processing, a function selector returns the appropriate operation tobe called on the service. You choose a function selector when you configure theadapter for inbound processing in the external service wizard. The adapterprovides three function selectors, FilenameFunctionSelector,EmbeddedNameFunctionSelector, and RootNameFunctionSelector.

FilenameFunctionSelector

FilenameFunctionSelector is a rule-based function selector that provides objectname resolution based on regular expressions that map to file names. A regularexpression is a string that is used to describe or match a set of strings according tocertain syntax rules.


The following table shows examples of matching rules, where a rule consists of theObjectName and Rule fields.

Table 7. Examples of matching rules for FilenameFunctionSelector

FileName ObjectName Rule

Customer0001.txt Customer CUST.*TXT

2231ORZ93.z21 Order [0-9]*OR[A-Z][0-9]{2}.*

2231ORZ93.z21 Order *OR.*

The rules in the second and third rows resolve to the same name, but the rule inthe second row is less “greedy” because it requires a specific sequence of numbersand letters in order for the file name to match, whereas the rule in the third rowresolves anything with the characters “OR” in the file name. The charactercombination “.*” indicates that any character can occur any number of times.

To generate the native function name, the function selector prefixes emit to theobject name that you provide. For example, if the object name is Customer, thefunction selector returns the function name emitCustomer. The object name mustbe the payload object name, for example, Customer or Order, and not the wrapperor business graph name. For pass-through scenarios, use FlatFile as the objectname.

You can configure FilenameFunctionSelector with multiple rules, each containingan object name, and a regular expression to match against the file name. If morethan one rule matches, the function selector returns the object name based on thefirst matching rule. If no rule matches, the adapter generates an error. If no rulesare present in the configuration, the function selector uses the function nameemitFlatFile.

For a detailed explanation of the rules governing the use of regular expressions,see the Java Class Pattern documentation at https://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html.

EmbeddedNameFunctionSelector

EmbeddedNameFunctionSelector is used for content-specific business objects, wherethe object name is embedded in the event file. It returns the function name basedon the content data, and not on the wrapper. For example, if the content-specificbusiness object is CustomerWrapperBG, the function returned by the functionselector is emitCustomer.

EmbeddedNameFunctionSelector must be configured with a data handler. The databinding must be the adapter-specific WrapperDataBinding, and it must beconfigured to use the same data handler that is configured with the functionselector.

RootNameFunctionSelector

RootNameFunctionSelector is used only for global elements in business objects,where the global element name is the root element name in the event XML file. Itreturns the function name based on the global element name. For example, if theglobal element name is CustomerType1, the function returned by the root namefunction selector is ‘emit CustomerType1'.


https://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html

https://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html

RootNameFunctionSelector is used only for global elements with XML Datahandleror UTF8XMLDatahandler.

Note: To use global Elements with Delimited Datahandler or FixedWidthDatahandler, use FilenameFunctionSelector instead of RootNameFunctionSelector.

RootNameFunctionSelector does not need any configuration, as it does not dependson the data handler to get the correct function name.

File retrievalDuring inbound processing, you can manage the retrieval of the files by using thePoll event files for modified content or the Time interval for pollingunchanged files property. You can also use the Include only the newly appendedcontent property to retrieve only the appended file contents.

The Poll event files for modified content property and the Time interval forpolling unchanged files property are mutually exclusive properties.

File retrieval based on last recorded time stamp

The Poll event files for modified content property enables the adapter to pollfor event files repeatedly (when the file content is changed) in the event directoryduring the subsequent poll cycles after the previous event poll. The adapter thenretrieves the event files and delivers them to the endpoint in the next poll cycle.

When you configure this property, the adapter retrieves the new files added to theevent directory since the last poll cycle along with the existing modified files.

This property enables the adapter to monitor file changes based on the lastmodified time stamp of each file. When the adapter is started for the first time, allevent files are polled and processed from the event directory. The adapter does notdelete any polled event file from the event directory after event processing.

During the next poll cycles, only those event files are picked for polling whoselastModifiedTimeStamp values have changed. If the lastModifiedTimeStamp for afile is same, it means that the file is not changed and therefore it is not picked upfor polling. This property allows for polling the complete content of the event fileevery time the file content is changed. For more information, see the “Poll eventfiles for modified content” on page 206 property details.

You can also configure the adapter to deliver the newly appended file contents atthe end of the file by using the Include only the newly appended contentproperty. This property is enabled when you select the Poll event files formodified content property in the external service wizard.

If there is a change in the last modified time stamp value, during the next pollcycle, the adapter checks the event file for any change in the file content. Thechanges to the file contents that are considered by the adapter for polling again arein the form of appended business objects. If the appended business objects exist,the adapter retrieves only the appended file contents by comparing the file withthe file contents of the previous poll. The adapter compares by using the totalnumber of business objects in the previously polled contents and the contents inthe current poll. It does not process any business object if the counts of thebusiness objects are same or less than the last poll.


The following scenarios illustrate how the adapter decides if a business object is tobe delivered to the endpoint. In this example, three business objects are taken as asample count. The scenarios depict how the adapter processes the business objectsbased upon their new processing order in the event file.v If another business object is added after the three business objects, the adapter

delivers the fourth business object to the endpoint.v If the second business object is deleted, and two more business objects are added

at the end, the adapter delivers only the last business object to the endpoint. Inthe changed position, the third business object is not delivered although it is anew business object.

v If the second business object is deleted, and no new business objects are added,the adapter does not poll the event file for delivery to the endpoint. If two morebusiness objects are added at the end, the adapter delivers both the businessobjects to the endpoint.

v If one business object is added in between the second and the third businessobject, then the existing third business object is delivered again to the endpoint.

v If two business objects are deleted and two new business objects are added, thenthe adapter does not deliver any business object to the endpoint.

v If the second business object is deleted and two new business objects are addedin its place, the existing third business object becomes last in the row. Thisconfiguration increases the count of the business objects and the adapter deliversthe earlier existing third business object to the endpoint.

Note: When the server is restarted after a shutdown, the adapter polls all thecontents of the files modified during this time to the endpoint that also include theappended contents.

For more information, see the “Include only the newly appended content” on page204 property details.

Note: If you select the Poll event files for modified content property, then youcannot configure the Time interval for polling unchanged files and File passby reference properties.

File retrieval based on time interval

The Time interval for polling unchanged files property monitors the changesto files in the event directory for the specified time interval. When you configurethis property, the adapter polls the files for event processing that do not undergoany change during the time interval. The adapter also polls files that are currentlybeing edited but are not saved during the specified time interval. The unsavedcontents are not processed during the event processing. This configuration preventsoccurrence of any erroneous results.

When the adapter polls the directory, it uses this property to check if a file ismodified by any event during the specified time interval. The adapter uses thelastModifiedStamp values of the files to determine if a file is changed during thetime interval.

The adapter retrieves the unchanged files in their present state and the changedfiles from their last saved state. For more information, see the Time interval forpolling unchanged files property details.


Note: If you select the Time interval for polling unchanged files property, thenyou cannot configure the Poll event files for modified content property.

File splittingThe adapter supports an optional file splitting feature to reduce memory loadingduring the event processing. When this feature is used, the adapter divides largeevent files into smaller chunks, which are then posted separately to the endpoint.

The adapter splits large event files into several business objects, also called chunks,based on the value you specify in the SplitCriteria property, which can be either adelimiter or a chunk size. Each business object is delivered to the endpointseparately. You can split files using a delimiter when the content of the businessobject has a definite structure; for example, if you have a customer business objectwith elements such as name, address, and city. You can also split files by size whenthe business object contains unstructured data, such as plain text or binary files.

When event files are split into such chunks, each chunk creates a business object.This means that the value specified for the PollQuantity property and the numberof business objects delivered to the endpoint can be different. When file splittingbased on a delimiter is enabled, the PollQuantity activation specification propertyspecifies the number of such event files that are present in the event store, and theclass used to split the event file is set in the SplittingFunctionClassName activationspecification property.

The adapter does not reassemble the chunked data.

The value specified in the SplitCriteria property determines the method that isused. The default value for SplitCriteria property is zero, which means that nosplitting is performed. You can also leave the values of the SplitCriteria andSplittingFunctionClassName properties empty, if no splitting is required.

You can optionally provide a custom file splitter class. Set theSplittingFunctionClassName property to the name of the class.

File splitting by delimiter

When one or more characters such as a comma (,), semicolon (;), quote (",’),brace ({}) or slash (/ \) delimiters are used to separate the business objects in afile, the adapter can split the file into smaller chunks based on the delimiter. Eachchunk is a logical unit that is used to construct a business object when forwardedto IBM Business Process Manager or WebSphere Enterprise Service Bus. You definethe delimiter that separates the business objects in the file in the SplitCriteriaproperty.

To demonstrate how the PollQuantity value works with delimiter file splitting,consider two event files. The first event file contains a business object and thesecond event file contains two business objects. If the PollQuantity value is 2, thefirst business object from the first event file and the next business record from thesecond event file are sent in the first poll cycle. The second business object fromthe second file is sent in the second poll cycle.

The following rules apply to the use of delimiters:v All new lines in the delimiter are represented by platform-specific newline

characters. The platform-specific newline characters are shown in Table 1.


Table 8. Platform-specific newline characters

Platform Newline character

Macintosh \r

Microsoft Windows \r\n

UNIX \n

v If there is more than one delimiter, each delimiter must be separated by asemicolon (;). The delimiters are matched in the order in which they are given.If the semicolon is part of the delimiter, it must be escaped as \;. For example, ifthe delimiter is ##\;##, it is processed as ##;##.

v To skip content that is part of the delimiter, specify a double semicolon (;;) infront of it so that the content between the delimiters is skipped. For example, ifthe event file contains a business object in the following format and thedelimiter is ##;;$$, the adapter considers ##$$ to be the delimiter and skips thewords "content skipped by the adapter", as shown here:Name=SmithCompany=IBM##content skipped by the adapter$$

v The delimiter can have any value, and there are no restrictions on it. Thedelimiter is a combination of a valid string, the newline character (for example,\n), and a semicolon separator if there is more than one delimiter. A delimiterdoes not have to comprise the newline character and a semicolon. The newlinecharacter is used only when a newline is to be considered when splitting thecontents of the file. Examples of valid delimiters include:– ####;\n;\n

– ####;$$$$;\n;####

– %%%%;$$$$$;#####

– \n;\n;$$$$

– ####\;####;\n;$$$$$

– \n;\n;\n

– ####;;$$$$

– \r

– \r\n

– $$$$;\r\n

v If the delimiter is at the end of the file, the SplitCriteria property usesEND_OF_FILE to determine the physical end of the file.

An example of a scenario with the commonly used delimiter format is shown inTable 2.


Table 9. Example of a scenario with a delimiter format

Databinding BO content Recommended delimiter format

XML <?xml version="1.0" encoding="UTF-8"?><customer:Customer xsi:type="customer:Customer"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:customer="http://www.ibm.com/xmlns/prod/websphere/j2ca/flatfile/customer"><CustomerName>Deepa</CustomerName><Address>IBM</Address><City>Bangalore</City><State>KA</State></customer:Customer>##

##;\n

File splitting by size

The value specified in the SplittingFunctionClassName property determineswhether a file is split by size. If the SplittingFunctionClassName property is set tocom.ibm.j2ca.utils.filesplit.SplitBySize, the SplitCriteria property mustcontain a valid number that represents the maximum file size, in bytes. If the eventfile is larger than the value specified in the SplitCriteria property, the file is splitinto chunks and each chunk is posted to the endpoint separately. If the event file issmaller than the SplitCriteria value, the entire event file is posted to the endpoint.

When event files are split into chunks, each chunk becomes a business object. Thismeans that the value specified for the PollQuantity property and the number ofbusiness objects delivered to the endpoint can be different. Although the adapterpolls according to the PollQuantity value, it actually processes the business objectsin the file one at a time. For example, if an event file is chunked into three parts,one file is polled and the three business objects are delivered to the endpoint(because each chunk creates a single business object).

If you use the FileChangeNotification property, then the size of the event file mustbe a multiple of the split chunks. For example, for an event file that contains 90bytes, the split size can either be 15, 6, 3, or 2.

When the event file is not a multiple of the split chunks and the last businessobject is smaller than the split size, the adapter delivers the last business object tothe endpoint correctly during the first event poll. When new contents areappended to the event file and the FileChangeNotification property is specified asTrue, then the updated business object that was smaller than the split size, doesnot send any new content to the endpoint. The sample scenarios for thisconfiguration, when a content is split by 2 bytes, are described in the followingexample.

When the content "ABCDE" is split by 2 bytes, so that the last business objectcontains only "E", then the adapter delivers the contents "AB", "CD", and "E" to theendpoint during the first event poll. In the next event poll, if the content ischanged to:v "ABCDEF", the content is split to "AB", "CD", and "EF", and the adapter delivers

the contents "AB", "CD", and "E" to the endpoint.v "ABCDEFG", the content is split to "AB", "CD", "EF", and "G", and the adapter

delivers the contents "AB", "CD", "E", and "G" to the endpoint.


Note: When an event file contains failed business objects and file splitting by sizeis enabled, then the event file is archived with the .fail extension in the specifiedarchive directory.

At the endpoint, the adapter does not reassemble the chunked data into a singlefile, but it provides information about the chunks to enable IBM Business ProcessManager or WebSphere Enterprise Service Bus to reassemble them into a singlefile. The chunk information is included in the ChunkFileName property of theFlatFileInputStreamRecord record, and includes the chunk size in bytes and theevent ID. The event ID of a chunk uses the following form: eventFileLocation_/_timestampStr_/_MofN, where M is the current chunk number and N is the totalnumber of chunks.

C:\flatfile\eventdir\eventfile.in_/_2005_01_10_10_17_49_864_/_3of5, wheretimestampStr has the following format:year_month_day_hour_minutes_seconds_milliseconds.

Chunk information in WebSphere Adapter for Flat Files, version 7.5

With WebSphere Adapter for Flat Files, version 7.5, the event ID does not containthe total business object count. Therefore, by default the total business object countis no longer part of the chunk information being sent to the endpoint. The formatof the event ID is changed to:EventID=AbsolutePathOfEventFileNameInLocalEventDirectory_/_YYYY_MM_DD_HH_mm_ss_SSS_/_currentBONumber, where theYYYY_MM_DD_HH_mm_ss_SSS string representsyear_month_day_hour_minutes_seconds_milliseconds.

Optionally, you can include the total business object count in the chunkinformation by using the includeBOCountInChunkInfo property. When you enablethe includeBOCountInChunkInfo property, the total business object count isincluded in the chunk information being sent to the endpoint.

Following is the format of the chunk information, when you enable theincludeBOCountInChunkInfo property:AbsolutePathOfEventFileNameInLocalEventDirectory_/_YYYY_MM_DD_HH_mm_ss_SSS_/_currentBONumberofTotalBOCount

For example, the chunk information can be: C:\flatfile\eventdir\c5.txt_/_2010_11_17_14_35_34_509_/_4of5

Following is the format of the chunk information, when you disable theincludeBOCountInChunkInfo property:AbsolutePathOfEventFileNameInLocalEventDirectory_/_YYYY_MM_DD_HH_mm_ss_SSS_/_currentBONumber

For example, the chunk information can be: C:\flatfile\eventdir\c5.txt_/_2010_11_17_14_35_34_509_/_4

For more information, see “Include total business object count in the ChunkInfo(includeBOCountInChunkInfo)” on page 205.

Inbound data transformationDuring inbound processing, the adapter performs data transformation based on theadapter-specific data binding and data handler that you select when you configurethe module in the external service wizard.


Inbound processing with data transformation

The process of data transformation during inbound processing is controlled by theadapter-specific data binding and data handler that you select when you configurethe module. The following steps describe inbound processing with datatransformation.1. Each individual event is retrieved from the event file based on the value set in

the SplitCriteria property. The content is set on the record and sent to the databinding.

2. The adapter checks the expected data type of the inbound operation. If it is nota generic type (FlatFile or FlatFileBG), the adapter checks for the data handlerproperty in the data binding.

3. If the data handler is set, the adapter transforms the data. The data bindinginvokes the data handler and returns a content-specific business object.

4. The adapter passes this content-specific business object to the endpoint bycalling the method returned by the function selector.

Inbound processing without data transformation

If no data transformation is required on the content, for example, when text\xmlcontent must be retained as text\xml content, the event data is not converted intobusiness objects but is passed through as unstructured content.

The following steps describe inbound processing without data transformation.1. Each individual event is retrieved from the event file based on the value set in

the SplitCriteria property. The content is set on the record and sent to the databinding.

2. The data binding checks for the expected type of the event. If it is a generictype (FlatFile or FlatFileBG), the adapter does not transform the data.

3. The data binding sets the content on the UnstructuredContent record and sendsit back to the adapter.

4. The adapter passes this business object to the endpoint by calling the methodreturned by the function selector.

Business objectsA business object is a logical data container that represents the data that isprocessed by the adapter. The data can represent either a business entity, such asan invoice or an employee record, or unstructured text, such as the body of ane-mail or a word-processing document. The adapter uses business objects to senddata to or obtain data from the local file system.

How the adapter uses business objects

During outbound processing, the adapter:1. Receives a business object from the module that represents a request to perform

an operation on a file in the local file system.2. If necessary, converts the business object into a format that can be understood

by the local file system.3. Performs the requested operation.4. Returns a business object, if applicable, that represents the result of the

operation to the module.


During inbound processing, the adapter:1. Retrieves a file from the event directory on the local file system.2. Constructs a business object out of the data, transforming the data, if necessary,

into the required format.3. Sends the business object to the export

How business objects are created

You can create business objects by using either the external service wizard or thebusiness object editor, both of which can be launched from IBM IntegrationDesigner. If you use the external service wizard, the wizard examines files in thefile system and generates business objects to represent them. It also generates otherartifacts needed by the adapter.

If you use the business object editor, you create business objects manually. Afteryou create your business objects, you can use the business object editor to definethe hierarchy of the business objects.

When you run the external service wizard, the WebSphere Adapter for Flat Filesgenerates two types of business objects: content-specific and generic. The adaptergenerates these generic business object XSD files:v FlatFile.xsdv FlatFileBG.xsdv UnstructuredContent.xsdv FileContent.xsd

An example of a content-specific business object is Customer. If you selectCustomer, these content-specific XSD files are generated, in addition to the genericXSD files:v Customer.xsdv CustomerWrapper.xsdv CustomerWrapperBG.xsd

Note: In this example, the business graph CustomerWrapperBG.xsd is generated.The generation of business graphs is optional.

During adapter configuration, you can optionally choose to generate a businessgraph. In version 6.0.2, each top-level business object is contained in a businessgraph, which includes a verb that an application can use in version 6.0.2 to specifyadditional information about the operation to be performed. In version 7.5.0.2 andlater releases, business graphs are optional; they are required only when you areadding business objects to a module created with a version of IBM IntegrationDesigner earlier than version 7.5.0.2. If business graphs exist, they are processed,but the verb is ignored.

Global elementsGlobal elements are the globally defined schema elements, which can be reused byreferencing them in other parts of the schema or from other schema documents.

WebSphere Adapter for Flat Files supports global elements in structured businessobjects. The adapter supports global elements of anonymous type and globalelements of named type, with namespace as well as without namespace in schemabusiness objects.


For more information see, “Global elements in a structured business object” onpage 168.

WebSphere Application Server environment variablesWebSphere Application Server environment variables can be used in the externalservice wizard to specify directory values.

When you configure the adapter for inbound or outbound processing using theexternal service wizard, you set values for various required local files anddirectories. You can later change these values in the deployed application from theIBM Business Process Manager or WebSphere Enterprise Service Bus ProcessAdministrative Console.

With IBM Business Process Manager or WebSphere Enterprise Service Bus Version7.5.0.2, instead of hard coding values for directories and files, you can declare themas WebSphere Application Server environment variables, and specify theenvironment variable names when you run the external service wizard. When youdeploy your application, the environment variable name is replaced with the actualvalue and used by the adapter. If you want to change the property value, you canchange the environment variable in the IBM Business Process Manager orWebSphere Enterprise Service Bus Process Administrative Console.

WebSphere Application Server environment variables can be used for all stringproperty values (not Boolean or integer variables) that are set in inbound andoutbound configuration.

When you create a WebSphere Application Server environment variable, youspecify:v The name of the environment variable, for example, EVENT_DIRECTORY.v The value that the symbolic name represents, for example: C:\flatfile\event.v The scope for the environment variable, which determines the level at which the

environment variable is visible in the Process Administrative Console. The scopelevel can be server, node, or cell:– Server scope limits visibility to the named server. The server scope is the most

specific scope for defining environment variables.– Node scope limits visibility to all the servers on the named node. The Node is

the default scope level.– Cell scope limits visibility to all servers on the named cell.

To create WebSphere Application Server environment variables, use the IBMBusiness Process Manager or WebSphere Enterprise Service Bus ProcessAdministrative Console.

The external service wizardUse the external service wizard to configure your adapter before it is deployed toIBM Business Process Manager or WebSphere Enterprise Service Bus. The wizardexamines files on the local file system, builds services (based on search criteria youprovide), and generates business objects and interfaces.

The external service wizard provides a blueprint for business objects. It allows youto select the artifacts of interest and generates deployable service objects anddescriptions. By selecting meta-object nodes from the metadata tree structure, you


can generate business objects for EIS or database entities. The metadata istransformed into service data objects consisting of business graphs and businessobjects.

The following figure illustrates the external service wizard flow. When finished, anEAR file containing all the information for your adapter project is created. ThisEAR file can then be deployed to the application server.

Figure 8. Basic external service wizard flow


Chapter 2. Planning for adapter implementation

To implement WebSphere Adapter for Flat Files, you must plan for inbound andoutbound processing and consider security and performance requirements. Also, ifyou are migrating from an earlier version of WebSphere Adapter for Flat Files,perform any migration tasks.

Before you beginBefore you begin to set up and use the adapter, you must possess a thoroughunderstanding of business integration concepts, the capabilities, and requirementsof the integration development tools and runtime environment you are going touse, and the environment where you are going to build and use the solution.

To configure and use WebSphere Adapter for Flat Files, you must understand andhave experience with the following concepts, tools, and tasks:v The business requirements of the solution you are building.v Business integration concepts and models, including the Service Component

Architecture (SCA) programming model.v The capabilities provided by the integration development tools you use to build

the solution. You must know how to use these tools to create modules, testcomponents, and complete other integration tasks.

v The capabilities and requirements of the runtime environment you use for theintegration solution. You must know how to configure and administer the hostserver and how to use the Process Administrative Console to set and modifyproperty definitions, configure connections, and manage events.

SecurityWebSphere Adapter for Flat Files relies on the permissions of the user that startsthe IBM Business Process Manager.

The user of the adapter must have sufficient privileges to access the directories andfiles that the adapter tries to access, read, or modify.

Support for protecting sensitive user data in log and trace filesYou can configure the adapter to prevent sensitive or confidential data, in the logand trace files, from being viewed by users without authorization.

Log and trace files for the adapter can contain data from your local file system,which might contain sensitive or confidential information. Sometimes these filesmight be seen by individuals without authorization to view sensitive data. Forexample, a support specialist must use the log and trace files to troubleshoot aproblem.

To protect the data in such situations, the adapter lets you specify whether youwant to prevent confidential user data from displaying in the adapter log and tracefiles. You can select this option in the external service wizard or change theHideConfidentialTrace property. When this property is enabled, the adapterreplaces the sensitive data with XXX's.


See “Managed connection factory properties” on page 177 for information aboutthis optional property.

The following types of information are considered potentially sensitive data andare disguised:v The contents of a business objectv The contents of the object key of the event recordv User name and passwordv Business object data in an intermediate form, such as a comma-delimited version

of a file

The following types of information are not considered user data and are nothidden:v The contents of the event record that are not part of the event record object key,

for example, the XID, event ID, business object name, and event statusv Business object schemasv Transaction IDsv Call sequences

Deployment optionsThere are two ways to deploy the adapter. You can either embed it as part of thedeployed application, or you can deploy it as a stand-alone RAR file. Therequirements of your environment affect the type of deployment option youchoose.

The following are the deployment options:v With module for use by single application: With the adapter files embedded in

the module, you can deploy the module to any application server. Use anembedded adapter when you have a single module using the adapter or ifmultiple modules need to run different versions of the adapter. Using anembedded adapter enables you to upgrade the adapter in a single modulewithout the risk of destabilizing other modules by changing their adapterversion.

v On server for use by multiple applications: If you do not include the adapterfiles in a module, you must install them as a stand-alone adapter on eachapplication server where you want to run the module. Use a stand-alone adapterwhen multiple modules can use the same version of the adapter and you wantto administer the adapter in a central location. A stand-alone adapter can alsoreduce the resources required by running a single adapter instance for multiplemodules.

An embedded adapter is bundled within an enterprise archive (EAR) file and isavailable only to the application with which it is packaged and deployed.


Files

IBM Business Process Manager orIBM WebSphere Enterprise Service Bus

Application

Enterprise informationsystem

Businessfunction

EmbeddedAdapterModule

Module

ModuleModule

Module

Module

A stand-alone adapter is represented by a stand-alone resource adapter archive(RAR) file, and when deployed, it is available to all deployed applications in theserver instance.

Stand-aloneAdapter

Files

IBM Business Process Manager orIBM WebSphere Enterprise Service Bus

Application A

Enterprise informationsystem

Businessfunction

Application B

Module

Module

ModuleModule

Module

Module

Module

Module

Module

While creating the project for your application using IBM Integration Designer, youcan choose how to package the adapter [either bundled with the (EAR) file or as astand-alone (RAR) file]. Your choice affects how the adapter is used in the run timeenvironment and how the properties for the adapter are displayed on theadministrative console.

Choosing either to embed an adapter with your application or to deploy theadapter as a stand-alone module depends on how you want to administer theadapter. If you want a single copy of the adapter and do not care about disruptionto multiple applications when you upgrade the adapter, then you would be morelikely to deploy the adapter as a stand-alone module.

Chapter 2. Planning for adapter implementation 35

If you plan to run multiple versions, and if you care more about potentialdisruption when you upgrade the adapter, you would be more likely to embed theadapter with the application. Embedding the adapter with the application allowsyou to associate an adapter version with an application version and administer itas a single module.

Considerations for embedding an adapter in the application

Consider the following items if you plan to embed the adapter with yourapplication:v An embedded adapter has class loader isolation.

A class loader affects the packaging of applications and the behavior ofpackaged applications deployed on run time environments. Class loader isolationmeans that the adapter cannot load classes from another application or module.Class loader isolation prevents two similarly named classes in differentapplications from interfering with each other.

v Each application in which the adapter is embedded must be administeredseparately.

Considerations for using a stand-alone adapter

Consider the following items if you plan to use a stand-alone adapter:v Stand-alone adapters have no class loader isolation.

Because stand-alone adapters have no class loader isolation, only one version ofany defined Java artifact is run and the version and sequence of that artifact isundetermined. For example, when you use a stand-alone adapter there is onlyone resource adapter version, one adapter foundation class (AFC) version, or onethird-party JAR version. All adapters deployed as stand-alone adapters share asingle AFC version, and all instances of a defined adapter share the codeversion. All adapter instances using a given third-party library must share thatlibrary.

v If you update any of these shared artifacts, all applications using the artifacts areaffected.For instance, if you have an adapter that is working with server version X, andyou update the version of the client application to version Y, your originalapplication might stop working.

v Adapter Foundation Classes (AFC) is compatible with previous versions, but thelatest AFC version must be in every RAR file that is deployed in a stand-alonemanner.If more than one copy of any JAR file is in the class path in a stand-aloneadapter, the one that is used is random; therefore, they all must be the latestversion.

Considerations while deploying adapters with different versions

When you install multiple adapters with different versions ofCWYBS_AdapterFoundation.jar, and if a lower version of theCWYBS_AdapterFoundation.jar is loaded during run time, the adapter returns theResourceAdapterInternalException error message, due to a version conflict. Forexample, when you install Oracle E-Business Suite adapter version 7.0.0.3 andWebSphere Adapter for Flat Files version 7.5.0.3, the following error message isdisplayed "The version of CWYBS_AdapterFoundation.jar is not compatible withIBM WebSphere Adapter for Flat Files" as IBM WebSphere Adapter for Flat Filesloads file:/C:/IBM/WebSphere/ProcServer7/profiles/ProcSrv01/


installedConnectors/CWYOE_OracleEBS.rar/CWYBS_AdapterFoundation.jar withversion 7.0.0.3. However, the base level of this jar required is version 7.5.0.3. Toovercome this conflict, you must migrate all adapters to the same version level.

There are occasions when you work with embedded adapters that do not need aclient-server communication, stand-alone adapters that need a server connection, ora hybrid mix of adapter connections.

The following scenarios cover the different behaviors of AFC version conflictdetection, when you are deploying two or more adapters and at least one of theadapter version is 7.5 or higher.

Deploying a stand-alone Adapter

1. Install WebSphere Adapter for Flat Files version 7.0.1.0 through the IBMBusiness Process Manager administrative console.

2. Install WebSphere Adapter for SAP Software version 7.5.0.0 through theadministrative console.

3. Create ActivationSpec for an ALE pass-through inbound operation.4. Create an application in IBM Integration Designer for a stand-alone ALE

pass-through inbound operation.5. Install and start the application through the administrative console.6. Verify the error.

Note: An error message is generated in the log/trace area of IBM Business ProcessManager, to indicate an AFC version conflict.

Deploying an embedded Adapter

1. Import a build of WebSphere Adapter for FTP version 7.0.1.0, using a RAR file.2. Create a FTP Inbound EMD operation.3. Import a build of WebSphere Adapter for Oracle E-Business Suite version

7.5.0.0, using a RAR file.4. Create an Oracle inbound EMD operation, in the same module where you have

created the FTP Inbound EMD operation.5. Deploy the module to IBM Business Process Manager.6. Check the trace.

At step 5, the deployment fails. At step 6, you get an internal error message due tothe AFC version conflict.

Note: To avoid a name conflict between the business object generated by the twoadapters, generate the artifacts into different folders.

Deploying a combination of stand-alone and embedded Adapters

1. Install WebSphere Adapter for JDBC version 7.0.1.0 through theIBM BusinessProcess Manager administrative console.

2. Create an ActivationSpec for a JDBC inbound operation.3. Create an application in IBM Integration Designer for a JDBC inbound

operation, for the stand-alone Adapter deployment.4. Deploy the JDBC inbound application and trigger your inbound events.5. Create an application in IBM Integration Designer for a WebSphere Adapter for

SAP Software version 7.5.0.0 inbound embedded Adapter deployment.


6. Deploy an SAP inbound application, and trigger your inbound events.

Note: You can resolve the AFC version conflict by using different class loaders forthe stand-alone and embedded deployments. With this approach, the migrationprocess handles different CWYBS_AdapterFoundation.jar files and do not conflictwith each other. You can start both JDBC and SAP inbound applicationssuccessfully, and process Inbound events without exception.

For further assistance, visit http://www.ibm.com/support/docview.wss?uid=swg27006249.

WebSphere Adapters in clustered environmentsYou can improve adapter performance and availability by deploying a module ona clustered server environment. Clusters are groups of servers that are managedtogether to balance workloads and to provide high availability and scalability.

The module you deployed is replicated across all servers in a cluster, regardless ofwhether you deploy the module using a stand-alone or an embedded adapter. Thefollowing IBM products support WebSphere Adapters in a clustered environment:v IBM Business Process Manager or WebSphere Enterprise Service Busv WebSphere Application Server Network Deploymentv WebSphere Extended Deployment

To deploy and configure WebSphere Adapter for Flat Files in a clusteredenvironment, see: “Deploying the module in a clustered environment” on page 119.When you set up a server cluster, you create a Deployment Manager profile. TheHAManager, a subcomponent of the Deployment Manager, notifies the JavaPlatform, Enterprise Edition (JEE) Connector Architecture (JCA) container toactivate an adapter instance. For information about creating clusteredenvironments, see the following link: http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5mx/index.jsp?topic=/com.ibm.wbpm.imuc.z.doc/topics/tins_zos_create_cluster.html.

Using WebSphere Extended Deployment, you can optionally enhance theperformance of adapter instances in your clustered environment. WebSphereExtended Deployment extends the WebSphere Application Server NetworkDeployment capabilities by using a dynamic Workload Manager instance instead ofa static Workload Manager. The dynamic Workload Manager instance can optimizethe performance of adapter instances in the cluster by dynamically balancing theload of the requests. It means that application server instances can be automaticallystopped and started based on the load variations, allowing systems with differentcapacities and configurations to handle load variations evenly. For informationabout the benefits of WebSphere Extended Deployment, see http://publib.boulder.ibm.com/infocenter/wxdinfo/v6r1m1/index.jsp.

In clustered environments, adapter instances can handle both inbound andoutbound processes.

Restriction: During inbound and outbound communication WebSphere Adapterfor Flat Files is not able to switch polling between a IBM Business Process Manageror WebSphere Enterprise Service Bus cluster backup node and the cluster's primarynode when each node is installed on a different operating system. For example, ifthe adapter starts polling on a primary Windows node, it cannot switch to abackup UNIX node because it cannot process the Windows path used for thedirectory storing in progress events.




http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5mx/index.jsp?topic=/com.ibm.wbpm.imuc.z.doc/topics/tins_zos_create_cluster.html



http://publib.boulder.ibm.com/infocenter/wxdinfo/v6r1m1/index.jsp

http://publib.boulder.ibm.com/infocenter/wxdinfo/v6r1m1/index.jsp

High availability for inbound processes

Inbound processes are based on events triggered as a result of updates to data inthe local file system. WebSphere Adapter for Flat Files is configured to detectupdates by polling an event table. The adapter then publishes the event to itsendpoint.

Important: In a clustered environment, the event directory must be on a sharedfile system and not local to any of the cluster machines.

When you deploy a module to a cluster, the Java Platform, Enterprise Edition (JEE)Connector Architecture (JCA) container checks the enableHASupport resourceadapter property. If the value for the enableHASupport property is true, which isthe default setting, all of the adapter instances are registered with the HAManagerwith a policy 1 of N. This policy means that only one of the adapter instancesstarts polling for events. Although other adapter instances in the cluster arestarted, they remain dormant with respect to the active event until the activeadapter instance finishes processing the event. If the server on which the pollingthread was started shuts down for some reason, an adapter instance that isrunning on one of the backup servers is activated.

Note: In the active-passive configuration mode of the adapters, the endpointapplication of the passive adapter instance also listens to the events/messages evenif the enableHASupport property is set to True. This is because thealwaysactivateAllMDBs property in the JMS activation specification is set to True.To stop the endpoint application of the passive adapter instance from listening tothe events, you must set the alwaysactivateAllMDBs property value to False. Formore information, see “Disabling end point applications of the passive adapter” onpage 158.

If the value for the enableHASupport property is set to False, all adapter instancespoll for events in the inbound cluster and the adapter works in an Active-Activeconfiguration. Multiple instances of WebSphere Adapter for Flat Files can be madeactive in a HA cluster in the active configuration mode. When more than oneadapter instance actively polls in a cluster setup, it serves as a load balancer. If oneof the adapter instances in the cluster fails, the other active instances in the clusterhandle the events.

Note: In clustered environments, when the adapter works in a HA Active-Activeconfiguration, it provides both high availability and load balancing support. Thisfunctionality is useful in production environments where high performance isneeded.

In the HA Active-Active configuration, WebSphere Adapter for Flat Files ensuresthat an event is not processed by more than one adapter instance. This results ineach adapter instance polling for a unique event, and delivering the event withoutany duplication to the endpoint.

Note:

v You must configure all the event persistence properties, if the adapter uses theHA Active-Active configuration.

v The local event directory must be present in a mapped drive that can beaccessed by all the adapter instances in the clustered environment.

v Sorting of event files polled is not supported.v Supports only unordered delivery type of events to the export.


v In the Windows operating systems, such as, Windows 7, Windows Vista, andWindows Server 2008, there are issues faced in the mapped drive connection.Due to this issue, in a clustered environment, where the nodes are running ondifferent machines, the files in the mapped event directory might not beprocessed completely or correctly. This may occur during both inbound andoutbound operations. For more information about working with mapped drives,refer to articles on mapped drive connection to network sharing, for youroperating system.

Database support in clustered environments

The adapter currently supports only the following databases:v IBM DB2®

v Oraclev Microsoft SQL Serverv Apache Derby

Note: If a different database is used, you must manually create the eventpersistence table and the file table. For more information about the event table andthe file table, see “Event store structure” on page 17 and “File store” on page 19.

In addition, the databases must support the following features to enable theadapter to run in the Active-Active configuration:v Batch Processing to allow efficient bulk database updates and automated

transaction processingv Transaction to ensure data integrityv FOR UPDATE clause in the SELECT statement with queries that select a range of

data that uses LIMIT, TOP, or the database equivalent.

High availability for outbound processes

In clustered environments, multiple adapter instances are available to performoutbound process requests. So, if your environment has multiple applications thatinteract with WebSphere Adapter for Flat Files for outbound requests, then youmight improve performance by deploying the module to a clustered environment.In a clustered environment, multiple outbound requests can be processedsimultaneously, so that they are not attempting to process the same record.

If multiple outbound requests are attempting to process the same record, such as aCustomer address, the workload management capability in WebSphere ApplicationServer Network Deployment distributes the requests among the available adapterinstances in the sequence they were received. As a result, these types of outboundrequests in a clustered environment are processed in the same manner as in asingle server environment: one adapter instance processes only one outboundrequest at a time. For more information about workload management, see thefollowing link: http://publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/trun_wlm.html.

Migrating to version 7.5.0.3 of WebSphere Adapter for Flat FilesBy migrating to version 7.5.0.3 of WebSphere Adapter for Flat Files, youautomatically upgrade from the previous version of the adapter. Additionally, youcan migrate your applications that embed an earlier version of the adapter, so thatthe applications can use features and capabilities present in version 7.5.0.3.


http://publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/trun_wlm.html

http://publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/trun_wlm.html

Migration considerationsWebSphere Adapter for Flat Files version 7.5.0.3 may have some features andupdates that might affect your existing adapter applications. Before migratingapplications that use WebSphere Adapter for Flat Files, you must consider somefactors that might affect your existing applications.

Compatibility with earlier versions

WebSphere Adapter for Flat Files version 7.5.0.3 is fully compatible with thecustom business objects (XSD files) and data bindings that are created using theadapter version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, and version 7.5.0.2and enables the existing business objects and data bindings to work well in thelatest version of the adapter.

Because version 7.5.0.3 of WebSphere Adapter for Flat Files is fully compatible withversion 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, and version 7.5.0.2, any ofyour applications that used previous versions of WebSphere Adapter for Flat Filesrun unchanged when you upgrade to version 7.5.0.3. However, if you want yourapplications to use features and functionality present in version 7.5.0.3 of theadapter, perform the migration of the artifacts as well as the upgrade of theadapter.

The migration wizard replaces (upgrades) version 6.1.x, version 6.2.x, version 7.0.x,version 7.5.0, or version 7.5.0.2 of the adapter with version 7.5.0.3 and enablesversion 7.5.0.3 features and functionality for use with your applications.

Note: The migration wizard does not create components or modify existingcomponents, such as mappers and mediators to work with version 7.5.0.3 of theadapters. If any of your applications embed an adapter that is version 7.5.0.2 orearlier and you are upgrading to version 7.5.0.3, and you want your applications totake advantage of the features and functions in version 7.5.0.3, you might need tochange those applications.

If the artifacts within a module have inconsistent versions, the entire module ismarked as unavailable for migration and cannot be selected. Versioninconsistencies are recorded in the workspace log, as they indicate that a projectmight be corrupted.

The adapter migration wizard in IBM Integration Designer Version 7.5.1 onlysupports the migration of adapters from version 6.1.x, version 6.2.x, version 7.0.x,version 7.5.0, and version 7.5.0.2 to version 7.5.0.3. It does not support the adaptermigration from lower versions to any of the versions before version 7.5.0.3.

Deciding whether to upgrade or to upgrade and migrate

The default processing of the migration wizard is to perform an upgrade of theadapter and to migrate the application artifacts so that the applications can usefeatures and functions in version 7.5.0.3 of the adapter. When you choose toupgrade the adapter by selecting a project, the wizard automatically selects theassociated artifacts for migration.

If you decide that you want to upgrade the adapter from version 6.1.x, version6.2.x, version 7.0.x, version 7.5.0, or version 7.5.0.2 to version 7.5.0.3, but you donot want to migrate the adapter artifacts, you can do so by clearing the adapterartifacts from the appropriate area of the migration wizard.


Running the migration wizard without selecting any adapter artifacts installs andupgrades your adapter. As the artifacts are not migrated, your applications cannottake advantage of the features and capabilities that exist in version 7.5.0.3 of theadapter.

Migrating multiple adapters referred within a project

When a module contains one or more connector projects, each of which referencesto different adapters (for example, a module project that contains connectorprojects referring to JDBC and SAP adapters), the migration wizard identifies theartifacts belonging to each adapter and migrates these artifacts without disruptingthe artifacts of other adapters.

When you select the module project and launch the migration wizard:v The Source connector field lists the connector projects with the selected module

project.v The Dependent artifact projects area lists only the selected module project.

If you select the connector project and launch the migration wizard:v The Source connector field lists only the selected connector project.v The Dependent artifact projects area lists all projects which reference the

selected connector project, including the module project.

Run the migration wizard in a test environment

Because adapter migration might require you to change those applications that useversion 7.5.0.3 of WebSphere Adapter for Flat Files, you must always perform themigration in a development environment first and test your applications beforedeploying the application to a production environment.

The migration wizard is fully integrated with the development environment.

Deprecated features

Become familiar with the deprecated features in version 7.5.0.2 and make anyrequired changes to your applications.

A deprecated feature is one that is supported but no longer recommended and thatmight become obsolete. The following features from earlier versions of WebSphereAdapter for Flat Files have been deprecated in version 6.2.x and might requirechanges to your applications:v Activation specification:

– ArchivingProcessed– EventContentType– DefaultObjectName

v InteractionSpecification:– DefaultObjectName

v Wrapper properties:– RetrieveContentType– DefaultObjectName


Performing the migrationYou can migrate a project or EAR file to version 7.5.0.3 using the adapter migrationwizard. When the tool is finished, the migration is complete and you can work inthe project or deploy the module.

Before you begin

Review the information in Migration considerations.

About this task

To perform the migration in IBM Integration Designer, complete the followingsteps.

Note: After migration is complete, the following changes occur:v the module will no longer be compatible with previous versions of IBM Business

Process Manager or WebSphere Enterprise Service Bus, IBM Business ProcessManager or WebSphere Enterprise Service Bus, or IBM Integration Designer.

v an XML data handler is added to all the operations. Because this data handler isnot needed for the pass-through operation, you must configure one data bindingwithout the data handler against the pass-through operation.

v a file table is automatically created for storing the event persistence information.The table is created for the supported databases.

The following steps describe how to run the adapter migration wizard from theconnector project menu while in the Java EE perspective in IBM IntegrationDesigner.

Procedure1. Import the PI (project interchange) file for an existing project into the

workspace.

Note: Ensure that you do not modify the contents of the RAR or copy theadapter JAR file outside the connector project.

2. When projects are created in an earlier version of IBM Integration Designer, theWorkspace Migration wizard starts automatically and selects the projects tomigrate. Follow the wizard and complete the workspace migration. For moreinformation, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.imuc.doc/topics/tmigsrcart.html.

3. Change to the Java EE perspective.4. Right-click the module and select Migrate connector project. For example, the

adapter RAR module.You can also launch the adapter migration wizard in the following ways:v Right-click the project in the Java EE perspective and select Migrate adapter

artifacts.v From the Problems view, right-click a migration-specific message and select

Quick Fix to correct the problem.5. In the Select Projects window, perform the following steps:

a. The Source connector field displays the name of the connector project thatyou are migrating. If you are migrating a module project, this field lists all


http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.imuc.doc/topics/tmigsrcart.html


the connector projects in the module project. Select the source project fromthe list. For more information, see “Migrating multiple adapters referredwithin a project” on page 42.

b. The Target connector field displays the name of the connector to which youare migrating. If you are working with more than one adapter version, thislist displays the names of all the compatible connectors. Select the connectoryou want to migrate.

c. The Target version field displays the version corresponding to the targetconnector that you selected in the previous step.

d. The Dependent artifacts project area lists the adapter artifacts that aremigrated. If you are migrating a module project, this area lists only theselected module project. If you are migrating a connector project within themodule project, this area lists all projects which reference the selectedconnector project, including the module project. By default, all thedependent artifact projects are selected. If you do not select a dependentartifact project, that project is not migrated. You can migrate any project thatyou have not selected at a later time. Previously migrated projects, projectswith a current version, and projects that contain errors are unavailable formigration and are not selected. For more information, see “Upgrading butnot migrating a project” on page 46.

e. Click Next. A warning window is displayed with the message, “Propertiesthat are not supported in this version of the target adapter will be removedduring the migration”.

f. Click OK.6. In the Review Changes window, review the migration changes that occur in

each of the artifacts that you are migrating. To view the details, expand eachnode by clicking the + sign.

7. To complete the migration:v Click Finish.v If the files that need to be updated during migration are in read-only mode,

you will be unable to click on the Finish button. To view these files, clickNext. The Update Read-only files window displays the read-only files. Toupdate these files and continue with the migration, click Finish. To exit thewizard without migrating the adapter, click Cancel.

Before running the migration process, the wizard performs a backup of allprojects affected by the migration. The projects are backed up to a temporaryfolder within the workspace. If the migration fails for any reason, or if youdecide to cancel the migration before it completes, the wizard deletes themodified projects and replaces them with the projects stored in the temporaryfolder.Upon completing the migration successfully, all backed up projects are deleted.

8. If you are migrating an EAR file, optionally create a new EAR file with themigrated adapter and artifacts, and deploy it to IBM Business Process Manageror WebSphere Enterprise Service Bus. For more information about exportingand deploying an EAR file, see the topics devoted to it in this documentation.

Results

The project or EAR file is migrated to version 7.5.0.3. You do not need to run theexternal service wizard after exiting the adapter migration wizard.


What to do next

After completing the migration, you must manually update the structure of theevent table. To update the structure of the event table, use the sample databasescripts available at "<IID_HOME>\Resource Adapters\FlatFile_7.5.0.2\Scripts".

Migrating databasesWith WebSphere Adapter for Flat Files, version 7.5, the schema of the eventpersistence table is modified. Hence, after completing the adapter migration, youmust update the structure of the event table to work with the adapter version 7.5.Use the sample database scripts available at "<IID_HOME>\ResourceAdapters\FlatFile_7.5.0.2\Scripts" to update the structure of the event table.

Before you begin

Before updating the structure of the event table, ensure that only the failed eventsare available in the event table. Ensure that you process or delete the unprocessedevents before performing this task.

Note: The database migration is required for both single and HA Active-Activeinstance of adapter configuration. After migrating the adapter, if you use anexisting event table with the adapter version 7.5, then a runtime exception isthrown.

About this task

Perform the following steps to run the scripts and update the structure of theevent table.

Procedure1. Go to the "<IID_HOME>/Resource Adapters/FlatFile_7.5.0.2/Scripts" folder.2. Double-click one of the following scripts corresponding to your database:

v scripts_db2_upgrade.sql – for DB2 and Derby databasev scripts_mssql_upgrade.sql – for Microsoft SQL Server databasev scripts_oracle_upgrade.sql – for Oracle database

3. The selected script performs the following actions:a. A temporary event table with the same structure of the existing event table

is created.

Note: Ensure that the name of the temporary event table (mentioned in thescript) is not already in use for any existing table. If the name is already inuse, then change the name of the temporary event table in the databasescript accordingly.

b. The event data from the existing event table is copied to the temporaryevent table.

c. If the default name of the event table is not used in your application orproject, ensure that you specify the name of the existing event table in thedatabase script.

d. An event table with the new structure is created.e. After the data from the temporary table is copied to the new event table,

the temporary table is deleted from the database.


Results

The updated event table can now be used in your project.

Upgrading but not migrating a projectYou can upgrade the adapter from an earlier version, to version 7.5.0.3 whilechoosing not to migrate the adapter project artifacts.

About this task

Running the migration wizard without selecting any adapter artifacts installs andupgrades your adapter. As the artifacts are not migrated, your applications cannottake advantage of the features and capabilities that exist in version 7.5.0.3 of theadapter.

Procedure1. Import the PI (project interchange) file into the workspace.2. When projects are created in an earlier version of IBM Integration Designer, the

Workspace Migration wizard starts automatically and selects the projects tomigrate. Follow the wizard and complete the workspace migration. For moreinformation, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.imuc.doc/topics/tmigsrcart.html.

3. In the Java EE perspective, right-click the project name and click Migrateconnector project. The Adapter Migration wizard is displayed.

4. In the Select Projects window, clear the dependent artifact projects, and clickNext. A warning window is displayed with the message, “The properties thatare not supported in the version of the target adapter will be removed duringthe migration.”

5. Click OK.6. In the Review Changes window, review the migration changes that occur

during updating the project. To view the details, expand each node by clickingthe + sign.



Results

The project can now be used with WebSphere Adapter for Flat Files, version7.5.0.3.

Migrating WebSphere Business Integration applicationsYou need to migrate the WebSphere Business Integration applications so that theybecome compatible with Version 7.5.0.3 of your adapter.




About this task

Migrating WebSphere Business Integration applications for use with Version 7.5.0.3of your WebSphere adapter is a multistep process. First, the artifacts fromWebSphere InterChange Server are migrated and converted. A project is thencreated for the artifacts in IBM Integration Designer. In the remaining steps, theadapter-specific artifacts are migrated and converted into the JCA-compliantformat supported by Version 7.5.0.3 of the adapter.

Example

The following diagram shows the wizards that you use to migrate WebSphereBusiness Integration solutions from WebSphere InterChange Server, so that theseapplications can be used with Version 7.5.0.3 of your adapter.

IBM Integration DesignerWebSphere InterChange Server

Installation directory

Imports/convertsWebSphere InterChange

artifactsJar file

The imported jar filebecomes a project in

-IBM Integration DesignerThe adapter artifacts arenot fullyJCA-compliant at this point

Enterprise servicewizard

Migrating WebSphere Business Integration solutions

WebSphereInterchange

Server migrationwizard

1

2 Run the Externalservice wizard toimport the connectorproject

3 Adapter migrationwizard

Run the Adaptermigration wizard toconvert WBI adapterartifacts into JCA-compliantartifacts for use withinIBM Business ProcessManager

Migrating applications from WebSphere InterChange ServerTo use Version 7.5.0.3 of WebSphere Adapter for Flat Files with applications fromWebSphere InterChange Server, you need to migrate the application artifacts andconvert them so that they can be deployed and run on IBM Business ProcessManager or WebSphere Enterprise Service Bus. Understanding this task at a highlevel helps you perform the steps that are needed to accomplish the task.

The following figure illustrates the flow of the migration task. The steps thatfollow the figure describe this task at a high level only. See the topics followingthis roadmap for the details on how to perform each of these steps.


Migrating applications from WebSphere InterChange Server

This task consists of the following steps:1. Run the WebSphere InterChange Server migration wizard.

The WebSphere InterChange Server migration wizard moves the applicationartifacts into IBM Integration Designer. The migrated adapter artifacts are notfully JCA-compliant at the completion of this task.

2. Verify that the WebSphere InterChange Server migration is successful.Review all messages from the Migration results window and take action ifrequired.

3. Consider the implications of using Version 7.5.0.3 of WebSphere Adapter forFlat Files.In addition to considerations for migrating WebSphere InterChange Serverapplications, you need to consider how Version 7.5.0.3 of WebSphere Adapterfor Flat Files works with the migrated applications. Some of the adapteroperations supported by WebSphere InterChange Server applications might besupported and implemented differently with Version 7.5.0.3 of the adapter.

4. Run the adapter migration wizard.Run the adapter migration wizard to update adapter-specific artifacts such asthe schemas and service definition files (.import, .export, and .wsdl files) foruse with Version 7.5.0.3 of the adapter.

Migration considerations for WebSphere Business Integrationadapters

By migrating to WebSphere Adapter for Flat Files Version 7.5.0.3, you have anadapter that is compliant with the Java Platform, Enterprise Edition (JEE)Connector Architecture (JCA) and designed specifically for service-orientedarchitecture.

Application artifacts

Before running the adapter migration wizard, use the WebSphere InterChangeServer migration wizard to generate the application artifacts for the WebSphereBusiness Integration adapter, including the business objects, maps, and

Figure 9. Roadmap for migrating applications from WebSphere InterChange Server


collaborations. Then you can run the adapter migration wizard to update theadapter-specific artifacts such as the schemas and service definition files (.import,.export, and .wsdl) so that they are suitably converted into a format that iscompliant with JCA.

Run the migration wizard in a test environment first

Because migrating from a WebSphere Business Integration adapter to WebSphereAdapter for Flat Files might require changes to the applications that use Version7.5.0.3 of WebSphere Adapter for Flat Files, always perform the migration in adevelopment environment first and test your applications before deploying theapplication to a production environment.

Migrating application artifacts from WebSphere InterChangeServer

To migrate the application artifacts into IBM Integration Designer, run theWebSphere InterChange Server migration wizard. The wizard imports and convertsmost of the artifacts into a format that is compatible with IBM Business ProcessManager or WebSphere Enterprise Service Bus.

Before you begin

Launch the WebSphere InterChange Server migration wizard from within IBMIntegration Designer to migrate the application artifacts from WebSphereInterChange Server format into artifacts that are compatible with IBM BusinessProcess Manager or WebSphere Enterprise Service Bus.

For information about how to prepare to migrate artifacts from WebSphereInterChange Server and for detailed instructions on performing the migration andverifying that the migration was successful, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/index.jsp?topic=/com.ibm.wbpm.wid.imuc.doc/topics/twics.html.

About this task

Running WebSphere InterChange Server migration wizard might not fully convertadapter-specific artifacts (such as service descriptors, service definitions, andbusiness objects) into IBM Business Process Manager or WebSphere EnterpriseService Bus compatible artifacts. To complete the migration of adapter-specificartifacts, run the adapter migration wizard after you have successfully run theWebSphere InterChange Server migration wizard.

Note: While you run the WebSphere InterChange Server migration wizard, ensurethat you set each connector in the repository to the same adapter version.

Results

The project and application artifacts are migrated and converted into IBM BusinessProcess Manager compatible artifacts.

What to do next

Run the adapter migration wizard to migrate the adapter-specific artifacts.


http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/index.jsp?topic=/com.ibm.wbpm.wid.imuc.doc/topics/twics.html



Migrating adapter-specific artifactsAfter a project is created for the artifacts in IBM Integration Designer, you canmigrate the project using the adapter migration wizard. The adapter migrationwizard updates adapter-specific artifacts such as the schemas and service definitionfiles (.import, .export, and .wsdl) for use with version 7.5.0.3 of the adapter. Whenyou finish running the adapter migration wizard, the migration is complete andyou can work in the project or deploy the module.

Before you begin

Before running the adapter migration wizard, do the following steps:v Review the information in “Migration considerations” on page 41.v Run the WebSphere InterChange Server migration wizard to migrate the project

and convert data objects for use with IBM Business Process Manager orWebSphere Enterprise Service Bus.

About this task

After migration is complete, the module will work only with Version 7.5.0.3 ofyour adapter.

To perform the migration in IBM Integration Designer, complete the followingsteps.

Procedure1. Import the PI (project interchange) file for an existing project into the

workspace.2. When projects are created in an earlier version of IBM Integration Designer,

the Workspace Migration wizard starts automatically and selects the projectsto migrate. Follow the wizard and complete the workspace migration. Formore information, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.imuc.doc/topics/tmigsrcart.html.

3. Change to the Java EE perspective.4. Right-click the connector project and select Migrate connector project.

You can also launch the adapter migration wizard by using the right-clickoption and selecting the module project in the Java EE perspective andselecting Migrate adapter artifacts.

Note:

If the adapter type (for example, CICS/IMS adapter) is not supported by themigration wizard, the Migrate connector project and Migrate adapterartifacts menus are not available for selection. If the adapter project is of thelatest version and the module projects referencing this adapter project are alsoof the latest version, these menus are disabled.When you launch the migration wizard from the connector project while inthe Java EE perspective, by default all the dependent artifact projects areselected. If you do not select a dependent artifact project, that project is notmigrated.

5. In the Select Projects window, perform the following steps:a. The Source connector field displays the name of the connector project that

you are migrating. Select the source project from the list.




b. The Target connector field displays the name of the connector to whichyou are migrating. If you are working with more than one adapter version,this list displays the names of all the compatible connectors. Select theconnector to which you want to migrate.

c. The Target version field displays the version corresponding to the targetconnector you selected in the previous step.

d. The Dependent artifacts project area lists the adapter artifacts that aremigrated.

e. Review the tasks and warnings presented on the welcome page, and clickNext. A warning window is displayed with the message, “The propertiesthat are not supported in the version of the target adapter are removedduring the migration.”

f. Click OK.6. In the Review Changes window, review the migration changes that occur in

each of the artifacts that you are migrating. To view the details, expand eachnode by clicking the + sign.



Before performing the migration process, the wizard backs up all projectsaffected by the migration. The projects are backed up to a temporary folderwithin the workspace. If the migration fails for any reason, or if you decide tocancel the migration before it completes, the wizard deletes the modifiedprojects and replaces them with the projects stored in the temporary folder.


8. Select Project > Clean, to refresh and rebuild the workspace for the changes totake effect.

9. On successful migration, all backed up projects are deleted. Remove the Syncinbound flow manually as this flow is not used by the adapter. From themigrated project, select the Input_Sync inbound flow, right-click, and selectDelete.

10. If you are migrating an EAR file, create a new EAR file with the migratedadapter and artifacts, and deploy it to IBM Business Process Manager orWebSphere Enterprise Service Bus. For information about exporting anddeploying an EAR file, see “Deploying the module for production” on page115.

Results

The project is migrated to Version 7.5.0.3. You do not need to run the externalservice wizard after exiting the adapter migration wizard.

Changes to the import, export, and WSDL files after migrationWhen the WebSphere InterChange Server migration wizard moves the applicationartifacts into IBM Integration Designer, changes made are reflected in the servicedefinition files: the import, export, and WSDL files.

The migrated adapter artifacts are not fully JCA-compliant at the completion ofthis task. You can complete the migration of the adapter-specific artifacts (such asservice descriptors, service definitions, and business objects) to a JCA compatibleformat by running the adapter migration wizard.

Changes to the import file

During migration, the affected module artifacts are migrated to an import file. Theexisting JMS Binding property is changed to the EIS Binding property in theimport file. The other property details added in the import file include informationabout the data binding configuration, changes to the connection information in theManaged Connection Factory properties, and several new method bindings.


Changes to the export file

During migration, the affected module artifacts are migrated to an export file. Theexisting JMS Binding property is changed to the EIS Binding property in the exportfile. The other property details added in the export file include information aboutthe data binding configuration, changes to the connection information in theActivation Specification properties, and several new method bindings.

Changes to the WSDL file after migration

During migration, the affected module artifacts are migrated to correspondingWSDL files that include Flat File specific service description WSDL artifacts. Theservice description files become JCA compatible. The WSDL files have an inputand output type for each operation. Both the inbound and outbound operationswork on their specific input types to produce corresponding output types after theoperations are performed. The outbound operations generated during migrationare shown in the following table:

Operations Input Output

Create CustomerWrapperBG CreateResponse

Append CustomerWrapperBG AppendResponse

Overwrite CustomerWrapperBG OverwriteReponse

Note:

v When you migrate multiple top level inbound business objects in the project,only the first top-level business object inbound feature works correctly. For theother top level inbound business object to work correctly, you must manuallymodify the "emit + [verb name] + after image + [business object name]" methodin the Input_Processing.java and Input_Async_Processing.java class to call thecorrect destination services.

v The WebSphere Business Integration Adapter for JText properties that are eithernot valid or not supported by WebSphere Adapter for Flat Files are removedfrom the migrated artifacts.


Chapter 3. Samples and tutorials

To help you use WebSphere Adapters, samples and tutorials are available from theBusiness Process Management Samples and Tutorials website.

You can access the samples and tutorials in either of the following ways:v From the welcome page of IBM Integration Designer, click Go to Samples and

Tutorials. In the Samples and Tutorials pane, under More samples, clickRetrieve. Browse the displayed categories to make your selection.

v From the Business Process Management Samples and Tutorials website:http://bpmwikilogin.blueworkslive.com/accounts/login/.


http://bpmwikilogin.blueworkslive.com/accounts/login/

Chapter 4. Configuring the module for deployment

To configure the adapter so that it can be deployed on IBM Business ProcessManager or WebSphere Enterprise Service Bus, use IBM Integration Designer tocreate a module, which is exported as an EAR file when you deploy the adapter.You then specify the business objects you want to build and the system on whichyou want to build them.

Road map for configuring the moduleBefore you can use WebSphere Adapter for Flat Files in a runtime environment,you must configure the module. Understanding this task at a high level helps youperform the steps that are needed to accomplish the task.

You configure the module for WebSphere Adapter for Flat Files by using IBMIntegration Designer. The following figure illustrates the flow of the configurationtask, and the steps that follow the figure describe this task at a high level only. Forthe details about how to perform each of these steps, see the topics following thisroad map.

Configuring the module

This task consists of the following steps, which are described at a high level.

Note: The information given in the steps assume that you are using user-definedbusiness objects that require data transformation. If using generic business objects,

Figure 10. Road map for configuring the module


that do not require data transformation, some of the following steps are ignored.For example, you do not need to select a data binding and a data handler.1. Create a module in IBM Integration Designer. You create business objects in the

module.2. Define the business objects that to be used by the project.3. Create a project, which is used to organize the files associated with the adapter

using the external service wizard in IBM Integration Designer.4. Build business services by running the external service wizard from IBM

Integration Designer, then performing the following steps:a. Specify the following deployment and runtime properties:

v Connection propertiesv Security propertiesv Deployment optionsv Function selector - Inbound only

b. Select a data type and name the operation associated with this data type.For each operation, specify the following information:v The operation kind. For example, Create, Append, Exists.v Specify if the operation is pass-through or user-defined.

c. Select the data binding. Each data type has an equivalent data binding usedto read the fields in a business object and fill the corresponding fields in afile.

d. Select the data handler that to perform the conversions between a businessobject and a native format.

e. Specify interaction specification property values and generate artifacts. Theoutput from running the external service wizard is saved to a businessintegration module, which contains the business object or objects, and theimport or export file.

Creating the required local foldersBefore you create inbound or outbound modules, you must create folders on thelocal file system for events and output. You can optionally create folders forstaging and archiving.

Before you create inbound or outbound modules, you must specify the eventdirectory and the output directory on the Service Configuration Properties screenof the external service wizard. You can also create a staging directory and anarchive directory, but these directories are not required.v The event directory stores events for inbound processing. The adapter polls this

folder at regular intervals and sends any found events, in the form of businessobjects, to the server.

v The output directory is used by the adapter to write the final output files forCreate, Append, and Overwrite operations during outbound processing.

v The staging directory is a temporary directory where the adapter writes theinitial output files during Create and Overwrite operations, to avoid writeconflicts. The output files are then renamed and copied to the output directory.

v The archive directory is a directory where the adapter stores processed eventfiles.

Instead of specifying the names of these directories when you run the externalservice wizard, you can use WebSphere Application Server environment variables.


Creating the moduleYou create the module in IBM Integration Designer. The module allows you todefine business objects that are used by the project.

About this task

Start the external service wizard and follow this procedure to create a module.

Procedure1. If IBM Integration Designer is not currently running, start it now.

a. Click Start > Programs > IBM > IBM Integration Designer > IBMIntegration Designer 8.0.

b. If you are prompted to specify a workspace, either accept the default valueor select another workspace.The workspace is a directory where IBM Integration Designer stores yourproject.

c. Optional: When the IBM Integration Designer window is displayed, clickGo to the Business Integration perspective.

2. Right-click inside the Business Integration section of the IBM IntegrationDesigner window. Click New > Module.

3. Type a new Module Name in the New Module window. Leave the otheroptions (Use default location and Open module assembly diagram) checked.

4. Click Finish.

Results

A new module is listed in the Business Integration window.

Figure 11. Business Integration section of the window

Chapter 4. Configuring the module for deployment 59

What to do next

Create a project, which is used to organize the files associated with the adapter.

Defining WebSphere Application Server environment variablesUse the Process Administrative Console of IBM Business Process Manager orWebSphere Enterprise Service Bus to define WebSphere Application Serverenvironment variables.

Before you begin

About this task

To define a WebSphere Application Server environment variable, use the followingprocedure.

Procedure1. Start the Process Administrative Console.2. Select Environment > WebSphere Variables.3. Select the scope for the environment variable. The scope specifies the level at

which the resource definition is visible on the Process Administrative Consolepanel. The possible values are server, node, and cell. In this example,Cell=widCell is used.

4. Click New and provide a name and a value for the environment variable. Thename is the symbolic name that represents a physical path. The value is theabsolute path that the variable represents. In this example, the name is

Figure 12. Setting the scope for the environment variable


EVENT_DIRECTORY and the value is C:/flatfile/event. You can use theDescription field, which is optional, to describe the purpose of the variable.

5. Click OK and save the changes.

Results

An environment variable called EVENT_DIRECTORY is defined, with the valueC:flatfile/event and a scope of Cell=widCell. You can use it in the externalservice wizard whenever you need to specify the event directory.

Figure 13. Providing a name and a value for the environment variable


What to do next


Defining business objectsPredefine the business objects in IBM Integration Designer to be used by theproject that you create in the next topic.

About this task

To predefine new business objects using the business object editor, complete thefollowing steps.

Procedure1. Expand the new module located inside of the Business Integration section of

the IBM Integration Designer window.2. Right-click the Data Types folder and select New > Business Object.3. Type a new Name in the Business Object window. For example, Customer to

create a customer business object.4. Click Finish. The new business object is added to the Data Types folder.5. Click the Add a field to a business object icon and add the necessary fields to

the business object.

Figure 14. The new environment variable EVENT_DIRECTORY displayed in the WebSphereVariables window


6. Click the Save icon.7. Repeat the previous steps for each business object that you want to create.

Results

The new business objects are defined.

What to do next


Converting business objects to COBOL copybook files duringoutbound processing

Use the external service wizard in IBM Integration Designer to generate businessobject definitions from a COBOL program source file. These business objectdefinitions are used during outbound processing.

Before you begin

Before you perform this task, make sure that:1. You have created a module in IBM Integration Designer.2. The COBOL program source file (.ccp file) is in a local directory on your

workstation.3. If you are going to generate a wrapper business object definition, you have

imported the adapter RAR file into your workspace.

Figure 15. Add Business object fields icon


About this task

Use the external service wizard to generate a business object definition for aCOBOL program source file. After you generate the business object definition, youcan optionally rerun the external service wizard to generate a wrapper businessobject definition from the generated business object.

Procedure1. Generate the business object definition for the COBOL program source file.

a. In the Business Integration section of the window, right-click the moduleand select New > New Business Object From External Data.

b. In the Select an Input Source window, select Languages -> COBOL. ClickNext.

c. In the Provide Details for the Mapping window, make sure the Selectedmapping value is COBOL to Business Object. Click Browse and select the.ccp file. For example, taderc99.ccp can be the name of the .ccp file. ClickNext.

d. In the Select Data Structures window, click Find. The new business object,called DFHCOMMAREA is displayed.

e. Select the business object DFHCOMMAREA and click Next.f. In the Generate Business Objects window, specify the Module, Folder,

Name. Select Generate style from the list and click Finish.

A business object, called DFHCOMMAREA is created in the module.

Figure 16. The Select an Input Source window


2. Optional: Generate a wrapper business object definition. Wrapper businessobject definitions wrap existing business object definitions with additionalfunction. The option to generate wrapper business object definitions isdisplayed only when the adapter RAR file is imported into the workspace.a. In the Business Integration section of the window, right-click the module

and select New > New Business Object From External Data.b. In the Select an Input Source window, expand Adapters and select Flat File.

Click Next.c. In the Specify the Location window, select the module in the Module field

and click Next.d. In the Specify the Properties window, click Browse and select the business

object created in Step 1. For example, DFHCOMMAREA for the data type.e. Optional: To generate a business graph, select the Generate business graph

for each business object check box. To generate a retrieve wrapper, selectthe Generate retrieve container to retrieve multiple business objects checkbox.

f. Click Finish.

A wrapper business object and a business graph, calledDFHCOMMAREAWrapper and DFHCOMMAREAWrapperBG as shown in thefigure, are listed for the current module in the Business Integration window. Ifwrappers for retrieve are selected, then business object calledDFHCOMMAREARetrieveWrapper and a business graph calledDFHCOMMAREARetrieveWrapperBG are also listed for the current module in

Figure 17. The Specify the Properties window


the Business Integration window.

3. Generate the required artifacts for the COBOL copybook outbound module.This example shows the configuration for a Create operation.a. In the Business Integration section of the window, right-click the module

and select New > External Service.b. Select Adapters and click Next.c. In the Select an Adapter window, select IBM WebSphere Adapter for Flat

Files (IBM : 7.5.0.2) adapter and click the CWYFF_FlatFile connectorproject. Click Next.

d. In the Select the Processing Direction window, select Outbound.e. Click Next.f. In the Specify the Security and Configuration Properties window, from the

Data format options list, select Use COBOL, C or PL/I data format option.Click Next.

Note: This option is not a data binding, but a data binding generator. Thetool generates the appropriate data binding code for you in the currentmodule.

Figure 18. The wrapper business object and the business graph listed in the BusinessIntegration window


g. In the Add, Edit, or Remove Operations window, click Add.h. In the Specify the I/O Properties window, select Create in the Operation

kind field. For Retrieve operation, select Retrieve.i. Select User-defined type for the Data type for the operation field. Click

Next.j. Browse for the input type (DFHCOMMAREA, DFHCOMMAREAWrapper, or

DFHCOMMAREAWrapperBG) and click OK. For Retrieve operation, browsefor the appropriate input type (DFHCOMMAREA,DFHCOMMAREARetrieveWrapper, orDFHCOMMAREARetrieveWrapperBG).

Figure 19. The Specify the Security and Configuration Properties window


k. Click Next and complete the external service wizard.

The data bindings used by COBOL copybook, WSDL files, import files, andother artifacts are generated. See the Project Explorer window for the generateddata binding classes.

Results

A business object, a wrapper business object, and a business graph are created forthe COBOL program source file for the outbound module. Artifacts are generated

Figure 20. The Data Type Selection window

Figure 21. Data bindings used by COBOL copybook, WSDL files, import files, and otherartifacts


for an outbound Create operation that uses COBOL copybook data binding. Thismodule can be deployed on IBM Business Process Manager or WebSphereEnterprise Service Bus and tested for a Create operation.

Note: To generate artifacts for other supported operations (Append andOverwrite), follow the same steps, beginning with Step 3h.

What to do next

Deploy the module.

Converting COBOL copybook files to business objects during inboundprocessing

Use the external service wizard in IBM Integration Designer to generate businessobject definitions from a COBOL program source file. These business objectdefinitions are used during inbound processing.

Before you begin

Before you perform this task, make sure that:1. You created a module in IBM Integration Designer.2. The COBOL program source file (.ccp file) is in a local directory on your

workstation.3. You have created a local event directory.4. If you are going to generate a wrapper business object definition, you have

imported the adapter RAR file into your workspace.

About this task

Use the external service wizard to generate a business object definition for aCOBOL program source file. After you generate the business object definition, youcan optionally rerun the external service wizard to generate a wrapper businessobject definition from the generated business object.

Procedure1. Generate the business object definition for the COBOL program source file.

a. In the Business Integration section of the window, right-click the moduleand select New > New Business Object From External Data.

b. In the Select an Input Source window, select Languages -> COBOL. ClickNext.


c. In the Provide Details for the Mapping window, make sure the Selectedmapping value is COBOL to Business Object. Click Browse and select the.ccp file. For example, taderc99.ccp can be the name of the .ccp file. ClickNext.

d. In the Select Data Structures window, click Find. The new business object,called DFHCOMMAREA is displayed.

e. Select DFHCOMMAREA and click Next.f. In the Generate Business Objects window, specify the Module, Folder,

Name. Select Generate style from the list and click Finish.

A business object, called DFHCOMMAREA in the figure, is created in themodule.

2. Optional: Generate a wrapper business object definition. Wrapper businessobject definitions wrap existing business object definitions with additionalfunction. The option to generate wrapper business object definitions isdisplayed only when the adapter RAR file is imported into the workspace.a. In the Business Integration section of the window, right-click the module

and select New > New Business Object From External Data.b. In the Select an Input Source window, expand Adapters and select Flat File.

Click Next.c. In the Specify the Location window, select the module in the Module field

and click Next.d. In the Specify the Properties window, click Browse and select the business

object created in Step 1, for example, DFHCOMMAREA, for the data type.

Figure 22. The Select an Input Source window


e. Optional: To generate a business graph, select the Generate business graphfor each business object check box.

f. Click Finish.

A wrapper business object and a business graph, calledDFHCOMMAREAWrapper and DFHCOMMAREAWrapperBG as shown in thefigure, are listed for the current module in the Business Integration window.

3. Generate the required artifacts for the COBOL copybook inbound module.

Figure 23. The Specify the Properties window

Figure 24. The wrapper business object and the business graph listed in the BusinessIntegration window


a. In the Business Integration section of the window, right-click the moduleand select New > External Service.

b. Select Adapters and click Next.c. In the Select an Adapter window, select IBM WebSphere Adapter for Flat

Files (IBM : 7.5.0.2) adapter and click the CWYFF_FlatFile connectorproject. Click Next.

d. In the Select the Processing Direction window, select Inbound and clickNext.

e. In the Event directory field, click Browse and select the event directory.f. From the Function selector options list, select the default value.g. From the Data format options list, select the Use COBOL, C or PL/I data

format option. Click Next.

Note: This option is not a data binding, but a data binding generator. Thetool generates the appropriate data binding code for you in the currentmodule.

h. Optional: If the input file contains multiple COBOL program source files,you can enable file splitting by size or by delimiter. To enable file splitting,

Figure 25. The Specify the Security and Configuration Properties window


click Advanced, and then click Additional configuration. To enable filesplitting by size, you must provide the correct length of each COBOLprogram source file. You can either open the business object in a text editorand add up the maximum lengths, or look for the content size ofDFHCOMMAREA at the top of the file. See “Specify criteria to split filecontent” on page 210.

i. In the Add, Edit, or Remove Operations window, click Add.j. In Specify the I/O Properties window, select User-defined type for the Data

type for the operation field. Click Next.k. For the input type, click Browse and select the generated business object

(DFHCOMMAREA). Click OK.

l. Click Finish.m. Click Next, and then Finish.

The data bindings used by COBOL copybook, WSDL files, export files, andother artifacts are generated. See the Project Explorer window for the generateddata binding classes.

Figure 26. Selecting the input type


Results

A business object, a wrapper business object, and a business graph are created forthe COBOL program source file for the inbound module. Artifacts are generatedfor an inbound operation that uses COBOL copybook data binding. This modulecan be deployed on IBM Business Process Manager or WebSphere EnterpriseService Bus and tested for an inbound operation.

What to do next

Deploy the module.

Creating a simple service with the adapter pattern wizardAdapter patterns provide a quick and easy way of creating a simple service withan adapter.

Before you begin

A module called RetrieveAFileModule and a business object called Customer isalready created. If you are using WebSphere Application Server environmentvariables to specify local files and directories, you defined them using the IBMBusiness Process Manager Process Administrative Console.

About this task

The following adapter patterns are available for the WebSphere Adapter for FlatFiles:

Figure 27. Data bindings used by COBOL copybook, WSDL files, export files, and otherartifacts


Table 10. Adapter patterns

Adapter pattern Description

Inbound Flat File pattern The Flat File inbound pattern creates a service that retrieves afile in a specific directory on the local file system. If the file isnot in an XML format, you can specify a data handler thattransforms from the file content format to business objects. Thefile content can be split if the content contains multiple copies ofthe data structure for processing.

Outbound Flat Filepattern

The Flat File outbound pattern creates a service that stores datain a file in a specific directory on the local file system. If therequired output format is not an XML format, you can specify adata handler that transforms the business object to the filecontent format.

In this example, we create a Flat File inbound service that receives a file from thefile system for processing. The completed service in this example reads in a fileand splits the contents into separate files based on a delimiter.

Complete the following steps to create a service with the adapter pattern wizard:

Procedure1. Right-click RetrieveAFileModule within the Business Integration section of the

IBM Integration Designer window and select New > External Service. TheSelect the Service Type or Registry window opens.

2. Select Simple: Create an inbound Flat File service to read from a local fileand click Next.


3. In the Flat File Service window, change the Name to something meaningfulsuch as FlatFileInboundInterface and click Next.

4. In the Business object and directory window, click Browse and navigate to theCustomer business object.

5. Specify the directory where you placed the input file, in this case theFFInboundEvents directory, and click Next. To use a WebSphere ApplicationServer environment variable for this value, specify the name of the variable inbraces, preceded by a $ symbol. For example: ${FFINBOUNDEVENTS}.

Figure 28. Select the Service Type or Registry window


6. In the Input file format and file content split option window, accept the defaultXML input file format or select Other and specify a data handler to transformthe data from your native format to the business object format.

7. Select Split file content by delimiter and enter your delimiter, which is####;\r\n in this example. Click Next.

Figure 29. Business object and directory window


8. In the Archive directory and wrapper business object window, specify the Localarchive directory, which is FFInboundArchive in this example. To use aWebSphere Application Server environment variable for this value, specify thename of the variable in braces, preceded by a $ symbol. For example:${FFINBOUNDARCHIVE}. Select Use a wrapper business object to containadditional input file information check box, if you want to include theadapter-specific information. Click Finish.

Results

The inbound service is created, which includes the following artifacts:

Table 11. Artifacts and their descriptions

Artifact Name Description

Export FlatFileInboundInterface The export exposes themodule externally, in thiscase, to the WebSphereAdapter for Flat Files.

Figure 30. Input file format and file content split option window


Table 11. Artifacts and their descriptions (continued)

Artifact Name Description

Business objects Customer, CustomerWrapper The Customer businessobject contains the fields forcustomer data such as name,address, city, and state. TheCustomerWrapper businessobject contains additionalfields for adapter-specificinformation.

Interface FlatFileInboundInterface This interface contains theoperation that can beinvoked.

Operation emitCustomerInput emitCustomerInput is theonly operation in theinterface.

Starting the external service wizardTo create and deploy a module, you start the external service wizard in IBMIntegration Designer. The wizard creates a project that is used to organize the filesassociated with the module.

About this task

Start the external service wizard to create a project for the adapter in IBMIntegration Designer. If you have an existing project, you can select it instead ofhaving the wizard create one.

To start the external service wizard and create a project, use the followingprocedure.

Procedure1. To start the external service wizard, go to the Business Integration perspective

of IBM Integration Designer, and then click File > New > External Service.2. In the New external service window, make sure Adapters is selected, and click

Next.3. From the Select an Enterprise Service Resource Adapter window, create a

project or select an existing project.v To create a project, perform the following steps:

a. Select IBM WebSphere Adapter for Flat Files and click Next.b. In the Connector Import window, provide another name for the project

(to use a name other than CWYFF_FlatFile), select the server (forexample, IBM Business Process Manager) and click Next.

v To select an existing project, perform the following steps:a. Expand IBM WebSphere Adapter for Flat Files.b. Select a project.

For example, if you have an existing project named CWYFF_FlatFiles, youcan expand IBM WebSphere Adapter for Flat Files and selectCWYFF_FlatFile.

c. Click Next.


Results

A new project is created and is listed in the Business Integration window.

What to do next

Configuring the module for outbound processingTo configure a module to use the adapter for outbound processing, use the externalservice wizard in IBM Integration Designer to build business services, specify datatransformation processing, and generate the business object definitions and relatedartifacts.

Setting deployment and runtime propertiesAfter you have decided whether your module is to be used for outbound orinbound communication with the local file system, you must configure themanaged connection factory properties so that the adapter can make theconnection between the module and the local file system.

Before you begin

Before you can set the properties in this section, you must create your adaptermodule. It is displayed in IBM Integration Designer below the adapter project. Formore information about creating the adapter project, see “Starting the externalservice wizard” on page 79.

About this task

To set deployment and runtime properties, follow this procedure. For moreinformation about the properties in this topic, see “Managed connection factoryproperties” on page 177.

Procedure1. In the Select the Processing Direction window, select Outbound and click Next.


2. In the Specify the Security and Configuration Properties window, in the Deployconnector project field, select With module for use by single application.

3. Define the Connection properties for your module. For more details on theproperties found on this window, see the “Managed connection factoryproperties” on page 177 topic.

Figure 31. Selecting inbound or outbound processing in the external service wizard


4. In the Output directory field, specify the directory that is to be used for all theoutbound operations. For example, the directory where the file is to be createdduring the Create operation.

5. Click Advanced and expand the Logging and tracing, Additionalconfiguration, and Bidi properties sections to specify additional properties.v Logging and tracing

a. If you have multiple instances of the adapter, enter a value in theAdapter ID that is unique for this instance. For more information, see“Adapter ID (AdapterID)” on page 178.

b. You can select the Disguise user data as 'XXX' in log and trace filescheck box to prevent sensitive user data from being written to log andtrace files. For more information, see “Disguise user data as "XXX" in logand trace files (HideConfidentialTrace) ” on page 179.

v Additional configuration

a. In the Default target file name field, specify the name of the file that iscreated in the output directory, or a WebSphere Application Serverenvironment variable that represents this file. For more information, see“Default target file name” on page 180.

b. In the Staging directory field, specify the full path name of thetemporary directory where the adapter writes the initial output files forCreate and Overwrite operations during outbound processing, oraWebSphere Application Server environment variable that represents thisdirectory. For more information, see “Staging directory” on page 182.

Figure 32. Setting the security and configuration properties


c. In the Sequence file field, specify the full path name of the file wheresequences are stored during outbound Create operations, or a WebSphereApplication Server environment variable that represents this file. Formore information, see “Sequence file” on page 181.

d. Select the Generate a unique file check box to enable the adapter togenerate unique file names. For more information, see “Generate aunique file” on page 188.– In the Prefix for the unique file field, specify a predefined prefix to

the unique file name. For more information, see “Prefix for the uniquefile name” on page 180.

– In the Suffix (extension) for the unique file field, specify a predefinedextension to the unique file name. For more information, see “Suffixfor the unique file name” on page 183.

v Bidi properties

a. Select the Bidi transformation check box to specify bidirectional format.For more information about setting the Bidi properties, refer to the“Globalization” on page 217 section.

6. Optional: If you want to specify the log file output location or define the levelof logging for this module, select the Change logging properties for wizardcheck box. For information about setting logging levels, see the section aboutconfiguring logging properties in the Chapter 8, “Troubleshooting andsupport,” on page 149 topic.

7. Click Next.

Results

The adapter saves the connection properties.

What to do next

Select a data type for the module and name the operation associated with thechosen data type.

Selecting the operation and data typeUse the external service wizard to select the outbound operation to accessfunctions on the local file system and the data type to be used with it. Theoperations supported are Create, Append, Overwrite, Delete, Exists, List, andRetrieve. The external service wizard gives you a choice of three data types:generic FlatFile business object, generic FlatFile business object with businessgraph, and user-defined type. Each data type corresponds to a business objectstructure.

Before you begin

You must specify the connection properties for the adapter to connect to the localfile system before you can complete the steps given here.

About this task

To select an outbound operation and the data type to be used with it, follow thisprocedure.


Procedure1. In the Add, Edit, or Remove Operations window, click Add to create an

operation.2. In the Specify the I/O Properties window, select an outbound operation from

the Operation kind list.3. In the Data type for the operation list, select a data type. Click Next. In this

example, the user-defined data type is selected. For Delete, Retrieve, Exists, andList operations, only the generic data type (generic FlatFile business object orgeneric FlatFile business object with business graph) is supported as input. Ifyou select user-defined type with one of these operations, you must provide auser-defined data binding to support it.For Create, Append, and Overwrite operations, the choices are user-definedtype, generic FlatFile business object, and generic FlatFile business object withbusiness graph. For more information about data types, see, “Business objectstructures” on page 165.

4. Optional: Select the Enable response type for the operation check box forCreate, Append, and Overwrite operations, if you want the file name returnedor if you are generating a unique file name or enabled file sequencing. Bydefault, the Enable response type for the operation check box is selected forthe Exists, List, and Retrieve operations because output is required for theseoperations. For the Delete operation, select the Enable response type for theoperation check box if you want a value of true returned when the operationis successful. Click Next.

5. In the Specify the I/O Properties window, type an Operation name. Name theoperation something meaningful.

Note: Names cannot contain spaces.

Figure 33. Naming the operation and specifying the input data type


By default, the data type for the output is specified as CreateResponse orCreateResponseBG.

6. Select the Input type. Click Browse and select the business object you createdearlier.

Note: If you specified a generic data type such as generic FlatFile businessobject or generic FlatFile business object with business graph, the Input type isspecified by default to FlatFile or FlatFileBG.

Results

A data type is defined for the module and the operation associated with this datatype is named.

What to do next

Add and configure a data binding to be used with the module.

Configuring the data bindingEach data type has an equivalent data binding that is used to read the fields in abusiness object and fill the corresponding fields in the file. In the external servicewizard, you add a data binding to your module and configure it to correspondwith your data type. This way, the adapter knows how to populate the fields inthe file with the information it receives in the business object.

Before you begin

You must select an operation and the data type to be used with it.

About this task

To add and configure a data binding for the module, follow this procedure.

Note: Data bindings can be configured before running the external service wizardusing IBM Integration Designer. To do this configuration, select New > ConfigureBinding Resource in IBM Integration Designer and complete the data bindingwindows described in this documentation.

Procedure1. In the Specify the I/O Properties window, select either the Use suggested data

format 'FlatFileBaseDataBinding' or the Use a data format configurationoption from the Data format options list.

2. If you select the Use a data format configuration option, click Select toconfigure the data binding.

3. In the Select a Data Format Transformation window, select the Use existingdata format transformation from the list option. From the list, selectFlatFileBaseDataBinding. To configure a custom data binding, select the Selectyour custom data format transformation from the workspace option. ClickNext.


4. In Specify the Data Transformation Properties window, click Next.

Note: This window is used for configuring the data handlers.5. In Configure a New Data Transformation window, provide the data binding

configuration details.a. In the Configure a New Data Transformation window, the Module defaults

to the module name you typed earlier in the external service. If you want tocreate a data binding for a different module, select New to create a module.

b. If you want to select a new folder for the artifact, click Browse and select anew folder location.

c. Type a Name for the data binding configuration. Click Finish. The databinding name is populated in the Specify the I/O Properties window.

Results

A data binding is configured for use with the module.

What to do next

Select the data handler configuration.

Figure 34. Selecting the data binding


Configuring data handlersData handlers perform the conversions between a business object and a nativeformat. The configuration in this topic is shown using the XML data handler. Forcomma-separated values (CSV) file format files, you must select the Delimited datahandler.

Before you begin

You must create a data binding before you specify the data handlers for themodule. Also, you must have predefined business objects using IBM IntegrationDesigner Business Object Editor. If you stop the wizard here to create businessobjects, you must start the wizard steps from the beginning.

Note: You can configure data handlers before running the external service wizardusing IBM Integration Designer. To do this configuration, select New > ConfigureBinding Resource in IBM Integration Designer and complete the data handlerwindows described in this documentation.

About this task

To specify data handlers, follow this procedure.

Procedure1. In the Specify the Data Transformation Properties window, ensure that

DataHandler is selected in the Binding type field.2. In the Configured data handler field, click Select. Complete the following steps

to create and configure a data handler.a. In the Select a Data Format Transformation window, click Use existing data

format transformation from the list option. Select XML data handler fromthe list and click Next. To work with data files (CSV) that uses comma toseparate the fields of data, select Delimited. For more information aboutworking with delimited data files, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5mx/topic/com.ibm.wbpm.wid.integ.doc/topics/rdelimitedcvs.html.


http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5mx/topic/com.ibm.wbpm.wid.integ.doc/topics/rdelimitedcvs.html



3. In the Specify the Data Transformation Properties window, specify theEncoding. The default is UTF-8. Click Next.

Note: If Delimited option is selected, the Specify the Data TransformationProperties window provides the delimiter data handler configuration fields.

Figure 35. Creating a data handler configuration


4. In the Configure a New Data Transformation window, specify the Module,Namespace, Folder, and Name for the data handler configuration. Click Finish.

Figure 36. Specifying the encoding for the data handler configuration


5. Click Finish. The configured data handler is populated in the Specify the DataTransformation Properties window.

Results

Data handlers are created.

What to do next

Specify interaction specification properties and generate artifacts for the module.

Setting interaction properties and generating the serviceInteraction properties are optional. If you choose to set them, the values youspecify appear as defaults in all parent business objects generated by the externalservice wizard. While creating artifacts for the module, the adapter generates animport file. The import file contains the operation for the top-level business object.

Figure 37. Specifying a name for the data handler configuration


Before you begin

To set interaction specification properties and generate artifacts for your module,you must have already configured data bindings and selected business objects.

About this task

To set interaction specification properties and generate artifacts, follow thisprocedure. For more information about interaction specification properties, see the“Interaction specification properties” on page 185 topic.

Procedure1. In the Add, Edit, or Remove Operations window, click Advanced.2. In the Additional configuration section, type values for different interaction

specification properties. Click Next.

Figure 38. Naming the service


3. In the Operations window, click Next. In the Specify the Name and Locationwindow, type a name for the interface. This name displays in the IBMIntegration Designer assembly diagram. Click Finish.

4.

Results

The IBM Integration Designer generates the service and an import. The outboundartifacts that are created are visible in the IBM Integration Designer ProjectExplorer under your module.

What to do next

Deploy the module.

Figure 39. Naming the service


Configuring the module for inbound processingTo configure a module to use the adapter for inbound processing, use the externalservice wizard in IBM Integration Designer to build business services, specify datatransformation processing, and generate business object definitions and relatedartifacts.

Setting deployment and runtime propertiesAfter you have decided whether your module is to be used for outbound orinbound communication with the enterprise information system (local file system),you must configure the activation specification properties, which hold the inboundevent processing configuration information for the export.

Before you begin

Before you can set the properties in this section, you must create your adaptermodule. It is displayed in IBM Integration Designer below the adapter project. Formore information about creating the adapter project, see “Starting the externalservice wizard” on page 79.

About this task

To set the activation specification properties, follow this procedure. For moreinformation about the properties in this topic, see “Activation specificationproperties” on page 196.

Procedure1. In the Select the Processing Direction window, select Inbound and click Next.


2. In the Specify the Security and Configuration Properties window, in the Deployconnector project field, select With module for use by single application.

3. In the Specify the Security and Configuration Properties window, define theactivation specification properties for your module. For more details on theproperties found on this window, see “Activation specification properties” onpage 196.

Figure 40. Selecting inbound or outbound in the external service wizard


4. In the Event directory field, specify the directory in the local file system wherethe event files are stored.

5. Click Advanced and expand the Event polling configuration, Event deliveryconfiguration, Event persistence configuration, AdditionalconfigurationCluster deployment settings, File archiving configuration, Bidiproperties, and Logging and tracing sections to specify values as needed.v Event polling configuration

a. In the Interval between polling periods (milliseconds) field, type thetime in milliseconds, that the adapter waits between polling periods. Formore information about the property, see “Interval between pollingperiods (PollPeriod)” on page 206.

b. In the Maximum events in polling period field, type the number ofevents to deliver in each polling period. For more information about theproperty, see “Maximum events in polling period (PollQuantity)” on page206.

c. In the Time between retries in case of case of system connection failure(in milliseconds) field, type the time in milliseconds, that the adapterwaits before trying to connect after a connection failure during polling.

Figure 41. Setting the connection properties


For more information, see “Time between retries in case of systemconnection failure (RetryInterval)” on page 210.

d. In the Maximum number of retries in case of system connection failurefield, type the number of times the adapter tries again the connectionbefore reporting a polling error. For more information, see “Maximumnumber of retries in case of system connection failure (RetryLimit)” onpage 207.

e. If you want the adapter to stop if polling errors occur, select the Stop theadapter when an error is encountered while polling check box. If youdo not select this option, the adapter logs an exception but continues torun. For more information, see “Stop the adapter when an error isencountered while polling (StopPollingOnError)” on page 212.

f. Select Retry EIS connection on startup. If you select this property, theadapter continues trying to connect to a system to which it failed toconnect when starting. For more information, see “Retry EIS connectionon startup (RetryConnectionOnStartup)” on page 210.

g. Select the calendar based scheduling option to create calendar basedpolling for inbound activities. You can schedule your business activities,when you create a new calendar in IBM Integration Designer. The optionof working with the calendar based scheduling feature is only possiblewith IBM Integration Designer as the tooling environment. The followingfigure helps you to schedule a calendar polling option.

You can either select a blank calendar or create a new calendar for amodule or library.

Note: When you select a blank calendar, you will not be able to setpredefined time intervals. You have to define your time intervals. Whenyou create a calendar using a predefined template, you can define timeintervals for each template.– To select an existing calendar for a module or library, click Browse. In

the Select a Business Calendar window, you can search for existingcalendar files (*cal) in the IBM Integration Designer workspace.1) In the Filter by name field, type the calendar name or name

pattern. The calenders matching the pattern are displayed in theMatching business calendars area.

2) Select a calendar and click OK to return to the external servicewizard.

– To create a new calendar entry for a module or library, click New. TheCreate a business calendar window is displayed.1) In the Module or library field, click Browse to select an existing

calendar module or click New to create a module for the newcalendar.

2) In the Folder field, click Browse to select an existing folder orcreate a new folder for the calendar.

3) In the Name field, enter a name for the new calendar.- To create a non template calendar, click Finish. Or

Figure 42. Polling based on business calendar


- To generate the calendar based on a predefined template, clickNext. In the Use a template window, select the Create a calendarusing one of the templates check box and click Finish.

The new business calendar is created and available in the BusinessIntegration view. Once you complete the wizard, you can view ormodify the calendar schedules in the Business Integration viewusing the Business Calendar Editor. You can modify the intervalsand exceptions, or add new entries for these elements. For moredetails about working with business calendars, see Businesscalendars.

Note: You must deploy the Business Calendar module to the same IBMBusiness Process Manager or WebSphere Enterprise Service Bus instance,along with the inbound application. If you do not map these twoconnections to the same server instance, the inbound application usingthe business calendar will by default, poll as there is no calendarconfigured.

h. In the FlatFile specific polling properties section, you can retrieve a fileby using one of the following properties. When any one of the propertiesis selected, the other property is automatically disabled.– In the Time interval for polling unchanged files (in milliseconds)

field, you can specify if the adapter retrieves only those files that arenot changed during the specified time interval. For more information,see “Time interval for polling unchanged files (in milliseconds)” onpage 213.

– Select Poll event files for modified content check box to specify if theadapter polls the files that changed since the last recorded time stamp.For more information, see “Poll event files for modified content” onpage 206.

Note: This property is disabled if you select the Pass only file nameand directory, not the content property.

– Select the Include only the newly appended content check box todeliver the appended file contents to the endpoint. This property isenabled when you select the Poll event files for modified contentcheck box. For more information, see “Include only the newlyappended content” on page 204.

v Event delivery configuration

a. In the Type of delivery field, select the delivery method. The methodsare described in “Delivery type (DeliveryType)” on page 200.

Note: The HA Active-Active configuration supports only unordereddelivery type events. If the delivery type specified is ORDERED, then theadapter throws a runtime exception error.

Figure 43. Configuring the polling properties


http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5mx/index.jsp?topic=/com.ibm.wbpm.wid.bpel.doc/topics/cbuscal.html

http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5mx/index.jsp?topic=/com.ibm.wbpm.wid.bpel.doc/topics/cbuscal.html

b. If you want to ensure that events are delivered only once and to only oneexport, select the Ensure assured-once event delivery check box. Thisoption might reduce performance but does not result in duplicate ormissing event delivery. For more information, see “Ensure once-onlyevent delivery (AssuredOnceDelivery)” on page 201.

c. In the Retry limit for failed events field, specify the number of times totry to deliver an event after a delivery failure. For more information, see“Retry limit for failed events (FailedEventRetryLimit)” on page 203.

v Event persistence configuration

Note: In a HA Active-Active configuration, ensure that you provide valuesfor the mandatory event persistence properties. If a value is not assigned toany of the event persistence properties, then the adapter throws a runtimeexception error.a. Select Auto create event table check box if you want the adapter to

create the Event Persistence table. For more information, see “Auto createevent table” on page 199.

b. In the Event recovery table name field, you can specify the name of thetable that the adapter uses for event persistence. If you specify the Eventrecovery table name field, you must enter value in the Table name tostore the file processing status field, to specify the table name that theadapter uses for file processing. For more information, see “Eventrecovery table name” on page 202 and “Table name to store the fileprocessing status (EP_FileTableName) ” on page 213 properties.

c. In the Event recovery data source (JNDI) name field, specify the JNDIname of the data source that event persistence uses to connect to theJDBC database. For more information, see “Event recovery data source(JNDI) name” on page 202.

d. In the User name used to connect to event data source field, specify theuser name that the event persistence uses to connect to the database fromthe data source. For more information, see “User name used to connect toevent data source” on page 214.

e. In the Password used to connect to event data source field, specify thepassword that the event persistence uses to connect to the database fromthe data source. For more information, see “Password used to connect toevent data source” on page 208.

f. In the Database schema name field, specify the schema name of thedatabase that the event persistence uses. For more information, see“Database schema name” on page 200.

g. In the Time interval for processing the fetched events (in seconds) field,specify the time interval for the adapter to process the fetched events. Formore information, see “Time out period for HA Active-Active eventprocessing change (in seconds) (EP_Timeout)” on page 214.

v Additional configuration

a. In the Retrieve files with this pattern field, specify the filter for the eventfiles. For more information, see “Retrieve files with pattern” on page 209.

b. Select Include business object delimiter in the file content check box tospecify if the delimiter value specified in the SplitCriteria property is sentwith the business object content for further processing. For moreinformation, see “Include business object delimiter in the file content” onpage 205.


c. In the Retrieve files in sorted order list, specify sorting order of polledevent files. For more information, see “Retrieve files in sorted order” onpage 209.

Note: In a HA Active-Active configuration, sorting of event files is notsupported. If the default value (no sort) is changed, then the adapterthrows a runtime exception error.

d. Select a value for the File content encoding field. If you are workingwith binary event data, select BINARY. If you are working with non-binaryevent data, such as text or XML, select a valid file encoding value, suchas UTF-8 (the default value). For more information, see “File contentencoding” on page 204.

e. Select Include total business object count in the ChunkInfo property tospecify that the total business object count is included in the chunkinformation of the dataobject being sent to the endpoint. For moreinformation, see “Include total business object count in the ChunkInfo(includeBOCountInChunkInfo)” on page 205.

f. Select Split file content based on size (bytes) or delimiter check box tospecify file splitting either by size or delimiter. For more information, see“Split file content based on size (bytes) or delimiter” on page 211.

Note: This property is disabled if you select the Pass only file name anddirectory, not the content property.

g. In the Split function class name field, specify how the event file is to besplit, by delimiter or by size. For more information, see “Split functionclass name” on page 212.

h. In the Specify criteria to split file content field, specify the delimiter thatseparates the business objects in the event file or the maximum size ofthe event file, depending on the value that is set in the Splitting FunctionClass Name. For more information, see “Specify criteria to split filecontent” on page 210.

i. Select Poll subdirectories in event directory check box to specify if theadapter polls the subdirectories within the event directory. For moreinformation, see “Poll subdirectories in event directory” on page 208.

v File archiving configuration

a. Select Pass only file name and directory, not the content check box tospecify if the adapter sends the directory name and file name to theendpoint. For more information, see “Pass only file name and directory,not the content” on page 207.

Note: In the external service wizard, you can use this property if both theSplit file content based on size (bytes) or delimiter property and Pollevent files for modified content properties are not selected.

b. In the Archive directory field, specify the directory where the adapterarchives processed event files. For more information, see “Archivedirectory” on page 199.

c. In the File extension for archive field, specify the file extension used toarchive unsuccessfully processed business objects in the input event file.For more information, see “File extension for archive” on page 204.

d. In the Success file extension for archive field, specify the file extensionused to archive successfully processed business objects. For moreinformation, see “Success file extension for archive” on page 213.


e. In the Failure file extension for archive field, specify the file extensionused to archive unsuccessfully processed business objects in the inputevent file. For more information, see “Failure file extension for archive”on page 203.

v Bidi properties

a. Select the Bidi transformation check box to specify bidirectional format.For more information about setting the Bidi properties, refer to the“Globalization” on page 217 section.

v Logging and tracing

a. If you have multiple instances of the adapter, expand Logging andtracing and enter a value in the Adapter ID field that is unique for thisinstance. For more information about this property, see “Adapter ID(AdapterID)” on page 184.

b. If you want to mask certain information so that the information is notdisplayed in the logs or traces, select Disguise user data as "XXX" in logand trace files.

c. To specify the log file output location or define the level of logging forthis module, select the Change logging properties for wizard check box.For information about setting logging levels, see “Configuring loggingproperties” on page 129.

6. In the Service properties section, select whether to use the default functionselector configuration or create a new one.a. To create a function selector configuration, click Select next to the Function

selector field.b. In the Select a Function Selector window, select the Use existing function

selector from the list option.c. Select the required function selector from the list of available function

selectors. Click Next.

Note: A function selector assigns incoming messages or requests to the correctoperation on the service.

Note: The enterprise information system (EIS) function name is not available inthe external service wizard. If you want to specify a value other than thedefault that is generated by the adapter (base classes), you can edit it using theassembly editor.

7. To filter the inbound event file by configuring rules, click Add or Edit in theRule editor table. The rule constitutes three parameters, namely, Property type,Operator and Value.

Figure 44. Creating a function selector configuration


a. Select any of the following metadata filtering property types from Propertytype list.v FileNamev FileSizev Directoryv LastModified

b. Select the operator for the property type from the Operator list. Each of theproperty type metadata has its own operators.1) FileName contains the following operators:

v Matches_File_Pattern (matches pattern)v Matches_RegExp (matches regular expression)

2) FileSize metadata contains the following operators:v Greater thanv Less thanv Greater than or equal tov Less than or equal tov Equal tov Not equal to

3) Directory contains Matches_RegExp as its operators.4) LastModified metadata contains the following operators:

v Greater thanv Less thanv Greater than or equal tov Less than or equal tov Equal tov Not equal to

Figure 45. Adding or editing a rule


c. Type the value for filtering the event file in the Value column. You mustenter a valid Java regular expression in value for Matches_RegExp operator.

To configure multiple rules, select END-OF-RULE option for each rule from theProperty type list.

Note: The rules are grouped by using the logical OR operator, unlessEND-OF-RULE is selected in the property field. If an END-OF-RULE isselected between expressions (an expression can be a single rule or multiplerules grouped by an OR operator), it will be grouped using the logical ANDoperator. For example, If the rule A (FileName) is grouped with rule B(FileSize) using the logical OR operator, and on selecting the END-OF-RULEoption, this expression will be grouped with another rule C (LastModified)using an AND operator. This can be represented as follows: ((A) OR (B)) AND(C)For more information see, “Rule editor to filter files (ruleTable)” on page 214.

8. Click Finish.

Results

The adapter saves the activation specification properties.

What to do next

Select a data type for the module and name the operation associated with thechosen data type.

Selecting the operation and data typeUse the external service wizard to select a data type and name the operationassociated with this data type. The external service wizard gives you a choice ofthree data types: generic FlatFile business object, generic FlatFile business objectwith business graph, and user-defined type. Each data type corresponds to abusiness object structure.

Before you begin

You must specify the connection properties for the adapter to connect to the localfile system before you can complete the steps given here.

About this task

To select a data type and name the operation associated with it, follow thisprocedure.

Procedure1. In the Add, Edit, or Remove Operations window, click Add to create an

operation.2. In the Specify the I/O Properties window, select a data type from the Data

type for the operation list. Click Next. The three available data types are:Generic FlatFile business object, Generic FlatFile business object with businessgraph, and User-defined type. For more information about data types, see,“Business object structures” on page 165. In this example, Generic FlatFilebusiness object is selected.


3. In the Specify the I/O Properties window, the emitFlatFile is displayed as theinbound operation name in the Operation name field.

Note: The emit operation is the only operation available during inboundprocessing.

Results

A data type is defined for the module and the operation associated with this datatype is named.

What to do next

Add and configure a data binding to be used with the module.

Configuring the data bindingEach data type has an equivalent data binding used to read the fields in a businessobject and fill the corresponding fields in the file. In the external service wizard,you add a data binding to your module and configure it to correspond with yourdata type. This way, the adapter knows how to populate the fields in the file withinformation it receives in the business object.

Before you begin

You must specify a data type and choose an operation name to be associated withthe data type.

About this task

To add and configure a data binding for the module, follow this procedure.

Figure 46. Naming the operation and specifying the input data type


Note: Data bindings can be configured before running the external service wizardusing IBM Integration Designer. To do this configuration, select New > ConfigureBinding Resource in IBM Integration Designer and complete the data bindingscreens described in this documentation.

Procedure1. In the Specify the I/O Properties window, select either the Use suggested data

format 'FlatFileBaseDataBinding' or the Use a data format configurationoption from the Data format options list.

2. If you select the Use a data format configuration option, click Select toconfigure the data binding.

3. In the Select a Data Format Transformation window, select the Use existingdata format transformation from the list option. From the list, selectFlatFileBaseDataBinding. To configure a custom data binding, select the Selectyour custom data format transformation from the workspace option. ClickNext.

4. In Specify the Data Transformation Properties window, click Next.

Note: This window is used for configuring the data handlers.

Figure 47. Selecting the data binding


5. In Configure a New Data Transformation window, provide the data bindingconfiguration details.a. In the Configure a New Data Transformation window, the Module defaults

to the module name you typed earlier in the external service. If you want tocreate a data binding for a different module, select New to create a module.

b. If you want to select a new folder for the artifact, click Browse and select anew folder location.

c. Type a Name for the data binding configuration. Click Finish. The databinding name is populated in the Specify the I/O Properties window.

Results

A data binding is configured for use with the module.

What to do next

Select the data handler configuration.

Configuring data handlersData handlers perform the conversions between a business object and a nativeformat. The configuration in this topic is shown using the XML data handler. Forcomma-separated values (CSV) file format files, you must select the Delimited datahandler.

Before you begin

You must create a data binding before you specify data handlers for the module.Also, you must have predefined business objects using IBM Integration DesignerBusiness Object Editor. If you stop the wizard here to create business objects, youneed to start the wizard steps from the beginning.

Note: Data handlers can be configured before running the external service wizardusing IBM Integration Designer. To do this configuration, select New > ConfigureBinding Resource in IBM Integration Designer and complete the data handlerwindows described in this documentation.

About this task

To specify data handlers, follow this procedure.

Procedure1. In the Specify the Data Transformation Properties window, ensure that

DataHandler is selected in the Binding type field.2. In the Configured data handler field, click Select. Complete the following steps

to create and configure a data handler.a. Select the class name for the data handler. In Select a Data Format

Transformation window, click XML for data handler class name. Thisexample uses XML data handler. Click Next.

3. Select the class name for the data handler. In Select a Data FormatTransformation window, click Use existing data format transformation fromthe list option. A list of available data handler classes is displayed. Select XMLdata handler from the list and click Next.


Note: To work with data files (CSV) that uses comma to separate the fields ofdata, select the Delimited data handler. For more information about workingwith delimited data files, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5mx/topic/com.ibm.wbpm.wid.integ.doc/topics/rdelimitedcvs.html.

4. In the Specify the Data Transformation Properties window, specify theEncoding. The default is UTF-8. Click Next.

Note: If Delimited option is selected, the Specify the Data TransformationProperties window provides the delimiter data handler configuration fields.

5. In the Configure a New Data Transformation window, specify the Module,Namespace, Folder, and Name for the data handler configuration. Click Finish.

Figure 48. Selecting the data handler class





6. Click Finish. The configured data handler is populated in the Specify the DataTransformation Properties window.

Results

Data handlers are created.

What to do next

Specify interaction specification properties and generate artifacts for the module.

Setting deployment properties and generating the serviceUse the external service wizard to set activation specification properties andgenerate artifacts for use with your module. Artifacts are the business objects,WSDL files, and import and export files that are created as part of the externalservice. While creating artifacts for the module, the adapter generates an exportfile. The export file contains the operation for the top-level business object.

Figure 49. Specifying a name for the data handler configuration


Before you begin

To set activation specification properties and generate artifacts for your module,you must have already configured data bindings and selected business objects.

About this task

To set activation specification properties and generate artifacts, follow thisprocedure. For more information about activation specification properties, see the“Activation specification properties” on page 196 topic.

Procedure1. In the Add, Edit, or Remove Operations window, click Advanced.2. In the Additional configuration section, type values for different interaction

specification properties. Click Next.

3. In the Specify the Name and Location window, type a name for the interface.This name displays in the IBM Integration Designer assembly diagram. ClickFinish.

Figure 50. The inbound operation with InteractionSpec properties


Results

The IBM Integration Designer generates the artifacts and an import. The inboundartifacts that are created are visible in the IBM Integration Designer ProjectExplorer under your module.

What to do next

Deploy the module.

Figure 51. Naming the artifact


Chapter 5. Changing interaction specification properties

To change interaction specification properties for your adapter module aftergenerating the service, use the assembly editor in IBM Integration Designer.

Before you begin

You must have used the external service wizard to generate a service for theadapter.

About this task

You might want to change interaction specification properties after you havegenerated a service for the adapter. Interaction specification properties, which areoptional, are set at the method level, for a specific operation on a specific businessobject. The values you specify appear as defaults in all parent business objectsgenerated by the external service wizard. You can change these properties beforeyou export the EAR file. You cannot change these properties after you deploy theapplication.

To change the interaction specification properties, use the following procedure:

Procedure1. From the Business Integration perspective of IBM Integration Designer, expand

the module name.2. Expand Assembly Diagram and double-click the interface.3. Click the interface in the assembly editor. The module properties are displayed.4. Click the Properties tab. You can also right-click the interface in the assembly

diagram and click Show in Properties.5. Under Binding, click Method bindings. The methods for the interface are

displayed, one for each combination of business object and operation.6. Select the method whose interaction specification property you want to change.7. Click Advanced and change the property in the Generic tab. Repeat this step

for each method whose interaction specification property you want to change.

Results

The interaction specification properties associated with your adapter module arechanged.

What to do next

Deploy the module.


Chapter 6. Deploying the module

Deploy a module to place the files that make up your module and adapter into anoperational environment for production or testing. In IBM Integration Designer, theintegrated test environment features runtime support for IBM Business ProcessManager or WebSphere Enterprise Service Bus, or both, depending on the testenvironment profiles that you selected during installation.

Deployment environmentsThere are test and production environments into which you can deploy modulesand adapters.

In IBM Integration Designer, you can deploy your modules to one or more serversin the test environment. This is typically the most common practice for runningand testing business integration modules. However, you can also export modulesfor server deployment on IBM Business Process Manager or WebSphere EnterpriseService Bus as EAR files using the Process Administrative Console orcommand-line tools.

Deploying the module for testingIn IBM Integration Designer, you can deploy a module that includes an embeddedadapter to the test environment and work with server tools that enable you toperform such tasks as editing server configurations, starting, and stopping serversand testing the module code for errors. The testing is generally performed on theinterface operations of your components, which enables you to determine whetherthe components are correctly implemented and the references are correctly wired.

Generating and wiring a target component for testing inboundprocessing

Before deploying to the test environment a module that includes an adapter forinbound processing, you must first generate and wire a target component. Thistarget component serves as the destination to which the adapter sends events.

Before you begin

You must have generated an export module, using the external service wizard.

About this task

Generating and wiring a target component for inbound processing is required in atesting environment only. It is not necessary when deploying the adapter in aproduction environment.

The target component receives events. You wire the export to the target component(connecting the two components) using the assembly editor in IBM IntegrationDesigner. The adapter uses the wire to pass event data (from the export to thetarget component).

Procedure1. Create the target component.


a. From the Business Integration perspective of IBM Integration Designer,expand Assembly Diagram and double-click the export component. If youdid not change the default value, the name of the export component is thename of your adapter + InboundInterface.An interface specifies the operations that can be called and the data that ispassed, such as input arguments, returned values, and exceptions. TheInboundInterface contains the operations required by the adapter tosupport inbound processing and is created when you run the externalservice wizard.

b. Create a new component by expanding Components, selecting UntypedComponent, and dragging the component to the Assembly Diagram.The cursor changes to the placement icon.

c. Click the component to have it displayed in the Assembly Diagram.2. Wire the components.

a. Click and drag the export component to the new component.b. Save the assembly diagram. Click File > Save.

3. Generate an implementation for the new component.a. Right-click on the new component and select Generate Implementation >

Java.b. Select (default package) and click OK. This creates an endpoint for the

inbound module.The Java implementation is displayed in a separate tab.

c. Optional: Add print statements to print the data object received at theendpoint for each of the endpoint methods.

d. Click File > Save to save the changes.

What to do next

Continue deploying the module for testing.

Adding the module to the serverIn IBM Integration Designer, you can add modules to one or more servers in thetest environment.

Before you begin

If the module you are testing uses an adapter to perform inbound processing,generate and wire a target component to which the adapter sends the events.

About this task

In order to test your module and its use of the adapter, you need to add themodule to the server.

Procedure1. Conditional: If there are no servers in the Servers view, add and define a new

server by performing the following steps:a. Place your cursor in the Servers view, right-click, and select New > Server.b. From the Define a New Server window, select the server type.c. Configure servers settings.d. Click Finish to publish the server.


2. Add the module to the server.a. Switch to the servers view. In IBM Integration Designer, select Windows >

Show View > Servers.a. Start the server. In the Servers tab in the lower-right pane of the IBM

Integration Designer screen, right-click the server, and then select Start.3. When the server status is Started, right-click the server, and select Add and

Remove Projects.4. In the Add and Remove Projects screen, select your project and click Add. The

project moves from the Available projects list to the Configured projects list.5. Click Finish. This deploys the module on the server.

The Console tab in the lower-right pane displays a log while the module isbeing added to the server.

What to do next

Test the functionality of your module and the adapter.

Testing the module for outbound processing using the testclient

Test the assembled module and adapter for outbound processing using the IBMIntegration Designer integration test client.

Before you begin

You need to add the module to the server first.

About this task

Testing a module is performed on the interface operations of your components,which enables you to determine whether the components are correctlyimplemented and the references are correctly wired.

Procedure1. Select the module you want to test, right-click on it, and select Test > Test

Module.2. For information about testing a module using the test client, see the Testing

modules and components topic in the IBM Integration Designer informationcenter.

What to do next

If you are satisfied with the results of testing your module and adapter, you candeploy the module and adapter to the production environment.

Deploying the module for productionDeploying a module created with the external service wizard to IBM BusinessProcess Manager or WebSphere Enterprise Service Bus in a productionenvironment is a two-step process. First, you export the module in IBM IntegrationDesigner as an enterprise archive (EAR) file. Second, you deploy the EAR fileusing the IBM Business Process Manager or WebSphere Enterprise Service BusProcess Administrative Console.

Chapter 6. Deploying the module 115

Installing the RAR file (for modules using stand-aloneadapters only)

If you chose not to embed the adapter with your module, but instead choose tomake the adapter available to all deployed applications in the server instance, youneed to install the adapter in the form of a RAR file to the application server. ARAR file is a Java archive (JAR) file that is used to package a resource adapter forthe Java EE Connector Architecture (JCA).

Before you begin

You must set Deploy connector project to On server for use by multiple adaptersin the Specify the Service Generation and Deployment Properties window of theexternal service wizard.

About this task

Installing the adapter in the form of a RAR file results in the adapter beingavailable to all Java EE application components running in the server run time.

Procedure1. If the server is not running, right-click your server in the Servers view and

select Start.2. When the server status changes to Started, right-click the server and select

Administration > Run administrative console.3. Log on to the administrative console.4. Click Resources > Resource Adapters > Resource adapters.5. In the Resource adapters page, click Install RAR.

Figure 52. The Install RAR button on the Resource adapters page


6. In the Install RAR file page, click Browse and navigate to the RAR file foryour adapter.The RAR files are typically installed in the following path:IID_installation_directory/ResourceAdapters/adapter_name/adapter.rar

7. Click Next.8. Optional: In the Resource adapters page, change the name of the adapter and

add a description.9. Click OK.

10. Click Save in the Messages box at the top of the page.

What to do next

The next step is to export the module as an EAR file that you can deploy on theserver.

Exporting the module as an EAR fileUsing IBM Integration Designer, export your module as an EAR file. By creatingan EAR file, you capture all of the contents of your module in a format that can beeasily deployed to IBM Business Process Manager or WebSphere Enterprise ServiceBus.

Before you begin

Before you can export a module as an EAR file, you must have created a moduleto communicate with your service. The module should be displayed in the IBMIntegration Designer Business Integration perspective.

About this task

To export the module as an EAR file, perform the following procedure.

Procedure1. Right-click the module and select Export.2. In the Select window, expand Java EE.3. Select EAR file and click Next.4. Optional: Select the correct EAR application. The EAR application is named

after your module, but with “App” added to the end of the name.5. Browse for the folder on the local file system where the EAR file will be placed.6. Optional: To export the source files, select the Export source files check box.

This option is provided in case you want to export the source files in additionto the EAR file. Source files include files associated with Java components, datamaps, and so on.

7. Optional: To overwrite an existing file, click Overwrite existing file.8. Click Finish.

Results

The contents of the module are exported as an EAR file.


What to do next

Install the module in the Process Administrative Console. This deploys the moduleto IBM Business Process Manager or WebSphere Enterprise Service Bus.

Installing the EAR fileInstalling the EAR file is the last step of the deployment process. When you installthe EAR file on the server and run it, the adapter, which is embedded as part ofthe EAR file, runs as part of the installed application.

Before you begin

You must have exported your module as an EAR file before you can install it onIBM Business Process Manager or WebSphere Enterprise Service Bus.

About this task

To install the EAR file, perform the following procedure. For more informationabout clustering adapter module applications, see the http://www.ibm.com/software/webservers/appserv/was/library/.



Administration > Run administrative console.3. Log on to the administrative console.4. Click Applications > New Application > New Enterprise Application.

5. Click Browse to locate your EAR file and click Next. The EAR file name is thename of the module followed by "App."

Figure 53. Preparing for the application installation window


http://www.ibm.com/software/webservers/appserv/was/library/


6. Optional: If you are deploying to a clustered environment, complete thefollowing steps.a. On the Step 2: Map modules to servers window, select the module and

click Next.b. Select the name of the server cluster.c. Click Apply.

7. Click Next. In the Summary page, verify the settings and click Finish.8. Optional: If you are using an authentication alias, complete the following steps:

a. Expand Security and select Business Integration Security.b. Select the authentication alias that you want to configure. You must have

administrator or operator rights to change the authentication aliasconfigurations.

c. Optional: If it is not already specified, type the User name.d. If it is not already specified, type the Password.e. If it is not already specified, type the password again in the Confirm

Password field.f. Click OK.

Results

The project is now deployed and the Enterprise Applications window is displayed.

What to do next

If you want to set or reset any properties or you would like to cluster adapterproject applications, make those changes using the Process Administrative Consolebefore configuring troubleshooting tools.

Deploying the module in a clustered environmentIn IBM Integration Designer, you can deploy the IBM WebSphere Adapter for FlatFiles in a clustered environment.

To deploy the module in a clustered environment, use any of the followingapproaches.v Embedded module: The adapter is embedded in the application and specific to

it. The adapter cannot be shared between multiple applications.v Node level module with embedded activation specification: The adapter is

deployed at the node level, with the activation specification created duringmodule creation. The adapter can be shared across multiple applications.

v Node level module with JNDI activation specification reference: The adapter isdeployed at the node level, and the application provides a JNDI reference to theactivation specification. You must create the reference at the cluster scope fromthe Process Administrative Console, with the same JNDI name. The adapter canbe shared across multiple applications.

Deploying module embedded in the applicationThe adapter is deployed embedded in the application and specific to it. Theadapter cannot be shared between multiple applications.


Before you begin

The following steps are a necessary prerequisite to configure and deploy themodule.v IBM Integration Designer version 7.5.0.0 or above.v A clustered topology deployment environment on the IBM Business Process

Manager or WebSphere Enterprise Service Bus available from IBM IntegrationDesigner.

v Create a clustered topology deployment environment, as shown in the followingGold Topology configuration figure.

v Deploy the adapter and the adapter applications (EAR files) in the AppTarget(the target that hosts the SCA container).

About this task

To create an application with the embedded adapter, use the external servicewizard.

Figure 54. Deployment environment

Figure 55. Deployment environment showing server clusters


Procedure1. In the Service Configuration Properties window, from the Deploy connector

project property list, select With module for use by single application.2. Create the module as described in the Business process management samples

for WebSphere Adapters.3. In the Dependencies option for the module, after the module is created, ensure

that the Deploy with module option is selected for the adapter.4. If the server is not running, right-click your server in the Servers view and


Administration > Run administrative console.6. From the Deployment Manager Admin Console, click Install applications to

deploy the application.7. On the Step 2: Map modules to servers window, select the module and click

Next. For the embedded adapter option, the adapter is deployed as part of theapplication, as shown in the following figure.

8. In the Enterprise Applications view, select the new applicationFFEmbeddedModuleApp. The new application is displayed after theapplication is deployed at the deployment manager level.

9. Select the node and click Installed applications to view the deployedapplication on each individual node.

Results

The resource adapter is embedded and deployed as part of the application.

Deploying module at node level with embedded activationspecification

The adapter is deployed at the node level, with the activation specification createdduring module creation. The adapter can be shared across multiple applications.

Figure 56. Embedded module deployment showing adapters installed


http://publib.boulder.ibm.com/bpcsamp/index.html


Before you begin





About this task

To create an application with the node level adapter and activation specificationproperties specified in the module itself, use the external service wizard.





project property list, select On server for use by multiple applications.2. From the Connection properties list, select Use properties below.3. Create the module as described in the Business process management samples

for WebSphere Adapters.4. In the Dependencies option for the module, ensure that the Deploy with

module option is not selected for the adapter. Here, the adapter is not part ofthe module, therefore you must deploy the adapter before deploying theapplication.

5. If the server is not running, right-click your server in the Servers view andselect Start.

6. When the server status changes to Started, right-click the server and selectAdministration > Run administrative console. Log on to the administrativeconsole.

7. To deploy the adapter at individual nodes, click Resources > ResourceAdapters > Resource adapters. In the clustered environment, you must installthe adapter in each node separately.

8. In the Resource adapters page, click Install RAR.9. In the Install RAR file page, click Browse and navigate to the RAR file for

your adapter. Deploy the RAR on each node.The RAR files are typically installed in the following path:IID_installation_directory/ResourceAdapters/adapter_name/adapter.rar

10. For deployment at node level, do not select any Scope because the scope isalways Node. Click Next.

11. Optional: In the Resource adapters page, change the name of the adapter andadd a description. Click OK.

12. Click Save in the Messages box at the top of the page.13. For node level deployment, check if the adapter RAR is deployed at the node

level as shown in the following figure.

14. To deploy the adapter at the cluster level, click Resources > ResourceAdapters > Resource adapters.

15. In the Resource adapters window, set the Scope to Cluster, and then clickNew.

16. Select the RAR deployed at the node level.17. Check if the adapter RAR is now deployed at the cluster level as shown in the

following figure. Deploy the application after the adapter is deployed at thenode level on the individual nodes, and then at the cluster level.

18. From the Deployment Manager Admin Console, click Install applications todeploy the application.

19. On the Step 2: Map modules to servers window, select the module and clickNext. The adapter is not part of the deployed application as shown in the

Figure 59. Adapter RAR deployed on a node




following figure.

20. In the Admin Console, click Resources > Resource Adapters > IBMWebSphere Adapter for Flat Files > J2C activation specifications to view theactivation specification from the adapter deployed at the cluster level.

Results

The resource adapter is deployed at the node level, with the activationspecification.

Deploying module at node level with JNDI activationspecification

The adapter is deployed at the node level, and the application provides a JNDIreference to the activation specification. You must create the activation specificationwith the same JNDI name at the cluster scope from the Process AdministrativeConsole. The adapter can be shared across multiple applications

Before you begin




Figure 60. Installed application not containing the adapter



About this task

To create an application with the node level adapter and activation specificationproperties specified in the module itself, use the external service wizard.


project property list, select On server for use by multiple applications.2. From the Connection properties list, select Use JNDI lookup name

configured on server.3. In the JNDI lookup name property field, specify the JNDI name. Use this

same JNDI name when you create the activation specification from the AdminConsole.

4. Create the module as described in the Business process management samplesfor WebSphere Adapters.

5. In the Dependencies option for the module, ensure that the Deploy withmodule option is not selected for the adapter.






6. If the server is not running, right-click your server in the Servers view andselect Start.

7. When the server status changes to Started, right-click the server and selectAdministration > Run administrative console. Log on to the administrativeconsole.

8. To install the adapter at the node level, click Resources > Resource Adapters> Resource adapters. In the clustered environment, you must install theadapter in each node separately.

9. In the Resource adapters page, click Install RAR.10. In the Install RAR file page, click Browse and navigate to the RAR file for

your adapter. Deploy the RAR on each node.The RAR files are typically installed in the following path:IID_installation_directory/ResourceAdapters/adapter_name/adapter.rar

11. For deployment at node level, do not select any Scope because the scope isalways Node. Click Next.

12. Optional: In the Resource adapters page, change the name of the adapter andadd a description. Click OK.

13. Click Save in the Messages box at the top of the page.14. To install the RAR at the cluster level, click Resources > Resource Adapters >

Resource adapters

15. In the Resource adapters page, set the Scope to Cluster, and then click New.16. Select the RAR deployed at the node level, and then check if the adapter RAR

is now deployed at the cluster level. Deploy the application after the adapteris deployed at the node level on the individual nodes, and then at the clusterlevel.

17. From the Deployment Manager Admin Console, click Install applications todeploy the application.

18. In the Admin Console, click Resources > Resource Adapters > IBMWebSphere Adapter for Flat Files > J2C activation specifications > New tocreate the activation specification from the adapter deployed at the clusterlevel.

19. When installing the adapter, in the Name field, you must enter the same nameas defined in the RAR.

20. In the JNDI name field, you must enter the same name as given during themodule creation.

21. Click Resources > Resource Adapters > IBM WebSphere Adapter for FlatFiles > J2C activation specifications to check if the JNDI reference on theadapter is same as the one specified for the module.

22. Click Resources > Resource Adapters > IBM WebSphere Adapter for FlatFiles > J2C activation specifications > Custom properties to set values for theactivation specification in the Admin Console.


23. From the Deployment Manager Admin console, click Install applications todeploy the application after you deploy the RAR and create the activationspecification.

24. On the Step 2: Map modules to servers page, select the module and clickNext. The adapter is not part of the deployed application as shown in thefollowing figure.

Results

The resource adapter is deployed at the node level, with the JNDI activationspecification reference.

Figure 63. JNDI reference created for the module

Figure 64. Installed application not containing the adapter


Chapter 7. Administering the adapter module

When you are running the adapter in a stand-alone deployment, use theadministrative console of the server to start, stop, monitor, and troubleshoot theadapter module. In an application that uses an embedded adapter, the adaptermodule starts or stops when the application is started or stopped.

Configuring logging and tracingConfigure logging and tracing to suit your requirements. Enable logging for theadapter to control the status of event processing. Change the adapter log and tracefile names to separate them from other log and trace files.

Configuring logging propertiesUse the Process Administrative Console to enable logging and to set the outputproperties for a log, including the location, level of detail, and output format of thelog.

About this task

Before the adapters can log monitored events, you must specify the servicecomponent event points that you want to monitor, what level of detail you requirefor each event, and format of the output used to publish the events to the logs.Use the administrative console to perform the following tasks:v Enable or disable a particular event logv Specify the level of detail in a logv Specify where log files are stored and how many log files are keptv Specify the format for log output

If you set the output for log analyzer format, you can open trace output usingthe Log Analyzer tool, which is an application included with your IBM ProcessServer. This is useful if you are trying to correlate traces from two differentserver processes, because it allows you to use the merge capability of the LogAnalyzer.

Note: For more information about monitoring on a IBM Process Server, includingservice components and event points, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.admin.doc/topics/welcome_wps_mon.html.

You can change the log configuration statically or dynamically. Static configurationtakes effect when you start or restart the application server. Dynamic or run timeconfiguration changes apply immediately.

When a log is created, the detail level for that log is set from the configurationdata. If no configuration data is available for a particular log name, the level forthat log is obtained from the parent of the log. If no configuration data exists forthe parent log, the parent of that log is checked, and so on, up the tree, until a logwith a non-null level value is found. When you change the level of a log, thechange is propagated to the child logs, which recursively propagate the change totheir child log, as necessary.


http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.admin.doc/topics/welcome_wps_mon.html



To enable logging and set the output properties for a log, use the followingprocedure.

Procedure1. In the navigation pane of the administrative console, select Servers >

WebSphere application servers.2. Click the name of the server that you want to work with.3. Under Troubleshooting, click Logging and tracing.4. Click Change log detail levels.5. Specify when you want the change to take effect:

v For a static change to the configuration, click the Configuration tab.v For a dynamic change to the configuration, click the Runtime tab.

6. Click the names of the packages whose logging level you want to modify. Thepackage names for WebSphere Adapters start with com.ibm.j2ca.*:v For the adapter base component, select com.ibm.j2ca.base.*.v For the adapter base component and all deployed adapters, select

com.ibm.j2ca.*.v For the WebSphere Adapter for Flat Files only, select the

com.ibm.j2ca.flatfile.* package.7. Select the logging level.

Logging Level Description

Fatal The task cannot continue or the component cannot function.

Severe The task cannot continue, but the component can still function.This logging level also includes conditions that indicate animpending fatal error, that is, situations that strongly suggest thatresources are on the verge of being depleted.

Warning A potential error has occurred or a severe error is impending.This logging level also includes conditions that indicate aprogressive failure, for example, the potential leaking ofresources.

Audit A significant event has occurred that affects the server state orresources.

Info The task is running. This logging level includes generalinformation outlining the overall progress of a task.

Config The status of a configuration is reported or a configurationchange has occurred.

Detail The subtask is running. This logging level includes generalinformation detailing the progress of a subtask.

8. Click Apply.9. Click OK.

10. Optional: To have static configuration changes take effect, stop and thenrestart the IBM Process Server.

Results

Log entries from this point forward contain the specified level of information forthe selected adapter components.


Changing the log and trace file namesTo keep the adapter log and trace information separate from other processes, usethe administrative console to change the file names. By default, log and traceinformation for all processes and applications on a IBM Process Server is written tothe SystemOut.log and trace.log files.

Before you begin

You can change the log and trace file names at any time after the adapter modulehas been deployed to an application server.

About this task

You can change the log and trace file names statically or dynamically. Staticchanges take effect when you start or restart the application server. Dynamic orrun time changes apply immediately.

Log and trace files are in the install_root/profiles/profile_name/logs/server_name folder.

To set or change the log and trace file names, use the following procedure.

Procedure1. In the navigation pane of the administrative console, select Applications

>Application Types>WebSphere enterprise applications.2. In the Enterprise Applications list, click the name of the adapter application.

This is the name of the EAR file for the adapter, but without the ear fileextension. For example, if the EAR file is named Accounting_OutboundApp.ear,then click Accounting_OutboundApp.

3. In the Configuration tab, select Modules>Manage Modules.4. In the list of modules, click IBM WebSphere Adapter for Flat Files.5. In the Configuration tab, under Additional Properties, click Resource Adapter.6. In the Configuration tab, under Additional Properties, click Custom properties.7. In the Custom Properties table, change the file names.

a. Click either logFilename to change the name of the log file ortraceFilename to change the name of the trace file.

b. In the Configuration tab, type the new name in the Value field. By default,the log file is called SystemOut.log and the trace file is called trace.log.

c. Click Apply or OK. Your changes are saved on your local machine.d. To save your changes to the master configuration on the server, use one of

the following procedures:v Static change: Stop and restart the server. This method allows you to

make changes, but those changes do not take effect until you stop andstart the server.

v Dynamic change: Click the Save link in the Messages box above theCustom properties table. Click Save again when prompted.

Chapter 7. Administering the adapter module 131

Changing configuration properties for embedded adaptersTo change the configuration properties after you deploy the adapter as part of amodule, you use the administrative console of the runtime environment. You canupdate resource adapter properties (used for general adapter operation), managedconnection factory properties (used for outbound processing), and activationspecification properties (used for inbound processing). For information aboutconfiguring logging properties and changing the log and trace file names, see“Configuring logging and tracing” on page 129.

Setting resource adapter properties for embedded adaptersTo set resource adapter properties for your adapter after it has been deployed aspart of a module, use the administrative console. You select the name of theproperty you want to configure and then change or set the value.

Before you begin

Your adapter module must be deployed on IBM Business Process Manager orWebSphere Enterprise Service Bus.

About this task

Custom properties are default configuration properties shared by all IBMWebSphere Adapters.

To configure properties using the administrative console, use the followingprocedure:



Administration > Run administrative console.3. Log on to the administrative console.4. Select Applications > Application Types > WebSphere enterprise

application.5. From the Enterprise Applications list, click the name of the adapter module

whose properties you want to change. The Configuration page is displayed.


6. Under Modules, click Manage Modules.7. Click IBM WebSphere Adapter for Flat Files.8. From the Additional Properties list, click Resource Adapter.9. On the next page, from the Additional Properties list, click Custom

properties.10. For each property you want to change, perform the following steps.

Note: For more information about,v Inbound resource adapter properties, see“Resource adapter properties” on

page 214v Outbound resource adapter properties, see “Resource adapter properties”

on page 183a. Click the name of the property. The Configuration page for the selected

property is displayed.b. Change the contents of the Value field or type a value, if the field is

empty.c. Click OK.

11. In the Messages area, click Save.

Results

The resource adapter properties associated with your adapter module are changed.

Figure 65. The Manage Modules selection in the Configuration tab


Setting managed (J2C) connection factory properties forembedded adapters

To set managed connection factory properties for your adapter after it has beendeployed as part of a module, use the administrative console. You select the nameof the property you want to configure and then change or set the value.

Before you begin


About this task

You use managed connection factory properties to configure the target local filesystem instance.

Note: In the administrative console, the properties are referred to as "J2Cconnection factory properties."

To configure properties using the administrative console, use the followingprocedure.




application.5. In the Enterprise Applications list, click the name of the adapter module

whose properties you want to change.


6. Under Modules, click Manage Modules.7. Click IBM WebSphere Adapter for Flat Files.8. In the Additional Properties list, click Resource Adapter.9. On the next page, from the Additional Properties list, click J2C connection

factories.10. Click the name of the connection factory associated with your adapter

module.11. In the Additional Properties list, click Custom properties.

Custom properties are those J2C connection factory properties that are uniqueto IBM WebSphere Adapter for Flat Files. Connection pool and advancedconnection factory properties are properties you configure if you aredeveloping your own adapter.

12. For each property you want to change, perform the following steps.

Note: See “Managed connection factory properties” on page 177 for moreinformation about these properties.a. Click the name of the property.b. Change the contents of the Value field or type a value, if the field is

empty.c. Click OK.




Results

The managed connection factory properties associated with your adapter moduleare changed.

Setting activation specification properties for embeddedadapters

To set activation specification properties for your adapter after it has beendeployed as part of a module, use the administrative console. You select the nameof the message endpoint property you want to configure, and then change or setthe value.

Before you begin


About this task

You use activation specification properties to configure the endpoint for inboundprocessing.





application.5. From the Enterprise Applications list, click the name of the adapter module

whose properties you want to change.


6. Under Modules, click Manage Modules.7. Click IBM WebSphere Adapter for Flat Files.8. From the Additional Properties list, click Resource Adapter.9. On the next page, from the Additional Properties list, click J2C activation

specifications.10. Click the name of the activation specification associated with the adapter

module.11. From the Additional Properties list, click J2C activation specification custom

properties.12. For each property you want to change, perform the following steps.

Note: See “Activation specification properties” on page 196 for moreinformation about these properties.a. Click the name of the property.b. Change the contents of the Value field or type a value, if the field is

empty.c. Click OK.


Results

The activation specification properties associated with your adapter module arechanged.



Changing configuration properties for stand-alone adaptersTo set configuration properties after you install a stand-alone adapter, use theadministrative console of the runtime environment. Provide the generalinformation about the adapter and then set the resource adapter properties (whichare used for general adapter operation). If the adapter is used for outboundoperations, create a connection factory and then set the properties for it. If theadapter is used for inbound operations, create an activation specification and thenset the properties for it. For information about configuring logging properties andchanging the log and trace file names, see “Configuring logging and tracing” onpage 129.

Setting resource adapter properties for stand-alone adaptersTo set resource adapter properties for your stand-alone adapter after it has beeninstalled on IBM Business Process Manager or WebSphere Enterprise Service Bus,use the administrative console. You select the name of the property you want toconfigure and then change or set the value.

Before you begin

Your adapter must be installed on IBM Business Process Manager or WebSphereEnterprise Service Bus.

About this task

Custom properties are default configuration properties shared by all IBMWebSphere Adapters.




Administration > Run administrative console.3. Log on to the administrative console.4. Click Resources > Resource Adapters > Resource adapters.5. In the Resource adapters page, click IBM WebSphere Adapter for Flat Files.6. In the Additional Properties list, click Custom properties.7. For each property you want to change, perform the following steps.

Note: For more information about,v Inbound resource adapter properties, see“Resource adapter properties” on

page 214v Outbound resource adapter properties, see “Resource adapter properties” on

page 183a. Click the name of the property.b. Change the contents of the Value field or type a value, if the field is empty.c. Click OK.



Results

The resource adapter properties associated with your adapter are changed.

Setting managed (J2C) connection factory properties forstand-alone adapters

To set managed connection factory properties for your stand-alone adapter after ithas been installed on IBM Business Process Manager or WebSphere EnterpriseService Bus, use the administrative console. You select the name of the propertyyou want to configure and then change or set the value.

Before you begin


About this task

You use managed connection factory properties to configure the target local filesystem instance.

Note: In the administrative console, the properties are referred to as "J2Cconnection factory properties."




Administration > Run administrative console.3. Log on to the administrative console.4. Click Resources > Resource Adapters > Resource adapters.5. In the Resource adapters page, click IBM WebSphere Adapter for Flat Files.6. In the Additional Properties list, click J2C connection factories.7. If you are going to use an existing connection factory, skip ahead to select

from the list of existing connection factories.

Note: If you have selected Specify connection properties when you use theexternal service wizard to configure the adapter module, you do not need tocreate a connection factory.If you are creating a connection factory, perform the following steps:a. Click New.b. In the General Properties section of the Configuration tab, type a name

for the connection factory. For example, you can type AdapterCF.c. Type a value for JNDI name. For example, you can type

com/eis/AdapterCF.d. Optional: Select an authentication alias from the Component-managed

authentication alias list.e. Click OK.f. In the Messages area, click Save.


The newly created connection factory is displayed.

8. In the list of connection factories, click the one you want to use.9. In the Additional Properties list, click Custom properties.

Custom properties are those J2C connection factory properties that are uniqueto WebSphere Adapter for Flat Files. Connection pool and advancedconnection factory properties are properties you configure if you aredeveloping your own adapter.

10. For each property you want to change, perform the following steps.

Note: See “Managed connection factory properties” on page 177 for moreinformation about these properties.a. Click the name of the property.b. Change the contents of the Value field or type a value, if the field is

empty.c. Click OK.

11. After you have finished setting properties, click Apply.12. In the Messages area, click Save.

Results

The managed connection factory properties associated with your adapter are set.

Setting activation specification properties for stand-aloneadapters

To set activation specification properties for your stand-alone adapter after it hasbeen installed on IBM Business Process Manager or WebSphere Enterprise ServiceBus, use the administrative console. You select the name of the message endpointproperty you want to configure, and then change or set the value.

Before you begin


About this task

You use activation specification properties to configure the endpoint for inboundprocessing.


Figure 68. User-defined connection factories for use with the resource adapter




Administration > Run administrative console.3. Log on to the administrative console.4. Click Resources > Resource Adapters > Resource adapters.5. In the Resource adapters page, click IBM WebSphere Adapter for Flat Files.6. In the Additional Properties list, click J2C activation specifications.7. If you are going to use an existing activation specification, skip ahead to select

from an existing list of activation specifications.

Note: If you have selected Use predefined connection properties when youuse the external service wizard to configure the adapter module, you mustcreate an activation specification.If you are creating an activation specification, perform the following steps:a. Click New.b. In the General Properties section of the Configuration tab, type a name

for the activation specification. For example, you can type AdapterAS.c. Type a value for JNDI name. For example, you can type

com/eis/AdapterAS.d. Optional: Select an authentication alias from the Authentication alias list.e. Select a message listener type.f. Click OK.g. Click Save in the Messages box at the top of the page.

The newly created activation specification is displayed.8. In the list of activation specifications, click the one you want to use.9. In the Additional Properties list, click J2C activation specification custom

properties.10. For each property you want to set, perform the following steps.

Note: See “Activation specification properties” on page 196 for moreinformation about these properties.a. Click the name of the property.b. Change the contents of the Value field or type a value, if the field is

empty.c. Click OK.

11. After you have finished setting properties, click Apply.12. In the Messages area, click Save.

Results

The activation specification properties associated with your adapter are set.

Starting the application that uses the adapterUse the administrative console of the server to start an application that uses theadapter. By default, the application starts automatically when the server starts.


About this task

Use this procedure to start the application, whether it is using an embedded or astand-alone adapter. For an application that uses an embedded adapter, theadapter starts when the application starts. For an application that uses astand-alone adapter, the adapter starts when the application server starts.



Administration > Run administrative console.3. Log on to the administrative console.4. Click Applications > Application Types > WebSphere enterprise applications.

Note: The administrative console is labeled “Integrated Solutions Console”.5. Select the application that you want to start. The application name is the name

of the EAR file you installed, without the .EAR file extension.6. Click Start.

Results

The status of the application changes to Started, and a message stating that theapplication has started displays at the top of the administrative console.

Stopping the application that uses the adapterUse the administrative console of the server to stop an application that uses theadapter. By default, the application stops automatically when the server stops.

About this task

Use this procedure to stop the application, whether it is using an embedded or astand-alone adapter. For an application with an embedded adapter, the adapterstops when the application stops. For an application that uses a stand-aloneadapter, the adapter stops when the application server stops.



Administration > Run administrative console.3. Log on to the administrative console.4. Click Applications > Application Types > WebSphere enterprise applications.

Note: The administrative console is labeled “Integrated Solutions Console”.5. Select the application that you want to stop. The application name is the name

of the EAR file you installed, without the .EAR file extension.6. Click Stop.


Results

The status of the application changes to Stopped, and a message stating that theapplication has stopped is displayed at the top of the administrative console.

Monitoring performance using Performance Monitoring InfrastructurePerformance Monitoring Infrastructure (PMI) is a feature of the administrativeconsole that allows you to dynamically monitor the performance of components inthe production environment, including IBM WebSphere Adapter for Flat Files. PMIcollects adapter performance data, such as average response time and total numberof requests, from various components in the server and organizes the data into atree structure. You can view the data through the Tivoli® Performance Viewer, agraphical monitoring tool that is integrated with the Process AdministrativeConsole in IBM Business Process Manager or WebSphere Enterprise Service Bus.

About this task

You can monitor the performance of your adapter by having PMI collect data atthe following points:v At outbound processing to monitor outbound requests.v At inbound event retrieval to monitor the retrieval of an event from the event

table.v At inbound event delivery to monitor the delivery of an event to the endpoint

or endpoints.

Before you enable and configure PMI for your adapter, you must first set the levelof tracing detail and run some events from which to gather performance data.

To learn more about how PMI can help you monitor and improve the overallperformance of your adapter environment, search for PMI on the IBM BusinessProcess Manager or WebSphere Enterprise Service Bus website:http://www.ibm.com/software/webservers/appserv/was/library/.

Configuring Performance Monitoring InfrastructureYou can configure Performance Monitoring Infrastructure (PMI) to gather adapterperformance data, such as average response time and total number of requests.After you configure PMI for your adapter, you can monitor the adapterperformance using Tivoli Performance viewer.

Before you begin

Before you can configure PMI for your adapter, you must first set the level oftracing detail and run some events to gather the performance data.1. To enable tracing and to receive event data, the trace level must be set to either

fine, finer, finest, or all. After *=info, add a colon and a string, for example:*=info: WBILocationMonitor.CEI.ResourceAdapter.*=finest: WBILocationMonitor.LOG.ResourceAdapter.*=finest:

For instructions on setting the trace level, see “Enabling tracing with theCommon Event Infrastructure” on page 146.

2. Generate at least one outbound request or inbound event to produceperformance data that you can configure.



Procedure1. Enable PMI for your adapter.

a. In the administrative console, expand Monitoring and Tuning, and thenselect Performance Monitoring Infrastructure (PMI).

b. From the list of servers, click the name of your server.c. Select the Configuration tab, and then select the Enable Performance

Monitoring (PMI) check box.d. Select Custom to selectively enable or disable statistics.

e. Click Apply or OK.f. Click Save. PMI is now enabled.

2. Configure PMI for your adapter.a. In the administrative console, expand Monitoring and Tuning, and then

select Performance Monitoring Infrastructure (PMI).b. From the list of servers, click the name of your server.c. Select Custom.d. Select the Runtime tab. The following figure shows the Runtime tab.

Figure 69. Enabling Performance Monitoring Infrastructure


e. Click WBIStats.RootGroup. This is a PMI sub module for data collected inthe root group. This example uses the name WBIStats for the root group.

f. Click ResourceAdapter. This is a sub module for the data collected for theJCA adapters.

g. Click the name of your adapter, and select the processes you want tomonitor.

h. In the right pane, select the check boxes for the statistics you want togather, and then click Enable.

Results

PMI is configured for your adapter.

What to do next

Now you can view the performance statistics for your adapter.

Viewing performance statisticsYou can view adapter performance data through the graphical monitoring tool,Tivoli Performance Viewer. Tivoli Performance Viewer is integrated with theProcess Administrative Console in IBM Business Process Manager or WebSphereEnterprise Service Bus.

Before you begin

Configure Performance Monitoring Infrastructure for your adapter.

Procedure1. In the administrative console, expand Monitoring and Tuning, expand

Performance Viewer, then select Current Activity.2. In the list of servers, click the name of your server.3. Under your server name, expand Performance Modules.

Figure 70. Runtime tab used for configuring PMI


4. Click WBIStatsRootGroup.5. Click ResourceAdapter and the name of your adapter module.6. If there is more than one process, select the check boxes for the processes

whose statistics you want to view.

Results

The statistics are displayed in the right panel. You can click View Graph to view agraph of the data, or View Table to see the statistics in a table format.

The following figure shows adapter performance statistics.

Enabling tracing with the Common Event InfrastructureThe adapter can use the Common Event Infrastructure (CEI), a componentembedded in the server, to report data about critical business events such as thestarting or stopping of a poll cycle. Event data can be written to a database or atrace log file depending on configuration settings.

About this task

Use this procedure to report CEI entries in the trace log file by using the CommonBase Event Browser within the administrative console.

Figure 71. Adapter performance statistics, using graph view


Procedure1. In the administrative console, click Troubleshooting.2. Click Logs and Trace.3. From the list of servers, click the name of your server.4. In the Change Log Detail Levels box, click the name of the CEI database (for

example, WBIEventMonitor.CEI.ResourceAdapter.*) or the trace log file (forexample, WBIEventMonitor.LOG.ResourceAdapter.*) to which you want theadapter to write event data.

5. Select the level of detail about business events that you want the adapter towrite to the database or trace log file, and (optionally) adjust the granularity ofdetail associated with messages and traces.v No Logging. Turns off event logging.v Messages Only. The adapter reports an event.v All Messages and Traces. The adapter reports details about an event.v Message and Trace Levels. Settings for controlling the degree of detail the

adapter reports about the business object payload associated with an event. Ifyou want to adjust the detail level, select one of the following options:Fine. The adapter reports the event but none of the business object payload.Finer. The adapter reports the event and the business object payloaddescription.Finest. The adapter reports the event and the entire business object payload.

6. Click OK.

Results

Event logging is enabled. You can view CEI entries in the trace log file or by usingthe Common Base Event Browser within the administrative console.


Chapter 8. Troubleshooting and support

Common troubleshooting techniques and self-help information help you identifyand solve problems quickly. For information about configuring logging propertiesand changing the log and trace file names, see “Configuring logging and tracing”on page 129.

Techniques for troubleshooting problemsTroubleshooting is a systematic approach to solving a problem. The goal is todetermine why something does not work as expected and how to resolve theproblem. Certain common techniques can help with the task of troubleshooting.

The first step in the troubleshooting process is to describe the problem completely.Without a problem description, neither you or IBM® can know where to start tofind the cause of the problem. This step includes asking yourself basic questions,such as:v What are the symptoms of the problem?v Where does the problem occur?v When does the problem occur?v Under which conditions does the problem occur?v Can the problem be reproduced?

The answers to these questions typically lead to a good description of the problem,and that is the best way to start down the path of problem resolution.

What are the symptoms of the problem?

When starting to describe a problem, the most obvious question is "What is theproblem?" Which might seem like a straightforward question; however, you canbreak it down into several more-focused questions that create a more descriptivepicture of the problem. These questions can include:v Who, or what, is reporting the problem?v What are the error codes and messages?v How does the system fail? For example, is it a loop, hang, lock up, performance

degradation, or incorrect result?v What is the business impact of the problem?

Where does the problem occur?

Determining where the problem originates is not always simple, but it is one of themost important steps in resolving a problem. Many layers of technology can existbetween the reporting and failing components. Networks, disks, and drivers areonly a few components to be considered when you are investigating problems.

The following questions can help you to focus on where the problem occurs inorder to isolate the problem layer.v Is the problem specific to one platform or operating system, or is it common for

multiple platforms or operating systems?v Is the current environment and configuration supported?

Remember that if one layer reports the problem, the problem does not necessarilyoriginate in that layer. Part of identifying where a problem originates is


understanding the environment in which it exists. Take some time to completelydescribe the problem environment, including the operating system and version, allcorresponding software and versions, and hardware information. Confirm that youare running within an environment that is a supported configuration; manyproblems can be traced back to incompatible levels of software that are notintended to run together or have not been fully tested together.

When does the problem occur?

Develop a detailed timeline of events leading up to a failure, especially for thosecases that are one-time occurrences. You can most simply do this by workingbackward: Start at the time an error was reported (as precisely as possible, evendown to the millisecond), and work backward through the available logs andinformation. Typically, you need to look only as far as the first suspicious eventthat you find in a diagnostic log; however, this is not always simple to do andtakes practice. Knowing when to stop looking is especially difficult when multiplelayers of technology are involved, and when each has its own diagnosticinformation.

To develop a detailed timeline of events, answer the following questions:v Does the problem happen only at a certain time of day or night?v How often does the problem happen?v What sequence of events leads up to the time that the problem is reported?v Does the problem happen after an environment change, such as upgrading or

installing software or hardware?

Responding to these types of questions can provide you with a frame of referencein which to investigate the problem.

Under which conditions does the problem occur?

Knowing what other systems and applications are running at the time that aproblem occurs is an important part of troubleshooting. These and other questionsabout your environment can help you to identify the root cause of the problem:v Does the problem always occur when the same task is being performed?v Does a certain sequence of events need to occur for the problem to surface?v Do any other applications fail at the same time?

Answering these types of questions can help you explain the environment inwhich the problem occurs and correlate any dependencies. Remember that justbecause multiple problems might have occurred around the same time, theproblems are not necessarily related.

Can the problem be reproduced?

From a troubleshooting standpoint, the "ideal" problem is one that can bereproduced. Typically with problems that can be reproduced, you have a larger setof tools or procedures at your disposal to help you investigate. Consequently,problems that you can reproduce are often simpler to debug and solve. However,problems that you can reproduce can have a disadvantage: If the problem is ofsignificant business impact, you do not want it to recur! If possible, re-create theproblem in a test or development environment, which typically offers you moreflexibility and control during your investigation.

Tip: Simplify the scenario to isolate the problem to a suspected component.


The following questions can help you with reproducing the problem:v Can the problem be re-created on a test machine?v Are multiple users or applications encountering the same type of problem?v Can the problem be re-created by running a single command, a set of

commands, a particular application, or a stand-alone application?

Adapter returns version conflict exception messageAdapter returns version conflict exception message

Problem

When you install multiple adapters with different versions ofCWYBS_AdapterFoundation.jar, and if a lower version of theCWYBS_AdapterFoundation.jar is loaded during run time, the adapter returns theResourceAdapterInternalException error message, due to a version conflict. Forexample, when you install Oracle E-Business Suite adapter version 7.0.0.3 andWebSphere Adapter for Flat Files version 7.5.0.3, the following error message isdisplayed "The version of CWYBS_AdapterFoundation.jar is not compatible withIBM WebSphere Adapter for Flat Files" as IBM WebSphere Adapter for Flat Filesloads file:/C:/IBM/WebSphere/ProcServer7/profiles/ProcSrv01/installedConnectors/CWYOE_OracleEBS.rar/CWYBS_AdapterFoundation.jar withversion 7.0.0.3. However, the base level of this jar required is version 7.5.0.3. Toovercome this conflict, you must migrate all adapters to the same version level.

Solution

Migrate all adapters to the same version level.

For further assistance, visit http://www.ibm.com/support/docview.wss?uid=swg27006249.

Log and Trace AnalyzerThe adapter creates log and trace files that can be viewed with the Log and TraceAnalyzer.

The Log and Trace Analyzer can filter log and trace files to isolate the messagesand trace information for the adapter. It can also highlight the messages of anadapter and trace information in the log viewer.

The adapter's component ID for filtering and highlighting is a string composed ofthe characters FFRA plus the value of the adapter ID property. For example, if theadapter ID property is set to 001, the component ID is FFRA001.

If you run multiple instances of the same adapter, ensure that the first ninecharacters of the adapter ID property are unique for each instance so that you cancorrelate the log and trace information to a particular adapter instance. By makingthe first seven characters of an adapter ID property unique, the component ID formultiple instances of that adapter is also unique, allowing you to correlate the logand trace information to a particular instance of an adapter. For example, whenyou set the adapter ID property of two instances of WebSphere Adapter for FlatFiles to 001 and 002. The component IDs for those instances, FFRA001 and FFRA002,are short enough to remain unique, enabling you to distinguish them as separateadapter instances. However, instances with longer adapter ID properties cannot bedistinguished from each other. If you set the adapter ID properties of two instances

Chapter 8. Troubleshooting and support 151



to Instance01 and Instance02, you will not be able to examine the log and traceinformation for each adapter instance because the component ID for both instancesis truncated to FFRAInstance0.

For outbound processing, the adapter ID property is located in both the resourceadapter and managed connection factory property groups. If you update theadapter ID property after using the external service wizard to configure theadapter for outbound processing, be sure to set the resource adapter and managedconnection factory properties consistently. It prevents inconsistent marking of thelog and trace entries. For inbound processing, the adapter ID property is locatedonly in the resource adapter properties, so this consideration does not apply.

For more information, see the “Adapter ID (AdapterID)” on page 184 property.

Known issues in editing the Rule TableWhen configuring the adapter to filter event files based on a set of rules, someknown issues can occur while editing the Rule Table in the Properties view. Tocorrect the problem follow the solutions described here for each of these issues.

Symptoms

When an existing Rule Table row is configured in the Properties view, thefollowing issue can occur:

The Finish option is not enabled sometimes.

Problem

After you have completed entering all the required properties, the Finish option isnot enabled for you to complete the editing of the Rule Table.

Solution

To correct this problem, use either of the following workaround:v Use Tab to move between the fields.v Keep the focus away from the Value field either to Operator or the Property

field.

Support for global elements without wrapperWhen global element without wrapper is used as input type, you need to take careof using the correct configuration described for the below listed scenarios to getthe expected result.

Global element of named type without wrapper during outboundprocessing

When global element of named type without wrapper is used as input type inadapter outbound using UTF8XML Datahandler, the file is serialized with globalelement type name as root element name, instead of the global element name.

To serialize file to get the global element name as the root element name, you needto use the XML Datahandler and specify the global element name as the rootelement name in XML datahandler configuration.


Global element of anonymous type without wrapper

When global element of anonymous type without wrapper is used as input type inadapter inbound or outbound retrieve, the data object is emitted back to SCAcomponent. When this data object is serialized, it returns the type name ofdataobject as ‘globalelementname_._type'.

To get the correct data object type, in order to be used for a global element ofanonymous type without wrapper, for inbound as well as outbound retrieve, youneed to use the following code snippet.The following sample code can be used to get the correctdataobject details for global element of anonymous typewithout wrapper, which is named as GlobalElementExample1.

import java.io.ByteArrayOutputStream;import java.io.IOException;

import commonj.sdo.DataObject;import commonj.sdo.Type;

import com.ibm.websphere.bo.BOFactory;import com.ibm.websphere.bo.BOXMLSerializer;import com.ibm.websphere.sca.ServiceManager;

public void emit(DataObject globalElementExample1) {ServiceManager s = ServiceManager.INSTANCE;BOFactory factory= (BOFactory) s.locateService("com/ibm/websphere/bo/BOFactory");DataObject dobj= factory.createByElement(globalElementExample1.getType().getURI(), "GlobalElementExample1");final Type type = dobj.getType();String typeName = type.getName();if (typeName.endsWith("_._type"))

typeName = typeName.substring(0, typeName.indexOf("_._type"));BOXMLSerializer serializer = BOXMLSerializer)s.locateService("com/ibm/websphere/bo/BOXMLSerializer");ByteArrayOutputStream baos = new ByteArrayOutputStream();serializer.writeDataObject(globalElementExample1, type.getURI(), typeName, baos);String bo = new String(baos.toByteArray());System.out.println("bo : "+bo);}

Global elements in SDOX mode throw exceptionsIn SDOX (Service Data Objects - XML Cursor Interface) mode, the adapter throwsthe DataBindingException or IllegalArgumentException exception when the globalelement feature is used in the business object structure.

DataBindingException when using anonymous complex typeglobal element

The adapter throws a DataBindingException exception when running in SDOXmode during the outbound operations, if it uses the following settings:v The business object structure contains an anonymous complex type global

element with no name space definition, andv the business object is directly specified as the data type in outbound artifacts.

Note: The exception can occur when running the Create, Append, Overwrite, orRetrieve outbound operation.

The stack trace of WebSphere Adapter for Flat Files contains a trace report. Anexample of a trace report is shown here.


[12/3/09 10:26:00:156 CST] 00000058 FfdcProvider I com.ibm.ws.ffdc.impl.FfdcProvider logIncident FFDC1003I:FFDC Incident emitted on C:\W7\profiles\ProcSrv01\logs\ffdc\server1_71327132_09.12.03_10.26.00.1404512422641450978700.txt com.ibm.j2ca.flatfile.emd.runtime.FlatFileBaseDataBinding getBiDiContext[12/3/09 10:26:00:156 CST] 00000058 FfdcProvider I com.ibm.ws.ffdc.impl.FfdcProvider logIncident FFDC1003I:FFDC Incident emitted on C:\W7\profiles\ProcSrv01\logs\ffdc\server1_71327132_09.12.03_10.26.00.1564220276222456620949.txt com.ibm.j2ca.flatfile.emd.runtime.FlatFileBaseDataBinding getRecord[12/3/09 10:26:00:156 CST] 00000058 FFRADB E Error on getRecord(): commonj.connector.runtime.DataBindingException:Error while bidi formatat com.ibm.j2ca.flatfile.emd.runtime.FlatFileBaseDataBinding.getBiDiContext(FlatFileBaseDataBinding.java:1083)at com.ibm.j2ca.flatfile.emd.runtime.FlatFileBaseDataBinding.getRecord(FlatFileBaseDataBinding.java:134)

To correct the problem, while using anonymous complex type global element foroutbound operations, use the BOWrapper instead of business object as the data type.

IllegalArgumentException during the outbound operations

The adapter throws a IllegalArgumentException exception when running in SDOXmode during the outbound operations, if it uses the following settings:v The business object structure contains a global element, andv the BOWrapperBG is used as the data type in the outbound artifacts.

Note: The exception can occur when running the Create, Append, Overwrite, orRetrieve outbound operation.The stack trace of WebSphere Adapter for Flat Files contains a trace report. Anexample of a trace report is shown here.[12/8/09 18:22:00:906 CST] FFDC Exception:java.lang.IllegalArgumentException SourceId:com.ibm.j2ca.flatfile.emd.runtime.FlatFileBaseDataBinding ProbeId:getRecord Reporter:[email protected]: Expected a DataObject GlobalElementExample1Wrapperinside GlobalElementExample1WrapperBG but found none.at com.ibm.j2ca.extension.emd.runtime.internal.DataBindingUtil.getBOFromBG(DataBindingUtil.java:459)at com.ibm.j2ca.flatfile.emd.runtime.FlatFileBaseDataBinding.getContentObject(FlatFileBaseDataBinding.java:640)at com.ibm.j2ca.flatfile.emd.runtime.FlatFileBaseDataBinding.getRecord(FlatFileBaseDataBinding.java:118)at com.ibm.ws.sca.binding.j2c.J2CMethodBindingImpl.invoke(J2CMethodBindingImpl.java:1202)at com.ibm.ws.sca.binding.j2c.J2CInterfaceBindingImpl.invoke(J2CInterfaceBindingImpl.java:152)at com.ibm.ws.sca.binding.j2c.handler.J2CImportHandler.invokeDynamicImport(J2CImportHandler.java:1314)

To correct the problem, you can use either of the following workaround:v When running this scenario using a component to start the outbound operation,

use the BOWrapper instead of BOWrapperBG as the data type.v Call the outbound operations directly from the Java code, BPEL (Business

Process Execution Language), and other mediation flows.

First-failure data capture (FFDC) supportThe adapter supports first-failure data capture (FFDC), which provides persistentrecords of failures and significant software incidents that occur during run time inIBM Business Process Manager or WebSphere Enterprise Service Bus.

The FFDC feature runs in the background and collects events and errors that occurat run time. The feature provides a means for associating failures to one another,allowing software to link the effects of a failure to their causes, and facilitate thequick location of the root cause of a failure. The data that is captured can be usedto identify exception processing that occurred during the adapter run time.

When a problem occurs, the adapter writes exception messages and context data toa log file, which is in the install_root/profiles/profile/logs/ffdc directory.

For more information about first-failure data capture (FFDC), see the IBM BusinessProcess Manager or WebSphere Enterprise Service Bus documentation.


Incomplete file processing in UNIX environmentsIn UNIX environments, such as AIX, the files being copied to the event directoryare made available to the adapter for processing even before the files arecompletely copied. This leads to incorrect business data being sent to thedownstream components.

Symptoms:

This problem occurs due to absence of locking mechanism in the UNIXenvironments, when files are being written to a directory. The other applicationsare not prohibited during the copying process from accessing the files.

Problem:

During inbound polling, the adapter picks up the files that are not completelycopied, causing erroneous results because of processing of the incomplete files.

Solution:

To resolve this problem, use any one of the following workaround.v Use a staging directory to copy the event files. After the event files are copied in

the staging directory, use the Move command to transfer the file to the eventdirectory. You can use some of the sample UNIX scripts that are provided foryour use as part of the adapter. The script file named CheckIfFileIsOpen.sh isavailable in the UNIX script file folder in the adapter installer. The scriptperforms a check to see if a file is copied to the staging directory. After the filecopy is completed, the script moves the file to the event directory for furtherprocessing.

Note: The staging directory and event directory must be on the same filesystem.

v You can also use the Time interval for polling unchanged files (inmilliseconds) property to ensure that adapter processes the completely copiedfiles. This property enables the adapter to retrieve only those files that are notmodified in the event directory for a specified time interval. When this propertyis selected, the adapter retrieves only the unchanged files during the poll cycles.

Out of memory exception

Out of memory exception error while polling large-size filesduring inbound processing

Problem

During inbound polling, the adapter fails to poll large-size files and generates anout of memory exception error.

Solution

If you split an event file by size, ensure that the SplitCriteria property contains avalid chunk value. A non-negative integer is considered as a valid chunk. If thevalue in the SplitCriteria property is not configured, the whole file is processed asa single business object and can throw exceptions with large-size files. When youspecify the split size value, the file is processed in split sized chunks resulting in a


successful poll. For more information about the splitting of files, see “File splitting”on page 25.

Out of memory exception error while retrieving large-size filesduring outbound processing

Problem

When retrieving content for large-size files during the retrieve operation, theadapter generates an out of memory exception error.

Solution

If an out of memory exception error is generated, it indicates that the machineconfiguration does not support processing of large-size files. For more informationabout the retrieve operation, see “Retrieve operation” on page 7.

XAResourceNotAvailableExceptionWhen the IBM Process Server log contains repeated reports of thecom.ibm.ws.Transaction.XAResourceNotAvailableException exception, removetransaction logs to correct the problem.

Symptom:

When the IBM Process Server is started after a server failure, the followingexception is repeatedly logged in the IBM Process Server log file:

com.ibm.ws.Transaction.XAResourceNotAvailableException

The stack trace of WebSphere Adapter for Flat Files contains a trace report. Anexample of a trace report is shown here.00000015 XARecoveryDat W WTRN0005W: The XAResource for a transaction participantcould not be recreated and transaction recovery may not be able to complete properly.The resource was [email protected] exception stack trace follows: com.ibm.ws.Transaction.XAResourceNotAvailableException:java.security.PrivilegedActionException: java.lang.ClassNotFoundException:com.ibm.j2ca.flatfile.FlatFileResourceAdapterat com.ibm.ws.Transaction.JTA.ASXAResourceFactoryImpl.getXAResource(ASXAResourceFactoryImpl.java:97)at com.ibm.ws.Transaction.JTA.XARecoveryData.getXARminst(XARecoveryData.java:529)at com.ibm.ws.Transaction.JTA.XARecoveryData.recover(XARecoveryData.java:644)at com.ibm.ws.Transaction.JTA.PartnerLogTable.recover(PartnerLogTable.java:524)at com.ibm.ws.Transaction.JTA.RecoveryManager.resync(RecoveryManager.java:1859)at com.ibm.ws.Transaction.JTA.RecoveryManager.run(RecoveryManager.java:2580)at java.lang.Thread.run(Thread.java:810)Caused by: java.security.PrivilegedActionException: java.lang.ClassNotFoundException:com.ibm.j2ca.flatfile.FlatFileResourceAdapterat com.ibm.ws.security.util.AccessController.doPrivileged(AccessController.java:122)at com.ibm.ejs.j2c.RAWrapperImpl.createAndConfigureRA(RAWrapperImpl.java:2064)at com.ibm.ejs.j2c.RAWrapperImpl.startRA(RAWrapperImpl.java:584)at com.ibm.ejs.j2c.RAWrapperImpl.getStartedRA(RAWrapperImpl.java:1662)at com.ibm.ejs.j2c.ActivationSpecWrapperImpl.getStartedRA(ActivationSpecWrapperImpl.java:1368)at com.ibm.ws.Transaction.JTA.ASXAResourceFactoryImpl.getXAResource(ASXAResourceFactoryImpl.java:92)... 6 more

Problem:

A resource deployed at the node level was being removed and there was an abruptshutdown of the IBM Process Server. This results in killing the Java process while


the IBM Process Server was committing or rolling back a transaction for thatresource. When the IBM Process Server is restarted, it tries to recover thetransaction but cannot do so as the resource was removed.

Solution:

To correct this problem, use the following procedure:1. Reinstall the WebSphere Adapter for Flat Files at the node level.

Note: The IBM Process Server is already running, therefore you do need torestart it.

2. From the Process Administrative Console, restore all the activation specificationproperties. When adding the properties, you must use the same JNDI referencethat the adapter was referencing for the module.

3. Stop the IBM Process Server.4. Restart the IBM Process Server in the Recovery mode. In Process Administrative

Console, move to the bin directory of the IBM Process Server installation andtype the following command: startServer <server name> -recovery

Note: The IBM Process Server stops after the IBM Process Server recovery iscompleted.

5. Start the IBM Process Server in the normal mode.

Note: After the IBM Process Server is started, the event processing will startagain.

6. Verify the stack trace file to ensure that there is no occurrence of theXAResourceNotAvailableException exception.

Uninstall the WebSphere Adapter for Flat Files deployed at the node level

The XAResourceNotAvailableException exception can occur when there are sometypical events, such as deleting an adapter that has unprocessed events from theserver.1. Use the Process Administrative Console to stop all applications that are using

the adapter.2. Uninstall all the applications that are using the adapter.3. Uninstall the WebSphere Adapter for Flat Files.4. Stop and start the IBM Process Server.

Unable to invoke adapter through webservices

Problem

After configuring the adapter, you might note that:1. the webservices client based on the WSDL is not getting generated properly in

IBM Integration Designer.2. you may not be able to invoke the WSDL using certain webservices client, such

as RESTUI firefox plugin and soapUI tool.

Solution

Perform the following steps to enable the adapter module to load the ASI file.


1. Create a library project.2. Change to the Enterprise Explorer view in IBM Integration Designer.3. Locate the ASI file of the adapter in connector project -> connectorModule.4. Copy the ASI file of the adapter and paste it in the library project.5. Add the library project to the list of dependencies for the adapter module.6. Clean project.

org.xml.sax.SAXParseExceptionWhen the adapter is configured with the XML data handler, anorg.xml.sax.SAXParseException exception is generated if the content is not in thespecified business object format. To correct the problem, make sure the file contentmatches the business object structure. If the file contains multiple business objects,make sure the delimiter is specified correctly.

Symptom

When the adapter is configured with the XML data handler, the followingexception is thrown:

org.xml.sax.SAXParseException: Content is not allowed in trailing section

Problem

The content of the file is not in the specified business object format.

Solution

To correct this problem, use the following procedure:1. Make sure the file content matches the business object structure.2. If the content file contains multiple business objects, make sure the delimiter is

specified correctly.

Disabling end point applications of the passive adapter

Problem

In the active-passive configuration mode of the adapters, the endpoint applicationof the passive adapter instance also listens to the events or messages even if theenableHASupport property is set to True.

Cause

By default, in WebSphere Application Server, the alwaysactivateAllMDBs propertyin the JMS activation specification is set to True. This enables the endpointapplication of all the adapter (active or passive) instances to listen to the events.

Solution

To stop the endpoint application of the passive adapter instance from listening tothe events, you must set the alwaysactivateAllMDBs property value to False. TheJMS activation specification is associated with one or more MDBs and provides the


necessary configuration to receive events. If the alwaysActivateAllMDBs property isset to False, then the endpoint application of only the active adapter instancereceives the events.

Perform the following procedure, to set the alwaysActivateAllMDBs property toFalse.1. Log on to the Process Administrative Console.2. Go to Resources> JMS > Activation specifications.3. Click the activation specification corresponding to the application from the list.4. Click Custom properties under Additional properties.5. Click alwaysActivateAllMDBs.6. Change the value to False.7. Click Apply and OK.

Result

The endpoint application of only the active adapter instance listens to the events.

Solutions to common problemsSome of the problems you might encounter while running WebSphere Adapter forFlat Files with your database are described along with solutions and workaround.These problems and solutions are in addition to those documented as technotes onthe software support website.

For a complete list of technotes about WebSphere Adapters, seehttp://www.ibm.com/support/search.wss?tc=SSMKUK&rs=695&rank=8&dc=DB520+D800+D900+DA900+DA800+DB560&dtm.

Adapter throws an exception requesting users to migrate theirexisting tables

Problem

When you install the version 7.5.0.3 of the adapter without migrating the existingevent table structure with the same name as specified in the activation specificationproperties, the adapter throws an exception error at run time.

Solution

Migrate the existing event table while retaining the same table name as providedin the previous version of the activation specification properties. You can use thedatabase scripts available at <IID-HOME>\Resource Adapters\FlatFile_7.5.0.2\SQLScripts, to migrate the existing event table.

Use the script corresponding to your database:v scripts_db2_upgrade.sql – for DB2 and Derby databasev scripts_mssql_upgrade.sql – for Microsoft SQL Server databasev scripts_oracle_upgrade.sql – for Oracle database

For more information, see “Migrating databases” on page 45.




Frequently Asked QuestionsThis section provides you with answers to common questions about WebSphereAdapter for Flat Files.v “How to configure a local event directory and a sequence file in a clustered

environment?”v “Does WebSphere Adapter for Flat Files provide exclusive locking to files that

are processed by the adapter?”v “ How to check for access permissions in an output, remote event, or remote

archive directory in the UNIX environment?”v “What is HA Active-Active and Active-Passive configuration?” on page 161v “How to replace the adapter RAR file?” on page 161v “Does WebSphere Adapter for Flat Files support the staging directory with the

generateUniqueFile option?” on page 161

How to configure a local event directory and a sequence file in aclustered environment?

The local event directory and the sequence file must be configured in a mappeddrive to make it accessible by all nodes in the cluster. The user must have read andwrite permissions to the local event directory and the sequence files.

Does WebSphere Adapter for Flat Files provide exclusive lockingto files that are processed by the adapter?

No. The WebSphere Adapter for Flat Files does not have exclusive access to thefiles that are being processed. The process of locking or lack of locking on the filesis dependent on the operating system.

How to check for access permissions in an output, remote event,or remote archive directory in the UNIX environment?

To check if the user ID that the adapter uses has the right access permissions toaccess a server in the UNIX environment, the adapter performs the followingactions:v Check for the existence of the directories by using the following command:

cd <path>

v Go to parent directory by using the command:cd..

v Check for the permissions of the particular directory by using the followingcommand:ls –l

Note: The directory must have the read permissions. The ls –l listing mustconform to UNIX type listing. The event directory listed shows up in the listingwith the correct permissions.

v Go to the target directory by using the following command:Cd <target directory>

v Check for permissions of the files to be processed by using the followingcommand:ls –l


Note: The directory must have the read and write permissions.

What is HA Active-Active and Active-Passive configuration?

WebSphere Adapter for Flat Files supports High Availability (HA) Active-Activeconfiguration during inbound processing in a clustered environment.

An HA Active-Active configuration,v Enables all adapter instances deployed in a clustered environment to be active

and each instance is allowed to process the events independently.v Enables distribution of events to be processed between the available instances

without any duplicate events being delivered to the endpoint.v Improves the overall event handling performance in a clustered environment.

In a HA Active-Passive configuration,v Only one of the adapter instances starts polling for events.v Other adapter instances in the cluster are started but they remain in a dormant

state with respect to the active instance till the active instance is processing theevents.

v If the active instance of the adapter shuts down for some reason, one of thestandby instances in the cluster is made the active one.

How to replace the adapter RAR file?

The WebSphere Adapter for Flat Files RAR files can be replaced on the server sideby using the Process Administrative Console. The RAR file can be either a fix or anew version of the adapter. The following link contains a video with details aboutthe process http://publib.boulder.ibm.com/infocenter/ieduasst/v1r1m0/index.jsp?topic=/com.ibm.iea.wa_v7/wa/7.0/Overview/WBPMV70_IEA_Adapters_InstallRarOnServer/wbpmv70_iea_adapters_installraronserver_viewlet_swf.html.

Does WebSphere Adapter for Flat Files support the stagingdirectory with the generateUniqueFile option?

The combination of generateUniqueFile option and staging directory is not asupported combination. Ensure that staging directory is not specified, if you selectthe generateUniqueFile option.

SupportThis section provides information about how to troubleshoot a problem with yourIBM® software, including instructions for searching knowledge bases, downloadingfixes, and obtaining support.

Searching knowledge bases (Web search)You can often find solutions to problems by searching IBM knowledge bases. Youcan optimize your results by using available resources, support tools, and searchmethods.


http://publib.boulder.ibm.com/infocenter/ieduasst/v1r1m0/index.jsp?topic=/com.ibm.iea.wa_v7/wa/7.0/Overview/WBPMV70_IEA_Adapters_InstallRarOnServer/wbpmv70_iea_adapters_installraronserver_viewlet_swf.html




About this task

You can find useful information by searching the information center for Product X.However, sometimes you need to look beyond the information center to answeryour questions or resolve problems.

To search knowledge bases for information that you need, use one or more of thefollowing approaches:v Search for content by using the IBM® Support Assistant (ISA).

ISA is a no-charge software serviceability workbench that helps you answerquestions and resolve problems with IBM software products. You can findinstructions for downloading and installing ISA on the ISA website.

v Find the content that you need by using the IBM Support Portal.The IBM Support Portal is a unified, centralized view of all technical supporttools and information for all IBM systems, software, and services. The IBMSupport Portal lets you access the IBM electronic support portfolio from oneplace. You can tailor the pages to focus on the information and resources thatyou need for problem prevention and faster problem resolution. Familiarizeyourself with the IBM Support Portal by viewing the demo videos(https://www.ibm.com/blogs/SPNA/entry/the_ibm_support_portal_videos)about this tool. These videos introduce you to the IBM Support Portal, exploretroubleshooting and other resources, and demonstrate how you can tailor thepage by moving, adding, and deleting portlets.

v Search for content by using the IBM masthead search. You can use the IBMmasthead search by typing your search string into the Search field at the top ofany ibm.com® page.

v Search for content by using any external search engine, such as Google, Yahoo,or Bing. If you use an external search engine, your results are more likely toinclude information that is outside the ibm.com domain. However, sometimesyou can find useful problem-solving information about IBM products innewsgroups, forums, and blogs that are not on ibm.com.

Tip: Include "IBM" and the name of the product in your search if you are lookingfor information about an IBM product.

Getting FixesA product fix might be available to resolve your problem.

About this task

To get product fixes, perform the following steps.

Procedure1. Determine which fix you need. Check the list of IBM WebSphere Adapter for

Flat Files recommended fixes to confirm that your software is at the latestmaintenance level. Check the list of problems fixed in the IBM WebSphereAdapter for Flat Files fix readme documentation that is available for each listedfix pack to see if IBM has already published an individual fix to resolve yourproblem. To determine what fixes are available using IBM Support Assistant,run a query on fix from the search page.Individual fixes are published as often as necessary to resolve defects in IBMBusiness Process Manager or WebSphere Enterprise Service Bus IBMWebSphere Adapter for Flat Files. In addition, two kinds of cumulative


http://www-01.ibm.com/software/support/isa/

http://www-947.ibm.com/support/entry/portal/Overview/

collections of fixes, called fix packs and refresh packs, are publishedperiodically for IBM WebSphere Adapter for Flat Files, in order to bring usersup to the latest maintenance level. You should install these update packages asearly as possible in order to prevent problems.

Note: A list of recommended, generally available (GA) fixes for the WebSphereJava™ Connector Architecture (JCA) and WebSphere Business Integrationadapters are available here. If a Fix Pack is not available for an adapter, itimplies that the GA version is the recommended version and details about thatversion of the adapter can be found in the Release notes.

2. Download the fix. Open the download document and follow the link in theDownload package section. When downloading the file, ensure the name of themaintenance file is not changed. This includes both intentional changes andinadvertent changes caused by certain web browsers or download utilities.

3. Apply the fix. Follow the instructions in the Installation Instructions section ofthe download document.

4. Optional: To receive weekly notification of fixes and updates, subscribe to MySupport e-mail updates.

Self-help resourcesUse the resources of IBM software support to get the most current supportinformation, obtain technical documentation, download support tools and fixes,and avoid problems with WebSphere Adapters. The self-help resources also helpyou diagnose problems with the adapter and provide information about how tocontact IBM software support.

Support website

The WebSphere Adapters software support website at http://www.ibm.com/support/docview.wss?uid=swg27006249 provides links to many resources to helpyou learn about, use, and troubleshoot WebSphere Adapters, including:v Flashes (alerts about the product)v Technical information including the product information center, manuals, IBM

Redbooks®, and whitepapersv Educational offeringsv Technotes

Recommended fixes

A list of recommended fixes you must apply is available at the following location:http://www.ibm.com/support/docview.wss?fdoc=aimadp&rs=695&uid=swg27010397.

Technotes

Technotes provide the most current documentation about WebSphere Adapter forFlat Files, including the following topics:v Problems and their currently available solutionsv Answers to frequently asked questionsv How to information about installing, configuring, using, and troubleshooting the

adapterv IBM Software Support Handbook

For a list of technotes for WebSphere Adapter for Flat Files, seehttp://www-01.ibm.com/support/docview.wss?uid=swg27024018.


http://www-01.ibm.com/support/docview.wss?uid=swg27010397#jca70



http://www.ibm.com/support/docview.wss?fdoc=aimadp&rs=695&uid=swg27010397

http://www.ibm.com/support/docview.wss?fdoc=aimadp&rs=695&uid=swg27010397

http://www-01.ibm.com/support/docview.wss?uid=swg27024018

For a list of technotes for all adapters, see http://www.ibm.com/support/search.wss?tc=SSMKUK&rs=695&rank=8&dc=DB520+D800+D900+DA900+DA800+DB560&dtm.





Chapter 9. Reference information

To support you in your tasks, reference information includes details about businessobjects that are generated by the external service wizard and information aboutadapter properties, including those that support bidirectional transformation. Italso includes pointers to adapter messages and related product information.

Business object informationYou can determine the purpose of a business object by examining both theapplication-specific information within the business object definition file and thename of the business object. The application-specific information dictates whatoperations can be performed on the local file system. The name typically reflectsthe operation to be performed and the structure of the business object.

Business object structuresThe WebSphere Adapter for Flat Files defines and generates business objectsduring external service. The business object structure is based on the genericWebSphere Business Integration business object structure, which is modeled as abase XML schema.

Generic FlatFileBG object

Two types of business objects are generated during enterprise metadata discovery:content-specific and generic.

The generic FlatFileBG business object is used for generic XSD files (for example,UnstructuredContent). The FlatFileBG business object is a wrapper business objectthat contains the FlatFile business object as a child. The following graphicillustrates this relationship:

Figure 72. The generic FlatFileBG business object structure


CustomerWrapperBG object

In this example, CustomerWrapperBG represents a content-specific XSD file. TheCustomerWrapperBG is a wrapper business object that contains theCustomerWrapper business object as a child. The following graphic illustrates thisrelationship:

Append operation with business graph response business object

Create operation with business graph response business object

Figure 73. The CustomerWrapperBG business object structure

Figure 74. Structure of the Append operation response business object

Figure 75. Structure of the Create operation response business object


Delete operation with business graph response business object

Exists operation with business graph response business object

List operation with business graph response business object

Overwrite operation with business graph response businessobject

Figure 76. Structure of the Delete operation response business object

Figure 77. Structure of the Exists operation response business object

Figure 78. Structure of the List operation response business object

Figure 79. Structure of the Overwrite operation response business object

Chapter 9. Reference 167

Retrieve operation with business graph response businessobject

Global elements in a structured business object

The WebSphere Adapter for Flat Files supports global elements in structuredbusiness objects. Global elements with null namespace are also supported.

The CustomerType1 is the global element in the business object.

The CustomerInventory is the global element in the business object.

Figure 80. Structure of the Retrieve operation response business object

Figure 81. Structure of the global elements in a structured Business Object


Attribute propertiesBusiness object architecture defines various properties that apply to attributes. Thissection describes how the adapter interprets these properties.

The following table describes these properties.

Table 12. Attribute properties

Attribute property Description

Cardinality Each business object attribute that representsa child or an array of child business objectshas the value of single (1) or multiple (n)cardinality. Only single cardinality flatbusiness objects are supported.

Key and foreign key These attributes are not used by the adapter.

Name Represents the unique name of the attribute.

Required This attribute is not used by the adapter.

Type The attribute type can be either simple orcomplex. Simple types are: Boolean, String,LongText, Integer, Float, Double, and Byte[ ].A typical complex type is another businessobject type.

Naming conventionsWhen the external service wizard generates a business object, it provides a namefor the business object based on the name of the object in the local file system thatit uses to build the business object.

When the external service wizard provides a name for the business object, itconverts the name of the object to mixed case, which means that it removes anyseparators, such as spaces or underscores, and then capitalizes the first letter ofeach word. For example, if the external service wizard uses a local file systemobject called CUSTOMER_ADDRESS to generate a business object, it generates abusiness object called CustomerAddress.

The generated business object name can indicate the structure of the businessobject. However, business objects names have no semantic value to the adapter,that is, if you change the business object name, the behavior of the business objectremains the same.

Important: If you want to rename a business object, use the refactoringfunctionality in IBM Integration Designer to ensure that you update all thebusiness object dependencies. For instructions on using refactoring to renamebusiness objects, refer to the following link: http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5mx/topic/com.ibm.wbpm.wid.bpel.doc/selector/topics/trefacts.html.

The following table describes the naming conventions that the external servicewizard uses when it generates business objects for the WebSphere Adapter for FlatFiles.


http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5mx/topic/com.ibm.wbpm.wid.bpel.doc/selector/topics/trefacts.html



Table 13. Naming conventions

Element Naming convention Example

Name ofthebusinessgraph

The business graph that contains theparent business object is named forthe contained business object,followed by the string BG. There canbe a business graph only if there is awrapper. CustomerWrapperBG is awrapper business object that containsthe CustomerWrapper business objectas a child.

CustomerWrapperBG

Note: Business graph generation is optional and is supported for IBM BusinessProcess Manager or WebSphere Enterprise Service Bus only.

Business faultsThe adapter supports business faults, which are exceptions that are anticipated anddeclared in the outbound service description, or import. Business faults occur atpredictable points in a business process, and are caused by a business ruleviolation or a constraint violation.

Although IBM Business Process Manager and WebSphere Enterprise Service Bussupport other types of faults, the adapter generates only business faults, which arecalled faults in this documentation. Not all exceptions become faults. Faults aregenerated for errors that are actionable, that is, errors that can have a recoveryaction that does not require the termination of the application. For example, theadapter generates a fault when it receives a business object for outboundprocessing that does not contain the required data or when the adapter encounterscertain errors during outbound processing.

Fault business objects

The external service wizard creates a business object for each fault that the adaptercan generate. Also, the wizard creates a WBIFault superset business object, whichhas information common to all faults, such as the message, errorCode, andprimaryKeySet attributes as shown in Figure 82.

Some faults contain the matchCount attribute, to provide additional informationabout the error. For others, WBIFault contains all the information needed to handlethe fault.

The WebSphere Adapter for Flat Files enables faults for you. Manual configurationof faults is not required. The adapter provides the following fault business objectsthat the wizard creates:

Figure 82. The structure of the WBIFault business object


v DuplicateRecordFaultThis fault is generated during the outbound Create operation when the fileexists in the specified directory.

v RecordNotFoundFaultThis fault is generated during Append, Delete, Overwrite, and Retrieveoperations when the file does not exist in the specified directory.

v MissingDataFaultIf the business object that is passed to the outbound operation does not have allthe required attributes, the adapter returns this fault. This fault can occur for theCreate, Delete, Update, Retrieve, ApplyChanges and Exists operations.For example, the adapter throws this fault if the content of the specified file isnull, or the file name or directory path is empty.

Custom file splittingYou can implement a custom class containing the splitting logic. The adapterprovides a Java interface for the class. The version 7.5.0.3 of the adapter providesinterfaces for both outbound and inbound processes.

Interface for outbound operations

Use the com.ibm.j2ca.utils.filesplit.SplittingFunctionalityInterfaceinterface for the outbound operations.

Following are the details of the interface:public interface SplittingFunctionalityInterface extends Iterator{

public int getTotalBOs(String filename) throws SplittingException;public void setBODetails(String filename, int currentPosition, int totalBOs,

boolean includeEndBODelimiter) throws SplittingException;public void setSplitCriteria(String splitCriteria);public void setEncoding(String encoding);public void setLogUtils(LogUtils logUtils);

public boolean isSplitBySize()}

v public int getTotalBOs(String filename) throws SplittingException

This method returns the total number of business objects present in the eventfile given by filename.

v public void setSplitCriteria(String splitCriteria)

This method takes the splitCriteria, that is based on the number of businessobjects in the event file. Each business object is returned during the next() call.

v public void setLogUtils(LogUtils logUtils)

This method is used to set the LogUtils object, which is the class that the usercan use to write trace and log messages to the files.

v public void setEncoding(String encoding)

This method is used to set the encoding of the event file content. This encodingis used while reading the file content. This encoding is also used for theSplitCriteria.

v public void setBODetails(String filename, int currentPosition, inttotalBOs, boolean includeEndBODelimiter) throws SplittingException

This method is used to set the current business object number so that whenevera next() call is made, the business object number set in the currentPosition isreturned. It also takes an includeEndBODelimiter parameter, which when set totrue, includes the SplitCriteria at the end of the business object content. This


method must be called before every next() call so that the next() methodreturns the business object content for the business object set in this method.

v The iterator has three methods: hasNext(), next, and remove(), that also must beimplemented. The next() method returns the business object content (as abyte[]) for the business object position set in setBODetails(). If the businessobject position is not set, it fails. The hasNext() method indicates whether thebusiness object position set in the setBODetails() exists or not. Before ahasNext() call, the setBODetails() method must be called. The remove() methodis called for each of the business object entries being deleted from the Eventpersistence table. Do not delete the event file in this method, and clean up onlythe resources that are being used.

v public boolean isSplitBySize()

This method indicates whether the event file is parsed based on size or based ondelimiter.

Interface for inbound operations

Use the com.ibm.j2ca.utils.filesplit.InboundSplittingFunctionalityInterfaceinterface for the inbound operations.

Note: The custom splitting class for an inbound operation created in the earlierversion of the adapter does not work with the version 7.5.0.3 of the adapter.

Following are the details of the interface:public interface InboundSplittingFunctionalityInterface{public Hashtable getBOs(String filename,int quantity, long lastBO,long lastBOPos,boolean withDelim) throws SplittingException,MissingDataException;public void setBODetails(String filename, long currentBO, long startPos, long endPos) throws SplittingException;public Object getBOContent();public boolean hasMoreBO();public void remove();public void setSplitCriteria(String splitCriteria);public void setEncoding(String encoding);public void setLogUtils(LogUtils logUtils);public boolean isSplitBySize();}

v public Hashtable getBOs(String filename, int quantity, long lastBOCount,long lastBOPos, boolean includeEndBODelimiter) throws SplittingException,MissingDataException

This method returns the business objects retrieved from the file specified in thefilename to a hashtable. The quantity parameter specifies the number ofbusiness objects to be retrieved. The lastBOCount parameter specifies the numberof business objects retrieved when the file was previously read. The lastBOPosparameter specifies the end position of the business object when the file waspreviously read. The includeEndBODelimiter parameter specifies the split criteriato retrieve the business objects. The hashtable that is returned contains thebusiness object count (key) and the start/end positions of that business object (along array of 2 elements).

v public void setBODetails(String filename, long currentBO, longstartPosition, long endPosition)throws SplittingException

This method is used to set the details for the current business object. Therefore,the getBOContent() method retrieves the content of the business object specifiedin the currentBO. The startPosition and endPosition parameters specify thestart and end position for the business object in the file.

v public Object getBOContent()


The getBOContent() method returns the business object content (as a byte[]) forthe details set in setBODetails() method. If the start and end position of thebusiness object is not set in the setBODetails() method, then the getBOContent()method fails.

v public boolean hasMoreBO()

This method returns the value True if there are unread business objects existingin the file after the last call to the getBOs() method.

v public void remove()

The remove() method is called for each of the business object entry beingdeleted from the Event persistence table. Ensure that you do not delete the eventfile and clean up only the resources that are being used.

v public void setSplitCriteria(String splitCriteria)

This method returns the splitCriteria set based on the number of businessobjects in the event file. Each business object is returned during the next() call.

v public void setLogUtils(LogUtils logUtils)

This method is used to set the LogUtils object, which is the class used to writetrace and log messages to the files.

v public void setEncoding(String encoding)

This method is used to set the encoding for the content of the event file. Thisencoding is used while reading the file content and for the SplitCriteria.

v public boolean isSplitBySize()

This method returns the value True when the event file is parsed based on thesize, and returns the value False if a delimiter is used.

Configuration propertiesIBM WebSphere Adapter for Flat Files has several categories of configurationproperties, which you set with the external service wizard while generating orcreating objects and services. You can change the resource adapter, managedconnection factory, and activation specification properties after you deploy theapplication to IBM Business Process Manager or WebSphere Enterprise Service Bus.

Outbound configuration propertiesIBM WebSphere Adapter for Flat Files has several categories of outboundconnection configuration properties, which you set with the external service wizardwhile generating or creating objects and services. You can change the resourceadapter and managed connection factory properties after you deploy the moduleto IBM Business Process Manager or WebSphere Enterprise Service Bus using IBMIntegration Designer or the Process Administrative Console, but connectionproperties for the external service wizard cannot be changed after deployment.

Guide to information about propertiesThe properties used to configure WebSphere Adapter for Flat Files are described indetail in tables included in each of the configuration properties topics, such asResource adapter properties, Managed connection factory properties, and so on. Tohelp you use these tables, information about each row you might see is explainedhere.

The following table explains the meaning of each row that might be displayed inthe table for a configuration property.


Row Explanation

Required A required field (property) must have a value in order for the adapter to work.Sometimes the external service wizard provides a default value for requiredproperties.

Removing a default value from a required field on the external service wizardwill not change that default value. When a required field contains no value at all,the external service wizard processes the field using its assigned default value,and that default value is displayed on the Process Administrative Console.

Possible values are Yes and No.

Sometimes a property is required only when another property has a specificvalue. When this is the case, the table notes this dependency. For example,

v Yes, when the EventQueryType property is set to Dynamic

v Yes, for Oracle databases

Possible values Lists and describes the possible values that you can select for the property.

Default The predefined value that is set by the external service wizard. When theproperty is required, you must either accept the default value or specify oneyourself. If a property has no default value, the table states No default value.

The word None is an acceptable default value, and does not mean that there isno default value.

Unit of measure Specifies how the property is measured, for example in kilobytes or seconds.

Property type Describes the property type. Valid property types include:

v Boolean

v String

v Integer

Usage Describes usage conditions or restrictions that might apply to the property. Forinstance, here is how a restriction would be documented:

For Rational® Application Developer for WebSphere Software version 6.40 orearlier, the password:

v Must be uppercase

v Must be 8 characters in length

For versions of Rational Application Developer for WebSphere Software laterthan 6.40, the password:

v Is not case-sensitive

v Can be up to 40 characters in length.

This section lists other properties that affect this property or the properties thatare affected by this property and describes the nature of the conditionalrelationship.

Example Provides sample property values, for example:

"If Language is set to JA (Japanese), code page number is set to 8000".

Globalized If a property is globalized, it has national language support, meaning that youcan set the value in your national language.

Valid values are Yes and No.


Row Explanation

Bidi supported Indicates whether the property is supported in bidirectional (bidi) processing.Bidirectional processing refers to the task of processing data that contains bothright-to-left (Hebrew or Arabic, for example) and left-to-right (a URL or filepath, for example) semantic content within the same file.


Connection properties for the wizardConnection properties are used to build a service description and save the built-inartifacts. These properties are configured in the external service wizard.

The following table lists the connection properties for the external service wizard.These properties can only be configured using the external service wizard andcannot be changed after deployment. A complete description of each property isprovided in the sections that follow the table. For information about how to readthe property detail tables in the sections that follow, see “Guide to informationabout properties” on page 173.

Table 14. Connection properties for the external service wizard

Property name in the wizard Description

“Bidi format string” The bidi format string of the content data.

“Data binding” Specifies the data binding that is to be used for alloperations or specifies that a data binding is to beselected for each operation.

“Log file output location” on page 176 The full path name of the log file generated by theexternal service wizard.

“Logging level” on page 176 Specifies the level of logging to be used by the adapter.

“NameSpace” on page 176 The namespace of the business object that is generated.

“Operation name” on page 177 The operation defined in the external service wizard.

“Processing Direction” on page 177 The processing direction, Inbound or Outbound.

Bidi format string

The bidi format string of the content data.

Table 15. Bidi format string

Required No

Default None

Property type String

Data binding

Specifies the data binding that is to be used for all operations or specifies that adata binding is to be selected for each operation.

Table 16. Data binding details

Required No

Default Use default data binding 'FlatFileBaseDataBinding' for all operations


Table 16. Data binding details (continued)

Usage The value of this property can be:

v Use default data binding 'FlatFileBaseDataBinding' for all operations

v Use a data binding configuration for all operations

v Specify a data binding for each operation

Globalized No

Bidi supported No

Log file output location

The full path name of the log file generated by the external service wizard.

Table 17. Log file output location details

Required No

Default \.metadata \FlatFileMetadataDiscoveryImpl.log


Usage

Globalized No

Bidi supported No

Logging level

Specifies the level of logging to be used by the adapter.

Table 18. Logging level details

Required No

Possible values SevereWarningAuditInfoConfigDetail

Default Severe

Property type List of values

Globalized No

Bidi supported No

NameSpace

The namespace of the business object that is generated.

Table 19. NameSpace details

Required Yes

Default http://www.ibm.com/xmlns/prod/websphere/j2ca/flatfile


Globalized Yes

Bidi supported No


http://www.ibm.com/xmlns/prod/websphere/j2ca/flatfile

Operation name

The name you give to the operation defined for this module.

Table 20. Operation name details

Required No

Default When the ServiceType property is set to Outbound, the operations listed are Create, Append,Retrieve, Delete, List, Overwrite, and Exists.


Globalized No

Bidi supported No

Processing Direction

The processing direction, inbound or outbound.

Table 21. Processing Direction details

Required Yes

Possible values OutboundInbound

Default Outbound


Globalized No

Bidi supported No

Managed connection factory propertiesManaged connection factory properties specify information the adapter needs atrun time for outbound communication with the local file system.

The following table lists the managed connection factory properties for outboundcommunication. You set the managed connection factory properties using theexternal service wizard and can change them using the IBM Integration DesignerAssembly Editor, or after deployment through the IBM Business Process Manageror WebSphere Enterprise Service Bus Process Administrative Console.

A more detailed description of each property is provided in the sections thatfollow the table. For information about how to read the property details tables inthe sections that follow, see “Guide to information about properties” on page 173.

Note: The external service wizard refers to these properties as managed connectionfactory properties and the IBM Business Process Manager or WebSphere EnterpriseService Bus Process Administrative Console refers to them as (J2C) connectionfactory properties.

Table 22. Managed connection factory properties

Property name

DescriptionIn the wizardIn the ProcessAdministrative Console

Adapter ID AdapterID Identifies the adapter instance for PMI events and forlogging and tracing.


Table 22. Managed connection factory properties (continued)

Property name


“Default target file name” onpage 180

OutputFileName Specifies the name of the file that is created in theoutput directory, or a WebSphere Application Serverenvironment variable that represents this file.

Disguise user data as "XXX"in log and trace files

HideConfidentialTrace Specifies whether to disguise potentially sensitiveinformation by writing X strings instead of user data inthe log and trace files.

“Generate a unique file” onpage 180

GenerateUniqueFile Specifies that the adapter creates a unique file duringCreate, Append, and Overwrite operations.

“Prefix for the unique filename” on page 180

uniqueFilePrefix Specifies the predefined prefix that is added to thegenerated unique file name during outboundoperations.

“Output directory” on page181

OutputDirectory Specifies the full path name of the directory where theadapter creates files during outbound operations, or aWebSphere Application Server environment variablethat represents this directory.

“Sequence file” on page 181 FileSequenceLog Specifies the full path name of the file wheresequences are stored during outbound Createoperations, or a WebSphere Application Serverenvironment variable that represents this file.

“Staging directory” on page182

StagingDirectory The full path name of the temporary directory wherethe adapter writes the initial output files for Createand Overwrite operations during outbound processing,or a WebSphere Application Server environmentvariable that represents this directory.

“Suffix for the unique filename” on page 183

uniqueFileSuffix Specifies the predefined suffix that is added to thegenerated unique file name during outboundoperations.

Adapter ID (AdapterID)

This property identifies a specific deployment or instance of the adapter.

Table 23. Adapter ID details

Required Yes

Default 001



Table 23. Adapter ID details (continued)

Usage This property identifies the adapter instance in the log and trace files, and also helpsidentify the adapter instance while monitoring adapters. The adapter ID is used with anadapter-specific identifier, FFRA, to form the component name used by the Log and TraceAnalyzer tool. For example, if the adapter ID property is set to 001, the component ID isFFRA001.

If you run multiple instances of the same adapter, ensure that the first nine characters ofthe adapter ID property are unique for each instance so that you can correlate the log andtrace information to a particular adapter instance. By making the first seven characters ofan adapter ID property unique, the component ID for multiple instances of that adapter isalso unique, allowing you to correlate the log and trace information to a particular instanceof an adapter.

For example, when you set the adapter ID property of two instances of WebSphere Adapterfor Flat Files to 001 and 002. The component IDs for those instances, FFRA001 and FFRA002,are short enough to remain unique, enabling you to distinguish them as separate adapterinstances. However, instances with longer adapter ID properties cannot be distinguishedfrom each other. If you set the adapter ID properties of two instances to Instance01 andInstance02, you will not be able to examine the log and trace information for each adapterinstance because the component ID for both instances is truncated to FFRAInstance0.

For inbound processing, the value of this property is set at the resource adapter level. Foroutbound processing, the value can be set both at the resource adapter level and themanaged connection factory level. After you use the external service wizard to configurethe adapter for outbound processing, you can set the resource adapter and managedconnection factory properties independently. If you use the IBM Integration Designerassembly editor or the administrative console to reset these properties, ensure that you setthem consistently, to prevent inconsistent marking of the log and trace entries.

Globalized Yes

Bidi supported No

Disguise user data as "XXX" in log and trace files(HideConfidentialTrace)

This property specifies whether to replace user data in log and trace files with astring of X's to prevent unauthorized disclosure of potentially sensitive data.

Table 24. Disguise user data as "XXX" in log and trace files details

Required No

Possible values TrueFalse

Default False

Property type Boolean

Usage If you set this property to True, the adapter replaces user data with a string of X's whenwriting to log and trace files.


Globalized No


Table 24. Disguise user data as "XXX" in log and trace files details (continued)

Bidi supported No

Default target file name

The name of the file that is created in the output directory, or a WebSphereApplication Server environment variable that represents this file.

Table 25. Default target file name details

Required No

Default None


Usage If a value for OutputFileName is specified in the record object, this value is overridden. Youcan use a WebSphere Application Server environment variable to represent the default targetfile name. Specify the name of the environment variable in braces, preceded by a $ symbol. Forexample: ${OUTPUT_FILENAME}. See the topic on creating an environment variable in thisdocumentation.

Globalized Yes

Bidi supported Yes

Generate a unique file

Specifies that the adapter creates a unique file during the Create operation.

Table 26. Generate unique file property details

Required No


Default False


Usage During Create operations, if this property is set to True, the adapter creates a unique file andignores any value set for the Filename property.Note: If a value is not specified for this property on the wrapper, then the value specified hereis used.

Globalized Yes

Bidi supported No

Prefix for the unique file name

The prefix for the unique file name that you predefine for outbound operations.

Table 27. Prefix for the unique file name details

Required No

Default None



Table 27. Prefix for the unique file name details (continued)

Usage You can define the prefix to be added when the adapter generates the unique file name duringthe outbound operations. The length of the prefix must be of minimum three letters. Forexample, abc can be used as a predefined prefix for the unique file name.Note: If you do not specify the prefix, the adapter automatically adds the prefix ffa to the filename.

Globalized No

Bidi supported No

Output directory

The full path name of the directory where the adapter creates files duringoutbound operations, or a WebSphere Application Server environment variable thatrepresents this directory.

Table 28. Output directory details

Required No

Default None


Usage The output directory is used by the adapter to write the final output files. You can use aWebSphere Application Server environment variable to represent the output directory. Specifythe name of the environment variable in braces, preceded by a $ symbol. For example:${OUTPUT_DIRECTORY}. See the topic on creating an environment variable in this documentation.

Globalized Yes

Bidi supported Yes

Sequence file

This property specifies the full path name of the file where sequences are storedduring outbound Create operations, or a WebSphere Application Serverenvironment variable that represents this file.

Table 29. Sequence file details

Required No

Default None



Table 29. Sequence file details (continued)

Usage When the adapter receives a Create request, it checks the file sequence log to see whether a filewith the specified name exists. If there is a file with that name, the adapter uses the filesequence number to create a file name. For example, if the output file name in the request isCustomer.txt, the adapter creates a file with the name Customer.n.txt, where n is the sequencenumber. If the output file name does not have an extension, the sequence is appended at theend of the file name; for example, Customern. All sequences begin with 1.

If this property is not specified, and the adapter receives a request to create a file with a namethat exists, the adapter generates a DuplicateRecordException error.

The sequence number continues to increment after an adapter restart. You can reset the filesequence by changing the sequence value in the sequence file.

Notes®:

1. To generate file sequencing for a particular request type, set the output directory and thefile name at the managed connection level.

2. When the adapter is working in a clustered environment, make sure that the sequence file ison a mapped drive that is accessible by all the clusters. The adapter must have writepermission for the sequence log file, or an IOException error is returned.Note: In the Windows operating systems, such as, Windows 7, Windows Vista, andWindows Server 2008, there are issues faced in the mapped drive connection. Due to thisissue, in a clustered environment, where the nodes are running on different machines, thefiles in the mapped event directory might not be processed correctly during outboundoperations. For more information about working with mapped drives, refer to articles onmapped drive connection to network sharing, for your operating system.

3. If the FileSequenceLog property is specified and the GenerateUniqueFile property isenabled, the GenerateUniqueFile property takes precedence over the FileSequenceLogproperty.

4. The directory path and file name, if specified in the business object, take precedence overthe values specified at the managed connection level.

You can use a WebSphere Application Server environment variable to represent the sequencefile. Specify the name of the environment variable in braces, preceded by a $ symbol. Forexample: ${SEQUENCE_FILE}. See the topic on creating an environment variable in thisdocumentation.Important: Unless they are part of a cluster, two adapter instances must not use the samesequence file, because it might result in delayed processing of batch requests.

Globalized Yes

Bidi supported Yes

Staging directory

The full path name of the temporary directory where the adapter writes the initialoutput files for Create and Overwrite operations during outbound processing, or aWebSphere Application Server environment variable that represents this directory.

Table 30. Staging directory details

Required No

Default None



Table 30. Staging directory details (continued)

Usage If this property is specified, the output file is first written to a staging directory and thenrenamed to the output directory. The adapter temporarily stores the initial output files forCreate and Overwrite operations in the staging directory to avoid write conflicts duringoutbound processing.

You can use a WebSphere Application Server environment variable to represent the stagingdirectory. Specify the name of the environment variable in braces, preceded by a $ symbol. Forexample: ${STAGING_DIRECTORY}. See the topic on creating an environment variable in thisdocumentation.

Globalized Yes

Bidi supported Yes

Suffix for the unique file name


Table 31. Suffix for the unique file name details

Required No

Default None


Usage You can define the suffix (file extension) to be added when the adapter generates the uniquefile name during the outbound operations.Note: If you do not specify the file extension, the adapter automatically adds the .tmpextension to the file name.

Globalized No

Bidi supported No

Resource adapter propertiesThe resource adapter properties control the general operation of the adapter, suchas specifying the namespace for business objects. You set the resource adapterproperties using the external service wizard when you configure the adapter. Afterdeploying the adapter, use the Process Administrative Console to change theseproperties.

The following properties for logging and tracing are no longer required in version6.1.0. They are visible from the Process Administrative Console for compatibilitywith previous versions.v LogFileMaxSizev LogFileNamev LogNumberOfFilesv TraceFileMaxSizev TraceFileNamev TraceNumberOfFiles

The following table lists the resource adapter properties and their purpose. Acomplete description of each property is provided in the sections that follow thetable. For information about how to read the property detail tables in the sectionsthat follow, see “Guide to information about properties” on page 173.


Table 32. Resource adapter properties for the WebSphere Adapter for Flat Files

Name





(Not available) Enable HA support Do not change this property.

(Not available) LogFileSize Deprecated

(Not available) LogFilename Deprecated

(Not available) LogNumberOfFiles Deprecated

(Not available) TraceFileSize Deprecated

(Not available) TraceFileName Deprecated

(Not available) TraceNumberOfFiles Deprecated




Required Yes

Default 001








Globalized Yes

Bidi supported No




Required No


Default False




Globalized No

Bidi supported No

Enable high availability support (enableHASupport)

Do not change this property. It must be set to true.

Interaction specification propertiesInteraction specification properties contain the outbound connection properties theadapter uses to interface with the file system. You configure these properties usingthe external service wizard. To change the interaction specification properties afterthe application is deployed, use the assembly editor in IBM Integration Designer.

Interaction specification properties control the interaction for an operation. Theexternal service wizard sets the interaction specification properties when youconfigure the adapter. Typically, you do not need to change these properties.However, some properties for outbound operations can be changed by the user. Tochange these properties after the application is deployed, use the assembly editorin IBM Integration Designer. The properties reside in the method binding of theimport.

The following table lists the interaction specification properties. A completedescription of each property is provided in the sections that follow the table. Forinformation about how to read the property detail tables in the sections that follow,see “Guide to information about properties” on page 173.


Table 35. Interaction specification properties

Property name


“Archive directory forretrieve operation”

ArchiveDirectoryForDeleteOnRetrieve

The directory where retrieved files are stored beforethey are deleted, if the DeleteOnRetrieve property isset to true.

“Create a new file if the filedoes not exist” on page 187

CreateFileIfNotExists When this property is set to true, the adapter creates afile during Append and Overwrite operations if the filedoes not exist.

“Default target file name” onpage 187

OutputFileName The name of the output file that is created or modified.

“Delete the file after retrieveoperation” on page 187

DeleteOnRetrieve During Retrieve operations, when this property is setto true, the file is deleted from the file system after thefile content is retrieved.

“Delimiter between businessobjects in the file” on page188

IncludeEndBODelimiter The file content is appended with this value.

“File content encoding” onpage 188

FileContentEncoding Specifies the encoding set used in writing to or readingfrom the event file.

“Generate a unique file” onpage 188

GenerateUniqueFile Specifies that the adapter creates a unique file duringCreate, Append, and Overwrite operations.

“Output directory” on page189

OutputDirectory The full path name of the directory on the local filesystem where the adapter writes the output files.

“Prefix for the unique filename” on page 189

uniqueFilePrefix The predefined prefix that is added to the generatedunique file name during outbound operations.

“Specify criteria to split filecontent” on page 189

SplitCriteria Specifies either the delimiter that separates thebusiness objects in the retrieved file or the size of thechunks into which the retrieved file is split.

“Split function class name”on page 190

SplittingFunctionClassName Specifies how the retrieved file is to be split, bydelimiter or by size, during an outbound Retrieveoperation.

“Staging directory” on page190

StagingDirectory A temporary directory where the adapter stores theinitial output files during Create and Overwriteoperations.

“Suffix for the unique filename” on page 191

uniqueFileSuffix The predefined suffix that is added to the generatedunique file name during outbound operations.

Archive directory for retrieve operation

The directory where retrieved files are stored before they are deleted, if theDeleteOnRetrieve property is set to true.

Table 36. Archive directory for retrieve operation details

Required No

Default None


Globalized Yes

Bidi supported Yes


Create a new file if the file does not exist

When this property is set to true, the adapter creates a file during Append andOverwrite operations if the file does not exist.

Table 37. Create a new file if the file does not exist details

Required No


Default False


Usage When this property is set to false and the file does not exist, the adapter generates theRecordNotFoundException error.Note: If a value is not specified for this property on the wrapper, then the value specified hereis used.

Globalized No

Bidi supported No

Default target file name

The name of the output file that is created or modified.

Table 38. Default target file name details

Required Required for all outbound operations except List

Default None


Globalized Yes

Bidi supported Yes

Delete the file after retrieve operation

During Retrieve operations, if this property is set to true, the file is deleted fromthe file system after the file content is retrieved.

Table 39. Delete the file after retrieve operation details

Required No


Default False


Usage To archive the file before it is deleted, specify a directory in theArchiveDirectoryForDeleteOnRetrieve property.Note: If a value is not specified for this property on the wrapper, then the value specified hereis used.

Globalized No

Bidi supported No


Delimiter between business objects in the file

The file content is appended with this value.

Table 40. Delimiter between business objects in the file details

Required No

Default <EndBO> for Append operationNone for Create and Overwrite operations


Usage This property is used during outbound Create, Append, and Overwrite operations. Any valuespecified in this property is appended to the file. If the value specified has escape sequencecharacters and Unicode escape characters, they are parsed and the corresponding controlcharacters are inserted in the file. The escape sequence characters include the following:carriage return (\r), new line (\n), carriage return and new line (\r\n), tab space (\t),backspace (\b), form feed (\f), and so on. An example of a Unicode escape character thatrepresents the character ? is \u2297.

Globalized Yes

Bidi supported No

File content encoding

The encoding set used when writing to or reading from the event file.

Note: During the Create operation, the adapter creates the file with the specifiedencoding.

Table 41. File content encoding details

Required No

Possible values Any Java supported encoded character sets.

Default UTF-8


Usage You can specify any Java supported encoding set, such as UTF-8. If the adapter is working withbinary event data, set this property to BINARY. If the adapter is working with non-binary eventdata, such as text or XML, set this property to a valid file encoding value, such as UTF-8 orUTF-16.Note: The value set in the interaction specification property is used only if no value is set onthe wrapper.

Globalized No

Bidi supported No

Generate a unique file

Specifies that the adapter creates a unique file during the Create operation.

Table 42. Generate unique file property details

Required No


Default False



Table 42. Generate unique file property details (continued)

Usage During Create operations, if this property is set to True, the adapter creates a unique file andignores any value set for the Filename property.Note: If a value is not specified for this property on the wrapper, then the value specified hereis used.

Globalized Yes

Bidi supported No

Output directory

The full path name of the directory on the local file system where the adapterwrites the output files.

Table 43. Output directory details

Required No

Default None


Usage If this property is not specified, the adapter writes the output files to the directory specified bythe OutputFileName property on the request.

Globalized Yes

Bidi supported Yes

Prefix for the unique file name


Table 44. Prefix for the unique file name details

Required No

Default None


Usage You can define the prefix to be added when the adapter generates the unique file name duringthe outbound operations. The length of the prefix must be of minimum three letters. Forexample, abc can be used as a predefined prefix for the unique file name.Note: If you do not specify the prefix, the adapter automatically adds a prefix ffa for the filename.

Globalized No

Bidi supported No

Specify criteria to split file content

This property specifies either the delimiter that separates the business objects inthe retrieved file, or the size of the chunks into which the retrieved file is split.

Table 45. Specify criteria to split file content details

Required No

Possible values A delimiter or a valid number

Default 0



Table 45. Specify criteria to split file content details (continued)

Usage This property specifies either the delimiter that separates the business objects in the retrievedfile, or the size of the chunks into which the retrieved file is split. The value of this property isdetermined by the value that is set in the SplittingFunctionClassName property:

v If the SplittingFunctionClassName property is set tocom.ibm.j2ca.utils.filesplit.SplitByDelimiter, the SplitCriteria property must contain thedelimiter that separates the business objects in the retrieved file.

v If the SplittingFunctionClassName property is set tocom.ibm.j2ca.utils.filesplit.SplitBySize, the SplitCriteria property must contain a validnumber that represents the size in bytes. If the retrieved file size is greater than this value, itis split into chunks of this value and that number of chunks are posted. If the file size is lessthan this value, the entire event file is posted.

If the SplitCriteria property is set to 0, chunking is disabled.

The SplitCriteria property must contain the same value for the newline character as the eventfile. For example, if the event file was created on a Macintosh system, the newline character is\r, and the SplitCriteria property must contain \r. The platform-specific newline characters areas follows:

Macintosh - \r

Microsoft Windows - \r\n

UNIX - \n

If there is more than one delimiter in the SplitCriteria property, each delimiter must beseparated by a semicolon (:). If a semicolon (;) itself is part of the delimiter, the semicolon (;)must be escaped, as in \;. For example, if the delimiter given is ##\;##. it is evaluated to ##;##.

Globalized Yes

Bidi supported Yes

Split function class name

This property specifies how the retrieved file is to be split, by delimiter or by size,during an outbound Retrieve operation.

Table 46. Split function class name details

Required No

Possible values com.ibm.j2ca.utils.filesplit.SplitByDelimiter– Files are split based on a delimiter that separates business objects in the event filecom.ibm.j2ca.utils.filesplit.SplitBySize– Files are split based on the size of the event file

Default com.ibm.j2ca.utils.filesplit.SplitBySize


Usage The delimiter or file size is set in the SplitCriteria property.

Globalized No

Bidi supported No

Staging directory

A temporary directory where the adapter stores the initial output files duringCreate and Overwrite operations to avoid write conflicts.

Table 47. Staging directory details

Required No


Table 47. Staging directory details (continued)

Default None


Usage If a staging directory is specified, the file to be operated is copied from the output directory tothe staging directory. The operation is performed on the file in the staging directory, and thefile is then renamed and copied to the output directory.

Globalized Yes

Bidi supported Yes

Suffix for the unique file name

The suffix for the unique file name that you predefine for outbound operations.

Table 48. Suffix for the unique file name details

Required No

Default None


Usage You can define the suffix (file extension) to be added when the adapter generates the uniquefile name during the outbound operations.Note: If you do not specify the file extension, the adapter automatically adds the .tmpextension to the file name.

Globalized No

Bidi supported No

Inbound configuration propertiesWebSphere Adapter for Flat Files has several categories of inbound connectionconfiguration properties, which you set with the external service wizard whilegenerating or creating objects and services. You can change the resource adapterand activation specification properties after you deploy the module using IBMIntegration Designer or the Process Administrative Console, but connectionproperties for the external service wizard cannot be changed after deployment.

Guide to information about propertiesThe properties used to configure WebSphere Adapter for Flat Files are described indetail in tables included in each of the configuration properties topics, such asResource adapter properties, Managed connection factory properties, and so on. Tohelp you use these tables, information about each row you might see is explainedhere.

The following table explains the meaning of each row that might be displayed inthe table for a configuration property.


Row Explanation

Required A required field (property) must have a value in order for the adapter to work.Sometimes the external service wizard provides a default value for requiredproperties.

Removing a default value from a required field on the external service wizardwill not change that default value. When a required field contains no value at all,the external service wizard processes the field using its assigned default value,and that default value is displayed on the Process Administrative Console.

Possible values are Yes and No.

Sometimes a property is required only when another property has a specificvalue. When this is the case, the table notes this dependency. For example,

v Yes, when the EventQueryType property is set to Dynamic

v Yes, for Oracle databases

Possible values Lists and describes the possible values that you can select for the property.

Default The predefined value that is set by the external service wizard. When theproperty is required, you must either accept the default value or specify oneyourself. If a property has no default value, the table states No default value.

The word None is an acceptable default value, and does not mean that there isno default value.

Unit of measure Specifies how the property is measured, for example in kilobytes or seconds.

Property type Describes the property type. Valid property types include:

v Boolean

v String

v Integer

Usage Describes usage conditions or restrictions that might apply to the property. Forinstance, here is how a restriction would be documented:

For Rational Application Developer for WebSphere Software version 6.40 orearlier, the password:

v Must be uppercase

v Must be 8 characters in length

For versions of Rational Application Developer for WebSphere Software laterthan 6.40, the password:

v Is not case-sensitive

v Can be up to 40 characters in length.

This section lists other properties that affect this property or the properties thatare affected by this property and describes the nature of the conditionalrelationship.

Example Provides sample property values, for example:

"If Language is set to JA (Japanese), code page number is set to 8000".

Globalized If a property is globalized, it has national language support, meaning that youcan set the value in your national language.



Row Explanation

Bidi supported Indicates whether the property is supported in bidirectional (bidi) processing.Bidirectional processing refers to the task of processing data that contains bothright-to-left (Hebrew or Arabic, for example) and left-to-right (a URL or filepath, for example) semantic content within the same file.


Connection properties for the wizardConnection properties are used to build a service description and save the built-inartifacts. These properties are configured in the external service wizard.

The following table lists the connection properties for the external service wizard.These properties can only be configured using the external service wizard andcannot be changed after deployment. A complete description of each property isprovided in the sections that follow the table. For information about how to readthe property detail tables in the sections that follow, see “Guide to informationabout properties” on page 173.

Table 49. Connection properties for the external service wizard

Property name in the wizard Description

“Bidi format string” The bidi format string of the content data

“Data binding” Specifies the data binding that is to be used for alloperations or specifies that a data binding is to beselected for each operation.

“Function selector” on page 194 During inbound processing, the name of the functionselector configuration to be used.

“Log file output location” on page 194 The full path name of the log file generated by theexternal service wizard

“Logging level” on page 195 The level of logging to be used by the adapter

“NameSpace” on page 195 The namespace of the business object that is generated

“Operation name” on page 195 The operation defined in the external service wizard

“Processing Direction” on page 196 The processing direction, Inbound or Outbound

Bidi format string

The bidi format string of the content data.

Table 50. Bidi format string

Required No

Default None


Data binding

Specifies the data binding that is to be used for all operations or specifies that adata binding is to be selected for each operation.

Table 51. Data binding details

Required No


Table 51. Data binding details (continued)

Default Use default data binding 'FlatFileBaseDataBinding' for all operations

Usage The value of this property can be:

v Use default data binding 'FlatFileBaseDataBinding' for all operations

v Use a data binding configuration for all operations

v Specify a data binding for each operation

Globalized No

Bidi supported No

Function selector

During inbound processing, the name of the function selector configuration to beused.

Table 52. Function selector details

Required Yes

Default FilenameFunctionSelector


Usage The function selector returns the appropriate operation to be called on the service. The adapterprovides two function selectors, FilenameFunctionSelector and EmbeddedNameFunctionSelector.

v FilenameFunctionSelector is a rule-based function selector that matches a regularexpression on a file name to an object name. Use FilenameFunctionSelector for genericFlatFile business objects, where the object name cannot be determined from the event file.

FilenameFunctionSelector is represented in properties as a two-column table with N rows.For any event file with a .txt extension, the corresponding object name is FlatFile, and theendpoint method name generated by the function selector is emitFlatFile. You must set thissame name in the EISFunctionName property after you add the operation.

You can configure FilenameFunctionSelector with multiple rules, each containing an objectname, and a regular expression to match against the file name. If more than one rulematches, the function selector returns the object name based on the first matching rule.

v Use EmbeddedNameFunctionSelector for content-specific business objects, where the objectname is embedded in the event file. EmbeddedNameFunctionSelector returns the functionname based on the content data, and not the wrapper. For example, if the content-specificbusiness object is CustomerWrapperBG, the function returned by the function selector isemitCustomer.

You must configure EmbeddedNameFunctionSelector with a data handler. The data bindingmust be the adapter-specific WrapperDataBinding, and it must be configured to use the samedata handler that is configured with the function selector.

Globalized Yes

Bidi supported No

Log file output location

The full path name of the log file generated by the external service wizard.

Table 53. Log file output location details

Required No

Default \.metadata \FlatFileMetadataDiscoveryImpl.log


Usage


Table 53. Log file output location details (continued)

Globalized No

Bidi supported No

Logging level

The level of logging to be used by the adapter.

Table 54. Logging level details

Required No

Possible values SevereWarningAuditInfoConfigDetail

Default Severe

Property type List of values

Globalized No

Bidi supported No

NameSpace

The namespace of the business object that is generated.

Table 55. NameSpace details

Required Yes

Default http://www.ibm.com/xmlns/prod/websphere/j2ca/flatfile


Globalized Yes

Bidi supported No

Operation name

The name you give to the operation defined for this module.

Table 56. Operation name details

Required No

Default When the ServiceType property is set to Outbound, the operations listed are Create, Append,Retrieve, Delete, List, Overwrite, and Exists.


Globalized No

Bidi supported No


http://www.ibm.com/xmlns/prod/websphere/j2ca/flatfile

Processing Direction

The processing direction, inbound or outbound.

Table 57. Processing Direction details

Required Yes

Possible values OutboundInbound

Default Outbound


Globalized No

Bidi supported No

Activation specification propertiesActivation specification properties hold the inbound event processing configurationinformation for an export. You set activation specification properties through eitherthe external service wizard or the Process Administrative Console.

The following activation specification properties are no longer required fromversion 6.1.0, but are supported for compatibility with previous versions.v ArchivingProcessedv DefaultObjectNamev EventContentType

The following table lists the activation specification properties for inboundcommunication. You set the activation specification properties using the externalservice wizard and can change them before deployment by using the IBMIntegration Designer Assembly Editor or after deployment through the IBMBusiness Process Manager Process Administrative Console.

A detailed description of each property is provided in the sections that follow thetable. For information about how to read the property detail tables in the sectionsthat follow, see “Guide to information about properties” on page 173.

Table 58. Activation specification properties

Property name


“Archive directory” on page 199 ArchiveDirectory The directory where the adapterarchives processed event files.

(Not available) ArchivingProcessed Deprecated

“Auto create event table” on page 199 EP_Create Table Determines whether the eventpersistence table is createdautomatically or manually.

“Bidirectional transformation of event persistenceproperties” on page 200

EP_BiDiFormat Determines whether the adaptertransforms any of the eventpersistence properties.

(Not available) DefaultObjectName Deprecated

Delivery type DeliveryType Determines the order in whichevents are delivered by theadapter to the export.


Table 58. Activation specification properties (continued)

Property name


Ensure once only event delivery AssuredOnceDelivery Specifies whether the adapterprovides assured once deliveryof events.

“Database schema name” on page 200 EP_SchemaName The schema name of thedatabase used by eventpersistence processing.

(Not available) EventContentType Deprecated

“Event directory” on page 201 EventDirectory The directory where the eventfiles are stored.

“Event recovery data source (JNDI) name” onpage 202

EP_DataSource_JNDIName The JNDI name of the datasource used by event persistenceprocessing to obtain the JDBCdatabase connection. The datasource must be created in IBMBusiness Process Manager.

“Event recovery table name” on page 202 EP_TableName The name of the table used bythe adapter for event persistenceprocessing.

Event types to process EventTypeFilter A delimited list of event typesthat indicates to the adapterwhich events it should deliver.

Retry limit for failed events FailedEventRetryLimit The number of times the adapterattempts to redeliver an eventbefore marking the event asfailed.

“Failure file extension for archive” on page 203 FailedArchiveExtension The file extension used toarchive unsuccessfully processedbusiness objects in the inputevent file. This property isapplicable only when theSplitByDelimiter file splittingcriteria is used.

“File content encoding” on page 204 FileContentEncoding Specifies the encoding of thefiles read by the adapter.

“File extension for archive” on page 204 OriginalArchiveExtension The file extension used toarchive the original event file.

“Include only the newly appended content” onpage 204

ProcessFileAppendedContent Specifies whether to process anddeliver only the appended filecontents compared to the lastpolled file contents.

“Include business object delimiter in the filecontent” on page 205

IncludeEndBO Delimiter Specifies whether the delimitervalue specified in theSplitCriteria property is sentwith the business object contentfor further processing.

“Include total business object count in theChunkInfo (includeBOCountInChunkInfo)” onpage 205

includeBOCountInChunkInfo When set to true, the totalbusiness object count is includedin the chunk information of thedataobject sent to the endpoint.



Property name


Interval between polling periods PollPeriod The length of time that theadapter waits between pollingperiods.

Maximum number of retries in case of systemconnection failure

RetryLimit The number of times the adaptertries to reestablish an inboundconnection after an error.

“Pass only file name and directory, not thecontent” on page 207

FilePassByReference Specifies whether the adapterdelivers the file content to theexport.

“Password used to connect to event data source”on page 208

EP_Password The password used by eventpersistence processing to obtainthe JDBC database connectionfrom the data source.

“Poll event files for modified content” on page 206 FileChangeNotification Specifies whether the adapterpolls the files that changed sincethe last recorded time stamp.

Poll quantity PollQuantity The number of events theadapter delivers to the exportduring each poll period.

“Poll subdirectories in event directory” on page208

PollSubDirectories Specifies whether the adapterpolls the subdirectories withinthe event directory.

“Retrieve files in sorted order” on page 209 SortEventFiles The sorting order of polled eventfiles.

“Retrieve files with pattern” on page 209 EventFileMask The file filter for the event files.

Retry connection on startup RetryConnectionOnStartup Controls whether the adapterretries the connection to the localfile system if it cannot connect atstartup.

“Time between retries in case of system connectionfailure (RetryInterval)” on page 210

RetryInterval The length of time that theadapter waits between attemptsto reestablish connection after anerror during inbound operations.

“Specify criteria to split file content” on page 210 SplitCriteria The delimiter that separates thebusiness objects in the event fileor the maximum size of theevent file, depending on thevalue that is set in the SplittingFunction Class Name.

“Split file content based on size (bytes) ordelimiter” on page 211

(Not available) Specifies file splitting either bysize or delimiter.

“Split function class name” on page 212 SplittingFunctionClassName Specifies how the event file is tobe split, by delimiter or by size.

“Stop the adapter when an error is encounteredwhile polling (StopPollingOnError)” on page 212

StopPollingOnError Specifies whether the adapterstops polling for events when itencounters an error duringpolling.



Property name


“Success file extension for archive” on page 213 SuccessArchiveExtension The file extension used toarchive successfully processedbusiness objects.

“Table name to store the file processing status(EP_FileTableName) ” on page 213

EP_FileTableName The name of the table used tostore the file processing status.

“Time interval for polling unchanged files (inmilliseconds)” on page 213

FileUnchangedTimeInterval Specifies whether the adapterretrieves only those files that arenot changed during the specifiedtime interval.

“Time out period for HA Active-Active eventprocessing change (in seconds) (EP_Timeout)” onpage 214

EP_Timeout Specifies the time interval forprocessing the events fetched.

“User name used to connect to event data source”on page 214

EP_UserName The user name used by eventpersistence processing to obtainthe JDBC database connectionfrom the data source.

Rule editor to filter files ruleTable The collection of rules used tofilter the events.

Archive directory

This property specifies the directory where the adapter archives processed eventfiles.

Table 59. Archive directory details

Required No

Default None


Usage You can use a WebSphere Application Server environment variable to represent the archivedirectory. Specify the name of the environment variable in braces, preceded by a $ symbol. Forexample: ${ARCHIVE_DIRECTORY}. See the topic on creating an environment variable in thisdocumentation.Note: You must enter the location of the archive directory, if PassByReference is set to True.

Globalized Yes

Bidi supported Yes

Auto create event table

This property determines whether the event persistence table is createdautomatically or manually.

Table 60. Auto create event table details

Required No


Default False


Table 60. Auto create event table details (continued)


Usage If this value is set to True, the adapter creates the event persistence table. If the value is set toFalse, the adapter does not create the table and you must manually create it.

The automatic table creation is supported only for the following databases.

v IBM DB2

v Oracle

v Microsoft SQL Server

v Apache Derby

For other databases, you must manually create the event table and the file table.

Globalized No

Bidirectional transformation of event persistence properties

This property determines whether the adapter transforms any of the eventpersistence properties.

Table 61. Bidirectional transformation of event persistence properties

Required No

Possible values You can specify a string value, such as VRYNN.

Default None


Usage The value set on the event persistence bidirectional format property (EP_BiDiFormat)determines the bidirectional transformation. You can specify a string value, such as VRYNN toenable bidirectional transformation of event persistence properties. If the EP_BiDiFormatproperty is not specified, the adapter displays a null value.Note: You can do bidirectional transformation of only those event properties whose values areset on the bidirectional context enterprise information system (EIS) property.

Globalized No

Bidi supported Yes

Database schema name

This property specifies the schema name of the database used by event persistenceprocessing.

Table 62. Database schema name details

Required No

Default None


Globalized Yes

Bidi supported Yes

Delivery type (DeliveryType)

This property specifies the order in which events are delivered by the adapter tothe export.


Table 63. Delivery type details

Required No

Possible values ORDEREDUNORDERED

Default ORDERED


Usage The following values are supported:

v ORDERED: The adapter delivers events to the export one at a time.

v UNORDERED: The adapter delivers all events to the export at once.

Note: HA Active-Active configuration supports only unordered delivery typeevents to the export.

Globalized No

Bidi supported No

Ensure once-only event delivery (AssuredOnceDelivery)

This property specifies whether to provide ensure once-only event delivery forinbound events.

Table 64. Ensure once-only event delivery details

Required Yes


Default True


Usage When this property is set to True, the adapter provides assured once eventdelivery. This means that each event is delivered once and only once. A value ofFalse does not provide assured once event delivery, but provides betterperformance.

When this property is set to True, the adapter attempts to store transaction(XID) information in the event store. If it is set to False, the adapter does notattempt to store the information.

This property is used only if the export component is transactional. If it is not,no transaction can be used, regardless of the value of this property.

Globalized No

Bidi supported No

Event directory

This property specifies the directory in the local file system where the event filesare stored.

Table 65. Event directory details

Required Yes

Default None



Table 65. Event directory details (continued)

Usage You can use a WebSphere Application Server environment variable to represent the eventdirectory. Specify the name of the environment variable in braces, preceded by a $ symbol. Forexample: ${EVENT_DIRECTORY}. See the topic on creating an environment variable in thisdocumentation.

Globalized Yes

Bidi supported Yes

Event recovery data source (JNDI) name

This property specifies the JNDI name of the data source used by event persistenceprocessing to obtain the JDBC database connection.

Table 66. Event recovery data source (JNDI) name details

Required No

Default None


Usage The data source must be created in IBM Business Process Manager. Leave this value empty toenable event polling without using the database.

Globalized Yes

Bidi supported Yes

Event recovery table name

This property specifies the name of the table to be used by the adapter for eventpersistence processing.

Table 67. Event recovery table name details

Required No

Default No default value


Usage When multiple activation specification instances are used, this value must be unique for eachactivation specification instance.

Globalized Yes

Bidi supported Yes

Event types to process (EventTypeFilter)

This property contains a delimited list of event types that indicates to the adapterwhich events it should deliver.

Table 68. Event types to process details

Required No

Possible values A comma-delimited (,) list of business object types

Default null



Table 68. Event types to process details (continued)

Usage Events are filtered by business object type . If the property is set, the adapterdelivers only those events that are in the list. A value of null indicates that nofilter will be applied and that all events will be delivered to the export.

Example To receive events related to the Customer and Order business objects only,specify this value: Customer,Order

Globalized No

Bidi supported No

Retry limit for failed events (FailedEventRetryLimit)

This property specifies the number of times that the adapter attempts to redeliveran event before marking the event as failed.

Table 69. Retry limit for failed events details

Required No

Possible values Integers

Default 5

Property type Integer

Usage Use this property to control how many times the adapter tries to send an eventbefore marking it as failed. It accepts the following values:

DefaultIf this property is not set, the adapter tries five additional times beforemarking the event as failed.

0 The adapter tries to deliver the event an infinite number of times.When the property is set to 0, the event remains in the event store andthe event is never marked as failed.

> 0 For integers greater than zero, the adapter retries the specified numberof times before marking the event as failed.

< 0 For negative integers, the adapter does not retry failed events.

Globalized No

Bidi supported No

Failure file extension for archive

This property specifies the file extension used to archive unsuccessfully processedbusiness objects in the input event file, and applicable only when an event file hasfailed business objects and file splitting by delimiter is enabled.

Table 70. Failure file extension for archive details

Required No

Default fail


Usage The event file is archived with the .fail extension only when you have specifiedSplitByDelimiter as the file splitting criteria. When you specify SplitBySize as the file splittingcriteria, the file is not archived with the .fail extension.

Globalized Yes

Bidi supported Yes


File content encoding

This property specifies the encoding of the files read by the adapter.

Table 71. File content encoding details

Required No

Default UTF-8


Usage You can specify any Java-supported encoding set, such as UTF-8. If the FileContentEncodingproperty is not specified, the adapter uses the default system encoding.

If the adapter is working with binary event data, set this property to BINARY. If the adapter isworking with non-binary event data, such as text or XML, set this property to a valid fileencoding value, such as UTF-8.

Globalized No

Bidi supported No

File extension for archive

This property specifies the file extension used to archive the original event file.

Table 72. File extension for archive details

Required No

Default original


Usage This property preserves the entire event file for reference if any of the business objects failprocessing.

Globalized Yes

Bidi supported Yes

Include only the newly appended content

This property specifies whether to process and deliver only the appended filecontents at the end of the file when compared to the last polled file contents.

Table 73. Notification for appended file contents

Required No

Default False


Usage When you select this property, the adapter processes and delivers only the appended businessobjects (data) at the end of the file when compared to previous poll contents. If the event filehas same or less number of business objects than the last poll, then the file is not processed fordelivery to the endpoint.Note: When you enable this property, the adapter does not archive or delete any files.

Globalized No

Bidi supported No


Include business object delimiter in the file content

This property specifies whether the delimiter value specified in the SplitCriteriaproperty is sent with the business object content for further processing.

Table 74. Include business object delimiter in the file content details

Required No


Default False


Usage When this property is set to true, the delimiter value specified in the SplitCriteria property issent with the business object content for further processing. This property is valid only if eventfile splitting is based on a delimiter; that is, if the SplittingFunctionClassName property is setto com.ibm.j2ca.utils.filesplit.SplitByDelimiter.Note:

v This property has no effect on the inbound processing of the event files.

v If the configured delimiter does not exist in the input file, the adapter processes the event fileas a single business object.

v This property must be used with a custom data binding that can handle end business objectdelimiter in the contents. Using it with XMLDataHandler results in failure at the databinding level.

Globalized No

Bidi supported No

Include total business object count in the ChunkInfo(includeBOCountInChunkInfo)

This property, when set to true, specifies that the total business object count isincluded in the chunk information of the dataobject, which is sent to endpoint.

Table 75. Include total business object count in the ChunkInfo property characteristics

Required No


Default False


Usage This property is used for specifying whether the total business object count isincluded in the chunk information of the dataobject sent to the endpoint.

Format of the chunk information:

When the property is enabledAbsolutePathOfEventFileNameInLocalEventDirectory_/_YYYY_MM_DD_HH_mm_ss_SSS_/_currentBONumberofTotalBOCount

When the property is disabledAbsolutePathOfEventFileNameInLocalEventDirectory_/_YYYY_MM_DD_HH_mm_ss_SSS.currentBONumber_/_currentBONumber

Globalized No


Table 75. Include total business object count in the ChunkInfo property characteristics (continued)

Bidi supported No

Interval between polling periods (PollPeriod)

This property specifies the length of time that the adapter waits between pollingperiods.

Table 76. Interval between polling periods details

Required Yes

Possible values Integers greater than or equal to 0.

Default 2000

Unit of measure Milliseconds


Usage The poll period is established at a fixed rate, which means that if running thepoll cycle is delayed for any reason (for example, if a prior poll cycle takeslonger than expected to complete) the next poll cycle occurs immediately tomake up for the lost time caused by the delay.

Globalized No

Bidi supported No

Maximum events in polling period (PollQuantity)

This property specifies the number of events that the adapter delivers to the exportduring each poll period.

Table 77. Maximum events in polling period details

Required Yes

Default 10


Usage The value must be greater than 0. If this value is increased, more events areprocessed per polling period and the adapter may perform less efficiently. If thisvalue is decreased, fewer events are processed per polling period and theadapter's performance might improve slightly.

Globalized No

Bidi supported No

Poll event files for modified content

This property specifies whether the adapter polls files that changed since the lastrecorded time stamp.

Table 78. Notification for file changes

Required No

Default False



Table 78. Notification for file changes (continued)

Usage This property is used to retrieve files from the event directory, when a file is changed from thelast recorded time stamp. When this property is selected, the adapter polls the new andchanged files during each subsequent poll cycle after the previous event poll. Also, the adapterdoes not delete any event file from the event directory.Note: The adapter does not archive any files in the specified archive directory. Also, thisproperty is disabled if you select the FilePassByReference property.

Globalized No

Bidi supported No

Maximum number of retries in case of system connection failure(RetryLimit)

This property specifies the number of times the adapter tries to reestablish aninbound connection.

Table 79. Maximum number of retries in case of system connection failure

Required No

Possible values 0 and positive integers

Default 0


Usage This property controls how many times the adapter retries the connection if theadapter cannot connect to the local file system to perform inbound processing.A value of 0 indicates an infinite number of retries.

To control whether the adapter retries if it cannot connect to the local filesystem when it is first started, use the RetryConnectionOnStartup property.

Globalized No

Bidi supported No

Pass only file name and directory, not the content

This property specifies whether to send the directory name and file name to theendpoint.

Table 80. Pass only file name and directory, not the content details

Required No


Default False



Table 80. Pass only file name and directory, not the content details (continued)

Usage If this property is set to True, the adapter always archives the file and sends the directory nameand file name to the endpoint. However, the adapter does not load the content of the file. Theevent file is appended with a time stamp and archived to the archive directory. For example, ifa.txt is the event file, it is archived as a.txt.yyyy_MM_dd_HH_mm_ss_SSS in the archive directory.Additionally, for COBOL or XMLDataHandler, the event file is archived toa.txt.yyyy_MM_dd_HH_mm_ss_SSS.original file.Note:

v If this property is set to True and archive directory is not specified, the adapter throws anexception. This property can be used with a custom data binding that does not fail at runtime if no content is set; or it can be used in a pass-through scenario. Using this propertywith XMLDataHandler results in failure at the data binding level, because XMLDataHandlerexpects content in addition to the file name and directory path.

v In the external service wizard, you can use this property if both the SplitCriteria propertyand FileChangeNotification properties are not selected.

v The Process Administrative Console allows you to use this property along with theFileChangeNotification, SplittingFunctionClassName, and SplitCriteria properties, but theevent files are not split into chunks. The settings specified in the FileChangeNotificationproperty take precedence, when used with this property.

Globalized No

Password used to connect to event data source

This property specifies the password used by event persistence processing toobtain the JDBC database connection from the data source.

Table 81. Password used to connect to event data source details

Required No

Default None


Globalized Yes

Bidi supported Yes

Poll subdirectories in event directory

This property specifies whether the adapter polls the subdirectories within theevent directory.

Table 82. Poll subdirectories in event directory details

Required No

Default False



Table 82. Poll subdirectories in event directory details (continued)

Usage When this property is set to True, the adapter polls the files in the event directory and also thefiles in its subdirectories. When this property is set to False, the adapter polls only the files inthe root directory and ignores any subdirectories.

During a poll cycle, the adapter first polls the files in the root directory and then polls the filesin the subdirectories. It sorts them according to the value set for the SortEventFiles propertyand processes them according to the value set for the PollQuantity property. It then sends thebusiness objects to the downstream components.

When the PollSubDirectories property is set to True and archiving is enabled, all the polledfiles, including the files that are polled from the subdirectories, are archived to the archivedirectory.

Globalized No

Bidi supported No

Retrieve files in sorted order

This property specifies the sorting order of polled event files.

Table 83. Retrieve files in sorted order details

Required No

Possible values File name - sort in ascending order on file nameTime stamp- sort in ascending order on last modified time stampNo sort- not sorted

Default No sort


Usage To support globalization, the sorting of file names is provided according to the system locale.The ICU4J package is used to track the locales and the rules corresponding to the locales.Note: The sorting of event files by file name or timestamp is not supported in the HAActive-Active configuration.

Globalized No

Bidi supported No

Retrieve files with pattern

This property specifies the file filter for the event files.

Table 84. Retrieve files with pattern details

Required Yes

Default *.*


Usage The file filter is a well-qualified valid regular expression that can consist of alphanumericcharacters and the wildcard character "*". *. For example, if you specify event*, only file namesbeginning with event are processed.

Globalized Yes

Bidi supported Yes


Retry EIS connection on startup (RetryConnectionOnStartup)

This property controls whether the adapter attempts to connect again to the localfile system if it cannot connect at startup.

Table 85. Retry EIS connection on startup details

Required No


Default False


Usage This property indicates whether the adapter should retry the connection to thelocal file system if the connection cannot be made when the adapter is started:

v Set the property to False when you want immediate feedback about whetherthe adapter can establish a connection to the local file system, for example,when you are building and testing the application that receives events fromthe adapter. If the adapter cannot connect, the adapter writes log and traceinformation and stops. The administrative console shows the applicationstatus as Stopped. After you resolve the connection problem, start the adaptermanually.

v Set the property to True if you do not need immediate feedback about theconnection. If the adapter cannot connect during startup, it writes log andtrace information, and then attempts to reconnect, using the RetryIntervalproperty to determine how frequently to retry and the value of theRetryLimit property to retry multiple times until that value is reached. Theadministrative console shows the application status as Started.

Globalized No

Bidi supported No

Time between retries in case of system connection failure(RetryInterval)

When the adapter encounters an error related to the inbound connection, thisproperty specifies the length of time the adapter waits before trying to reestablish aconnection.

Table 86. Retry interval details

Required Yes

Default 2000



Usage Only positive values are valid. When the adapter encounters an error related tothe inbound connection, this property specifies the length of time the adapterwaits before trying to establish a new connection.

Globalized No

Bidi supported No

Specify criteria to split file content

This property specifies either the delimiter that separates the business objects inthe event file or the maximum size of the event file.


Table 87. Specify criteria to split file content details

Required No

Default 0


Usage This property specifies the delimiter that separates the business objects in the event file or themaximum size of the event file. The value of this property is determined by the value that isset in the SplittingFunctionClassName property:

v If the SplittingFunctionClassName property is set tocom.ibm.j2ca.utils.filesplit.SplitByDelimiter, the SplitCriteria property must contain thedelimiter that separates the business objects in the event file.

v If the SplittingFunctionClassName property is set tocom.ibm.j2ca.utils.filesplit.SplitBySize, the SplitCriteria property must contain a validnumber that represents the maximum file size in bytes. If the event file size is greater thanthis value, it is split into chunks of this value and that number of chunks are posted. If theevent file size is less than this value, the entire event file is posted.

If the SplitCriteria property value is set to 0, file splitting is disabled.Note: During inbound processing, if file splitting is based on size or delimiter and theFilePassByReference property is enabled, the event files are not split into chunks.Note: For input files that contain multiple COBOL copybook records, in order to enable filesplitting by size you must provide the correct length of each record. To determine the size ofeach record, use the following method:

1. Open the Business Object in a text editor.

2. Look for the complex type tag with the business object name value in the name attribute. Inthe example that follows, the business object name is DFHCOMMAREA.

3. Locate a namespace-appended tag called aggregateInstanceTD and use the value for theattribute contentSize. In this example, the value is 117. This value is the size of each recordof type DFHCOMMAREA.

<complexType name="DFHCOMMAREA"><annotation><appinfo source="http://www.ibm.com/cam/2005/typedescriptor"><td:typeDescriptorCT><td:aggregateInstanceTD accessor="readWrite" attributeInBit="false"contentSize="117" offset="0" size="117">

Globalized Yes

Bidi supported Yes

Split file content based on size (bytes) or delimiter

This property specifies file splitting either by size or delimiter. The splittingfunction class name and the split criteria are used to split the file content.

Table 88. Split file content based on size (bytes) or delimiter

Required No


Default False



Table 88. Split file content based on size (bytes) or delimiter (continued)

Usage This property specifies whether the adapter splits the contents of the files present in the eventdirectory based on either by size or delimiter. You can specify the following settings to spliteither by size or delimiter.

v Specify the split function class name to com.ibm.j2ca.utils.filesplit.SplitBySize andspecify the split size (in bytes) criteria to enable the adapter to split the file contents.

v Specify the split function class name to com.ibm.j2ca.utils.filesplit.SplitByDelimiterand specify the delimiter criteria to enable the adapter to split the file contents.

Globalized No

Bidi supported No

Split function class name

This property determines how the event file is to be split.

Table 89. Split function class name details

Required No

Possible values com.ibm.j2ca.utils.filesplit.SplitByDelimiter– Files are split based on a delimiter that separates business objects in the event filecom.ibm.j2ca.utils.filesplit.SplitBySize– Files are split based on the size of the event file

Default com.ibm.j2ca.utils.filesplit.SplitBySize


Usage The delimiter or file size is set in the SplitCriteria property.Note: If the SplittingFunctionClassName property is null, this property is automatically set tocom.ibm.j2ca.utils.filesplit.SplitBySize.

Globalized No

Bidi supported No

Stop the adapter when an error is encountered while polling(StopPollingOnError)

This property specifies whether the adapter will stop polling for events when itencounters an error during polling.

Table 90. Stop the adapter when an error is encountered while polling details

Required No


Default False


Usage If this property is set to True, the adapter stops polling when it encounters anerror.

If this property is set to False, the adapter logs an exception when it encountersan error during polling and continues polling.

Globalized No

Bidi supported No


Success file extension for archive

This property specifies the file extension used to archive successfully processedbusiness objects.

Table 91. Success file extension for archive details

Required No

Default success


Globalized Yes

Bidi supported Yes

Table name to store the file processing status (EP_FileTableName)

This property specifies the table name to store the file processing status. Theadapter continues to process the file from its last stored status, during the eventrecovery.

Table 92. Table name to store the file processing status (EP_FileTableName) details

Required No

Default FILETABLE


Usage This property supports WebSphere Adapter for Flat Files to read only the partialcontents of the file required by the polling quantity and tracks the last fileposition reached after a partial read of the file. The file status stored in the tableis used during the event recovery.Note: During the event recovery, the adapter continues to process the file fromits last stored status in the table.

Globalized Yes

Bidi supported Yes

Time interval for polling unchanged files (in milliseconds)

This property specifies whether the adapter retrieves only those files that are notchanged during the specified time interval.

Table 93. Time interval for polling unchanged file

Required No

Default 0



Usage This property enables the adapter to retrieve only those files that are not modified in the eventdirectory for a specified time interval. When this property is selected, the adapter retrieves theunchanged files during the poll cycles. The adapter also polls the files that are currently beingedited but retrieves the file content present during the last save of the file.

Globalized No

Bidi supported No


Time out period for HA Active-Active event processing change (inseconds) (EP_Timeout)

Specifies the time interval, in seconds, for processing the events fetched. Theunprocessed events at the end of the time interval are reprocessed as new events.

Table 94. Time out period for HA Active-Active event processing change (in seconds) property characteristics

Required Yes

Default 300

Unit of measure Seconds


Usage This property is used for specifying the time interval, in seconds, for theadapter to process the events fetched. If for any reason the adapter fails toprocess all the fetched events at the end of the time interval, the unprocessedevents are reprocessed as new events by a different adapter.Note: You can use this property if the HA Active-Active configuration isenabled and the guaranteed delivery event is required.

Globalized No

Bidi supported No

User name used to connect to event data source

This property specifies the user name used by event persistence processing toobtain the JDBC database connection from the data source.

Table 95. User name used to connect to event data source details

Required No

Default None


Globalized Yes

Bidi supported Yes

Rule editor to filter files (ruleTable)

This property is used to filter event files based on a set of rules

Table 96. Rule editor to filter files

Required Optional

Default No default value


Usage During an inbound processing, if the value in the rule table is specified, then the event filesare fetched after filtering, based on the specified rules before polling those event files.

Globalized Yes

Bidi supported No

Resource adapter propertiesThe resource adapter properties control the general operation of the adapter, suchas specifying the namespace for business objects. You set the resource adapter


properties using the external service wizard when you configure the adapter. Afterdeploying the adapter, use the Process Administrative Console to change theseproperties.

The following properties for logging and tracing are no longer required in version7.5.0.3. They are visible from the Process Administrative Console for compatibilitywith previous versions.v LogFileMaxSizev LogFileNamev LogNumberOfFilesv TraceFileMaxSizev TraceFileNamev TraceNumberOfFiles

The following table lists the resource adapter properties and their purpose. Acomplete description of each property is provided in the sections that follow thetable. For information about how to read the property detail tables in the sectionsthat follow, see “Guide to information about properties” on page 173.

Table 97. Resource adapter properties for the WebSphere Adapter for Flat Files

Name





“Enable high availabilitysupport (enableHASupport)”on page 217

enableHASupport Specifies if a single or multiple adapter instances areactive at a given time in a clustered environment.

(Not available) LogFileSize Deprecated

(Not available) LogFilename Deprecated

(Not available) LogNumberOfFiles Deprecated

(Not available) TraceFileSize Deprecated

(Not available) TraceFileName Deprecated

(Not available) TraceNumberOfFiles Deprecated




Required Yes

Default 001








Globalized Yes

Bidi supported No




Required No


Default False




Globalized No


Table 99. Disguise user data as "XXX" in log and trace files details (continued)

Bidi supported No

Enable high availability support (enableHASupport)

This property specifies the cluster deployment settings for the adapter.

Note: For HA Active-Active configuration, this property must be set to false inthe Process Administrative Console.

Table 100. Enable high availability support property details

Required No

Possible values True (Active-Passive)False (Active-Active)

Default True


Usage Use this property to specify if the adapter is to be run in Active-Passive or Active-Activeconfiguration mode.

Active-Passive configuration mode

By default, the adapter is configured to run in an Active-Passive mode that provides highavailability support. This configuration allows only one adapter instance to be active to poll aremote event directory for files.

Active-Active configuration mode

When you use the Active-Active mode, the adapter provides both high availability and loadbalancing support. This configuration allows multiple adapter instances to simultaneously polla remote event directory for files. It also provides the advantage of faster event processing byensuring that there is no duplication when processing the different adapter instances.

The following limitations are applicable when you configure the adapter in the Active-Activemode:

v The Active-Active configuration works only for the Unordered delivery type.

v The event persistence entries must not be left empty.

v The sorting of event files by file name or timestamp is not supported in the HAActive-Active configuration.

Note: If you change the existing value of this property in the administrative console, theadapter overwrites the value specified in the external service.

Globalized No

Bidi supported No

GlobalizationWebSphere Adapter for Flat Files is a globalized application that can be used inmultiple linguistic and cultural environments. Based on character set support andthe locale of the host server, the adapter delivers message text in the appropriatelanguage. The adapter supports bidirectional script data transformation betweenintegration components.


Globalization and bidirectional data transformationThe adapter is globalized to support single- and multi-byte character sets anddeliver message text in the specified language. The adapter also performsbidirectional script data transformation, that refers to the task of processing datathat contains both right-to-left (Hebrew or Arabic, for example) and left-to-right (aURL or file path, for example) semantic content within the same file.

Globalization

Globalized software applications are designed and developed for use withinmultiple linguistic and cultural environments rather than a single environment.WebSphere Adapters, IBM Integration Designer, IBM Business Process Manager orWebSphere Enterprise Service Bus are written in Java. The Java runtimeenvironment within the Java virtual machine (JVM) represents data in the Unicodecharacter code set. Unicode contains encodings for characters in most knowncharacter code sets (both single- and multi-byte). Therefore, when data istransferred between these integration system components, there is no need forcharacter conversion.

To log error and informational messages in the appropriate language and for theappropriate country or region, the adapter uses the locale of the system on whichit is running.

Bidirectional script data transformation

Languages such as Arabic and Hebrew are written from right to left, yet theycontain embedded segments of text that are written left to right, resulting inbidirectional script. When software applications handle bidirectional script data,standards are used to display and process it. Bidirectional script datatransformation applies only to string type data. IBM Business Process Manager orWebSphere Enterprise Service Bus uses the Windows standard format, butapplications or file systems that exchange data with the server might use adifferent format. The adapter transforms bidirectional script data passed betweenthe two systems so that it is accurately processed and displayed on both sides of atransaction. It transforms the script data by using a set of properties that definesthe format of script data, as well as properties that identify content or metadata towhich transformation applies.

Bidirectional script data formats

IBM Business Process Manager or WebSphere Enterprise Service Bus uses thebidirectional format of ILYNN (implicit, left-to-right, on, off, nominal). Thisbidirectional format is used by Windows. If an enterprise information system usesa different format, the adapter converts the format before introducing the data toIBM Business Process Manager or WebSphere Enterprise Service Bus.

The bidirectional format consists of five attributes. When you set bidirectionalproperties, you assign values for each of these attributes. The attributes andsettings are listed in the following table.

Table 101. Bidirectional format attributes

Letter position Purpose Values Description Default setting

1 Order schema I Implicit (Logical) I

V Visual


Table 101. Bidirectional format attributes (continued)

Letter position Purpose Values Description Default setting

2 Direction L Left-to-Right L

R Right-to-Left

C Contextual Left-to-Right

D Contextual Right-to-Left

3 Symmetric Swapping Y Symmetric swapping is on Y

N Symmetric swapping is off

4 Text Shaping S Text is shaped N

N Text is not shaped (Nominal)

I Initial shaping

M Middle shaping

F Final shaping

B Isolated shaping

5 Numeric Shaping H National (Hindi) N

C Contextual shaping

N Numbers are not shaped (Nominal)

Bidirectional properties that identify data for transformation

To identify business data for transformation, set the BiDiContextEIS property. Dothis setting by specifying values for each of the five bidirectional format attributes(listed in the preceding table) for the property. The BiDiContextEIS property can beset for the managed connection factory and for the activation specification.

To identify event persistence data subject for transformation, set theEP_BiDiFormat property. The value for the EP_BiDiFormat property is set with thevalue you specified in the BiDiContextEIS property. The EP_BiDiFormat propertycan be set for the activation specification.

To identify application-specific data for transformation, annotate theBiDiContextEIS property and the BiDiMetadata property within a business object.Do this setting by using the business object editor within IBM Integration Designerto add the properties as application-specific elements of a business object.

Bidirectional transformation in business objectsFor outbound processing, you can modify the business objects to enable thebidirectional transformation of the wrapper properties in the WebSphere Adapterfor Flat Files business object and the data in content-specific or generic businessobjects.

You must add an annotation to the complex type of the business object to specifythe bidirectional formatting attributes in the files for the following business objects:v For the generic business object, change the FlatFile.xsd file.v For the user-defined business object, change the custom wrapper (for example,

the CustomWrapper.xsd file and Customer.xsd).v For the UnstructuredContent business object, change the

UnstructuredContent.xsd.


The following sections include annotations that can serve as examples.

Bidirectional formatting attributes of the business object

The following annotation, which contains the bidirectional context information,applies to all the attributes in the Flat Files business objects. TheFlatFileBaseDataBinding uses the bidirectional information in the elementBiDiContext to transform all the attributes.<xsd:complexType name="Customer"><xsd:annotation>

<xsd:appinfosource="http://www.ibm.com/xmlns/prod/websphere/j2ca/datatrans

formation/databindingmapping">

<dtm:DataBindingMappingxsi:type="dtm:DataBindingMapping"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:dtm="http://www.ibm.com/xmlns/prod/websphere/j2ca/da

tatransformation/databindingmapping"><BiDiContext>

<orientation>rtl</orientation><textShape>nominal</textShape><orderingScheme>visual</orderingScheme><symmetricSwapping>true</symmetricSwapping><numeralShapes>nominal</numeralShapes>

</BiDiContext></dtm:DataBindingMapping>

</xsd:appinfo></xsd:annotation>

Bidirectional formatting attributes of the wrapper

You can add an annotation to the wrapper of a user-defined type business object.The annotation in the wrapper business objects such as the generic (FlatFile) andthe user-defined type (CustomerWrapper) is used to do bidirectionaltransformation of wrapper attributes. The content-specific business objects that areused inside the wrapper business objects are not transformed using annotation inthe wrapper business objects. To transform content-specific business objects, youmust edit the respective business object definition to add the annotation shown inthe previous example for bidirectional formatting of attributes of the businessobject.

The following annotation is an example for the wrapper:<complexType name="CustomerWrapper"><xsd:annotation>

<xsd:appinfosource="http://www.ibm.com/xmlns/prod/websphere/j2ca/

datatransformation/databindingmapping"><dtm:DataBindingMapping

xsi:type="dtm:DataBindingMapping"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:dtm="http://www.ibm.com/xmlns/prod/websphere/j2ca/

datatransformation/databindingmapping"><BiDiContext>

<orientation>rtl</orientation><textShape>nominal</textShape><orderingScheme>visual</orderingScheme><symmetricSwapping>true</symmetricSwapping><numeralShapes>nominal</numeralShapes>


</BiDiContext></dtm:DataBindingMapping>

</xsd:appinfo></xsd:annotation>

Properties enabled for bidirectional data transformationBidirectional data transformation properties enforce the correct format ofbidirectional script data exchanged between an application or file system andintegration tools and runtime environments. Once these properties are set,bidirectional script data is correctly processed and displayed in IBM IntegrationDesigner and IBM Business Process Manager or WebSphere Enterprise Service Bus.

Managed connection factory properties

The following managed connection factory properties control bidirectional scriptdata transformation:v FileSequenceLogv OutputDirectoryv OutputFilenamev StagingDirectory

Activation specification properties

The following activation specification properties control bidirectional script datatransformation:v ArchiveDirectoryv EventDirectoryv EventFileMaskv FailedArchiveExtensionv OriginalArchiveExtensionv SplitCriteriav SuccessArchiveExtension

Deployment Descriptor configuration properties

The following deployment descriptor configuration properties control bidirectionalscript data transformation:v EPDatabasePasswordv EPDatabaseSchemaNamev EPDatabaseUsernamev EPDataSourceJNDINamev EPEventTableName

Business object wrapper properties

The following business object wrapper properties control bidirectional script datatransformation:v DirectoryPathv FileNamev IncludeEndBODelimiterv StagingDirectory


v ArchiveDirectoryForDeleteOnRetrievev ChunkFileName

Adapter messagesView the messages issued by WebSphere Adapter for Flat Files at the followinglocation.

Link to messages: http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.ref.doc/adapt_messages.html

The displayed Web page shows a list of message prefixes. Click a message prefix tosee all the messages with that prefix:v Messages with the prefix CWYFF are issued by WebSphere Adapter for Flat Filesv Messages with the prefix CWYBS are issued by the adapter foundation classes,

which are used by all the adapters

Related informationThe following information centers, IBM Redbooks, and web pages contain relatedinformation for WebSphere Adapter for Flat Files.

Information resourcesv The WebSphere Business Process Management information resources web page

includes links to articles, Redbooks, documentation, and educational offerings tohelp you learn about WebSphere Adapters: http://www-01.ibm.com/software/integration/integration-designer/.

v The WebSphere Adapters library page includes links to all versions of thedocumentation: http://www.ibm.com/software/integration/wbiadapters/library/infocenter/.

Information about related productsv IBM Business Process Manager, Version 8.0.1, information center, which includes

IBM Business Process Manager, and IBM Integration Designer information:http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0m1/index.jsp.

v IBM Business Process Manager, Version 8.0, information center, which includesIBM Business Process Manager, and IBM Integration Designer information:http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0mx/index.jsp.

developerWorks® resourcesv WebSphere Adapter Toolkitv WebSphere business integration zone

Video samplesTo help you use WebSphere Adapters, sample videos are available to detail someof the scenarios.

You can find several WebSphere Adapters video demonstrations at this FTPlocation ftp://ftp.software.ibm.com/software/websphere/integration/wsa/library/videos/.

To view these video samples:1. Download the zip file of the required sample from the FTP location.


http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.ref.doc/adapt_messages.html

http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.ref.doc/adapt_messages.html

http://www-01.ibm.com/software/integration/integration-designer/

http://www-01.ibm.com/software/integration/integration-designer/

http://www.ibm.com/software/integration/wbiadapters/library/infocenter/

http://www.ibm.com/software/integration/wbiadapters/library/infocenter/

http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0m1/index.jsp

http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0mx/index.jsp

http://www.ibm.com/developerworks/websphere/downloads/wat/

http://www.ibm.com/developerworks/websphere/zones/businessintegration/

ftp://ftp.software.ibm.com/software/websphere/integration/wsa/library/videos/

ftp://ftp.software.ibm.com/software/websphere/integration/wsa/library/videos/

2. Extract the downloaded zip file to your system.3. From the extracted folder, double-click the HTML file.4. The video sample opens in your default Web browser.

Note: Some of the video samples has a built-in audio narration. If you do notwant to listen to the audio, you can lower its tab to the minimum, and slide thetab to an audio level, whenever you want the audio back.

The following sample videos for IBM Integration Designer are currently availableat this location: ftp://ftp.software.ibm.com/software/websphere/integration/wsa/library/videos/IIDv Applying Adapter fix for IBM Integration Designer toolkitv Applying Adapter fix for IBM Process Server at embedded levelv Applying Adapter fix for IBM Process Server at node levelv Checking version in IBM Integration Designer toolkitv Checking version in IBM Process Server after enabling traces

The following sample videos for WebSphere Adapters version 7.5.0 are currentlyavailable at this location: ftp://ftp.software.ibm.com/software/websphere/integration/wsa/library/videos/750v AFC: Scheduling Calendar based pollingv AFC: Overcoming an AFC version conflict situation

The sample videos for WebSphere Adapters Version 7.0 are currently available atthis location: ftp://ftp.software.ibm.com/software/websphere/integration/wsa/library/videos/700


ftp://ftp.software.ibm.com/software/websphere/integration/wsa/library/videos/IID

ftp://ftp.software.ibm.com/software/websphere/integration/wsa/library/videos/IID

ftp://ftp.software.ibm.com/software/websphere/integration/wsa/library/videos/750




Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation Licensing2-31 Roppongi 3-chome, Minato-kuTokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.


Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM CorporationDepartment 2Z4A/SOM1294 Route 100Somers, NY 10589-0100U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurements may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrate programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows: (c) (your company name) (year). Portions of


this code are derived from IBM Corp. Sample Programs. (c) Copyright IBM Corp._enter the year or years_. All rights reserved.

If you are viewing this information softcopy, the photographs and colorillustrations may not appear.

Programming interface informationProgramming interface information, if provided, is intended to help you createapplication software using this program.

General-use programming interfaces allow you to write application software thatobtain the services of this program's tools.

However, this information may also contain diagnosis, modification, and tuninginformation. Diagnosis, modification and tuning information is provided to helpyou debug your application software.

Warning:

Do not use this diagnosis, modification, and tuning information as a programminginterface because it is subject to change.

Trademarks and service marksIBM, the IBM logo, and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corporation in the United States, other countries,or both. These and other IBM trademarked terms are marked on their firstoccurrence in this information with the appropriate symbol (® or ™), indicating USregistered or common law trademarks owned by IBM at the time this informationwas published. Such trademarks may also be registered or common lawtrademarks in other countries. A complete and current list of IBM trademarks isavailable on the Web at http://www.ibm.com/legal/copytrade.shtml

Linux is a registered trademark of Linus Torvalds in the United States, othercountries, or both.

Microsoft and Windows are trademarks of Microsoft Corporation in the UnitedStates, other countries, or both.

Java and all Java based trademarks and logos are trademarks of Sun Microsystems,Inc. in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Other company, product, or service names may be trademarks or service marks ofothers.

This product includes software developed by the Eclipse Project(http://www.eclipse.org).

Notices 227

http://www.eclipse.org

Index

Aaccess permissions 160activation specification 122, 124activation specification properties

do not process events with a futuretimestamp 196

event recovery data source (JNDI)name 196

number of times to retry the systemconnection 196

password used to connect to eventdata source 196

setting in administrative console 136,140

Activation specification propertiesarchive directory 196auto create event table 196database schema name 196delivery type 196ensure once only event delivery 196event directory 196event recovery table name 196event types to process 196failure file extension for archive 196file content encoding 196file extension for archive 196include business object delimiter in

the file content 196interval between polling periods 196pass only file name and

directory 196poll quantity 196poll subdirectories in event

directory 196retrieve files in sorted order 196retrieve files with pattern 196retry connection on startup 196retry interval if connection fails 196specify criteria to split file

content 196split function class name 196stop the adapter when an error is

encountered during polling 196success file extension for archive 196user name used to connect to the

event data source 196Active-Passive 38adapter

configuringrequirements 33

information resources 222messages 222package files 129performance 143related information 222samples and tutorials 222support and assistance 222technotes 222

adapter applicationstarting 142, 162stopping 142, 162

Adapter for Flat Files moduleexporting as EAR file 117installing EAR file on server 118starting 142, 162stopping 142, 162

adapter patterns wizardCreating a simple service 74

adapterWebSphere Adapter for Flat Filesoutbound processing 3

administrative console 120, 122, 124AIX 155append 3Archived events

failure 19original file extensions 19success 19

artifacts 50artifacts, generating 91ASI file 157assured-once

event delivery 17

BBatch Processing 38bidirectional format

setting 218Bidirectional formatting attributes

wrapper 219BPEL (Business Process Execution

Language) 153business faults 170business integration adapters to

JCA-compliant adapters 47business object information 165business object, predefining 59, 62business objects 3, 29

attribute properties 169converting into COBOL copybook

files 63naming conventions 169structure 165

business objects, converting COBOLcopybook files into 69

business objects, processingevent file 23

CCEI (Common Event Infrastructure) 146changes after migration

to the export file 52to the import file 52to the wsdl file 52

cluster level 122, 124clustered environment 120, 122, 124

adapters version conflict 38deployment 38inbound process 38inbound processes 39

clustered environment (continued)load balancing 38outbound process 38outbound processes 40

COBOL copybook filesconverting from business objects 63

COBOL copybook files, converting intobusiness objects 69

Comma-separated values (CSV) 105Common Event Infrastructure (CEI) 146compatibility matrix 1confidential data, disguising 33confidential tracing 33configuration properties

inbound 191configuring

logging properties 129Performance Monitoring Infrastructure

(PMI) 143configuring the data binding,

inbound 103configuring the data binding,

outbound 85Connection properties

inbound 93outbound 80

Connection propertiesexternal serviceconnection properties

bidi format string 175, 193data binding 175, 193function selector 175, 193log file output location 175, 193logging level 175, 193nameSpace 175, 193operation name 175, 193processing direction 175, 193

Createoperation 4

Create operationmapped drive connection 4unique file 4

Create operationsGenerating unique file names

persistent sequence number,random numbers 12

Custom classsplitting logic 171

Custom file splitting 171custom properties

activation specification 136, 140managed connection factory 134, 139resource adapter 132, 138

Ddata binding

configuring 103Data handlers

configuring 105data transformation

bidirectional 221


data transformation (continued)right-to-left 218

data transformation (inbound) 29data transformation (outbound) 8Data type

Selecting 102setting 83

database scripts 45debugging

org.xml.sax.SAXParseExceptionexception 158

self-help resources 149, 163XAResourceNotAvailableException

exception 156Delete 3, 6

RecordNotFoundException error 6Delimited data handler 87deploy module 120, 122deployment 118

production environment 116test environment 113

deployment environment 113deployment options 34developerWorks 222disguising confidential data 33duplicate file processing

avoiding 19

EEAR file

exporting 117installing on server 118

embedded adapter 120activation specification properties,

setting 136considerations for using 36managed connection factory

properties, setting 134resource adapter properties,

setting 132usage considerations 34

embedded adapters 120, 122changing configuration

properties 132setting activation specification

properties 136setting managed (J2C) connection

factory properties 134setting resource adapter

properties 132EmbeddedNameFunctionSelector 21enableHASupport property 39endpoint applicaiton

troubleshoot 158environment variablesWebSphere

Application Server 60environment variablesWebSphere

Application Server environmentvariables 31, 58, 177, 196

eventvalue 17

Event archival values 19event delivery 201event directory

polling 13

event filesarchiving 17

event management flow 17event persistence

activation specification 196Event persistence 13event store

overview 17structure 17upgrade 45

event table structureupgrade 45

eventsrule-based filtering 13

ExceptionDataBindingException 153existing tables

migrate 159IllegalArgumentException 153

exceptionsorg.xml.sax.SAXParseException 158XAResourceNotAvailableException 156

Exists 3, 6exporting module as EAR file 117external service discovery, connection

properties 80, 93external service wizard

basic flow 31external service wizardexternal service

overview 31external service wizardexternal service

wizardstarting 79

FFAQ 160faults

description 170fetched events 196FFDC (first-failure data capture) 154file

reading 1writing 1

File content change 23file metadata change 23file processing status 196File retrieval 23file splitting

chunk information 10delimiter 25delimiter-based 10size 25size-based 10

file store 19tracking inbound files 19

file table 17, 20FilenameFunctionSelector 21files

SystemOut.log log file 131trace.log trace file 131

first-failure data capture (FFDC) 154Frequently Asked Questions 160

WebSphere Adapter for Flat Files 160function selector 21

Ggenerating artifacts 91generating inbound artifactsexternal

service 108generating unique file names

prefix 12suffix 12

global elements 30Global elements 153Globalization

character encoding 218

HHA Active-Active 38, 196, 215hardware and software requirements 1hardware requirements 1High Availability (HA)

clustered environments 222high-availability environment 38

Active-Active 38Active-Passive 38deployment 38inbound processes 39outbound processes 40

IIBM Business Process Manager

information 222IBM Business Process Manager or

WebSphere Enterprise Service Busdeploying to 116

IBM Business Process Manager, version7.5.0.2, information 222

IBM Integration Designerinformation 222test environment 113

IBM WebSphere Adapter for Flat Filesadministering 129

IBM WebSphere Adapter Toolkit 222developerWorks resources 222

IBM WebSphere Enterprise Service Businformation 222

implementation, Java 114import, export 2importWebSphere Adapter for Flat

Files 2inbound

configuration properties 191inbound processingWebSphere Adapter

for Flat Files 13Include only the newly appended content

property 23Include total business object count in the

ChunkInfo 196Incomplete file processing 155installing EAR file 118integrated processes 1interaction specification properties

changing 111Interaction specification properties

archive directoryretrieve operation 185

create a new file if the file does notexist 185


Interaction specification properties(continued)

default target file name 185delete the file after retrieve

operation 185delimiter between business objects in

the file 185file content encoding 185generate a unique file 185output directory 185specify criteria to split file

content 185split function class name 185staging directory 185

Interfaceoperations


introductionWebSphere Adapter for FlatFiles 1

JJava implementation 114

Kknowledge base 162

LList 3, 6load balancing 38, 215local event directory 160locking 155Log Analyzer 129log and trace

configure 129Log and Trace Analyzer, support for 151log and trace files 151log files

changing file name 131disabling 129enabling 129level of detail 129location 131SystemOut.log 131

loggingconfiguring properties with

administrative console 129logging level 129

Mmanaged (J2C) connection factory

propertiessetting in administrative console 134,

139Managed connection properties

default target file name 177output directory 177sequence file 177staging directory 177

matrix, compatibility 1

messageexception

version 151messages, adapter 222migration 47

adapter-specific artifacts 50artifacts

adapter-specific 50considerations

compatibility with earlierversions 41

migrating applications fromWebSphere InterChange Server

roadmap 47overview 47performing migration 43upgrading a project 46WebSphere InterChange Server

migrationmigration roadmap 47

WebSphere InterChange Servermigration wizard 49

moduleadding to the server 114configuring

road map 57configuring for deployment

overview 57configuring inbound processing 93configuring outbound processing 80creating 59deploy for testing 113

monitoring performance 143multiple connection 201

Nnode level 122, 124notification 23

Ooperations 3, 4, 6, 7

exists 6org.xml.sax.SAXParseException 158out of memory

exception 155outbound 3, 4, 6, 7

processing 3supported operations 3

outbound configuration properties 173outbound operations

append 3create 3delete 3exists 3list 3overwrite 3retrieve 3

outbound processingtesting the module 115

Overwrite 6

Ppackage files for adapters 130passive adapter 158patterns 74performance monitoring

infrastructure 143configuring 143performance statistics 145

Performance Monitoring Infrastructure(PMI)

configuring 143description 143viewing performance statistics 145

performance statistics 145persistent cache 17planning adapter

implementationWebSphere Adapter forFlat Files 33

PMI (Performance MonitoringInfrastructure)

configuring 143viewing performance statistics 145

Poll event files for modified contentproperty 23

Polling based on calendar 93privilegesWebSphere Adapter for Flat

Filesaccess 33

problem determinationorg.xml.sax.SAXParseException

exception 158self-help resources 149, 163solutions to common problems 159XAResourceNotAvailableException

exception 156project interchange (PI) file

project interchange files 46projects 46updating without migrating 46

project, creating 79properties

activation specification 136, 140configuration properties


inbound configuration 191JNDI 124managed (J2C) connection

factory 134, 139outbound configuration 173resource adapter 120, 122, 124, 132,

138properties information

guide 173, 191Property, time interval for polling

unchanged files 155

RRAR (resource adapter archive) file

description 116installing on server 116

recommended fixes 149, 163Redbooks, IBM WebSphere

Adapters 222related products, information 222

Index 231

remote archive directory 160Required local folders

creating 58requirements

hardware 1software 1

resource adapter archive (RAR) filedescription 116installing on server 116

resource adapter propertiesadapter ID 215setting in administrative console 132,

138Resource adapter properties

adapter ID 183details 183, 215enable HA support 183, 215

Retrieve 7Retry limit property 207road map for configuring the module 57roadmap for migrating

WebSphere InterChange Serverapplications 47

Rule Table 152runtime environment

deploying EAR file 116

Ssamples 55, 222SDOX (Service Data Objects - XML

Cursor Interface) mode 153global elements 153

security 33disguising sensitive data 33

self-help resources 149, 163sensitive data, disguising 33sequence file 160Sequence file 4software requirements 1sql scripts 45stand-alone adapter 140

considerations for using 36managed connection factory

properties, setting 139resource adapter properties,

setting 138usage considerations 34

stand-alone adapterschanging configuration

properties 138setting activation specification

properties 140setting managed (J2C) connection

factory properties 139setting resource adapter

properties 138starting adapter applications 142, 162startingIBM Integration Designer 62, 79stopping adapter applications 142, 162structure 19support

overview 149plug-in for IBM support

assistant 149, 163self-help resources 149, 163web site 149, 163

supported operations 3, 6, 7append 3create 4

SystemOut.log file 131

TTable name to store the file processing

status 196target component 113technical overview 2technotes 1, 149, 163test environment 113

adding module to 114deploying to 114testing modules 115

Time interval for polling unchanged filesproperty 23

Time interval for processing the fetchedevents 196

trace fileschanging file name 131disabling 129enabling 129level of detail 129location 131trace.log 131

tracingconfiguring properties with

administrative console 129troubleshooting

org.xml.sax.SAXParseExceptionexception 158

overview 149self-help resources 149, 163

tutorials 55, 222

UUnique file

prefix 80suffix 80

unique file names, generating 12UNIX 155UNORDERED 201

Vversion conflict 151

Wwebservices 157WebSphere Adapters, version 6.0,

information 222WebSphere Adapters, version 6.2.x,

information 222WebSphere Application Server

information 222WebSphere business integration

adapters 47WebSphere Business Integration Adapters

information 222WebSphere Extended Deployment 38wiring components 113

WSDL 157

XXAResourceNotAvailableException 156XID (transaction ID) 17


��

Printed in USA

flatfiles book

Documents

ibm websphere adaptersversion

fix pack

data handlers

data type

data binding

copyright ibm corporation

setting deployment properties

adapter patternwizard