IBM WebSphere Business Integration Adapter User Manual
IBM WebSphere Business Integration Ad apters
A d apter fo r i2 User Guid e
Adapter Version 1. 0.x
IBM WebSphere Business Integration Ad apters
A d apter fo r i2 User Guid e
Adapter Version 1. 0.x
Note!
Before using this information and the product it supports, read the information in Appendix D, “Notices”, on page 77.
18April2003
This edition of this document applies to IBM WebSphere InterChange Server, version 4.2, WebSphere Business
Integration Adapters, version 2.2.0, and to all subsequent releases and modification until otherwise indicated in new
editions.
To send us your comments about this document, email doc-comments@us.ibm.com. We look forward to hearing
from you.
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 2002, 2003. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Integration broker compatibility
Supported on IBM WebSphere Business Integration Adapter Framework versions
2.2.0, IBM WebSphere InterChange Server versions 4.1.1 and 4.2, WebSphere MQ
Integrator version 2.1.0, and WebSphere MQ Integrator Broker, version 2.1.0.
See Release Notes for any exceptions.
© Copyright IBM Corp. 2002, 2003 iii
iv Adapter for i2 User Guide
Contents
Integration broker compatibility .........................iii
About this document .............................vii
Audience ....................................vii
Related documents .................................vii
Typographic conventions ...............................vii
Chapter 1. Overview of the connector .......................1
Connector architecture ................................1
How the connector works ...............................3
Chapter 2. Installing and configuring the connector .................7
Prerequisites for installing the connector ..........................7
Installing the connector on a Windows or UNIX system .....................7
Configuring the connector ...............................8
Starting the connector ................................10
Chapter 3. Understanding business objects for the connector ............11
Defining connector metadata .............................11
Overview of business object structure...........................11
i2 business object structure ..............................12
Specifying business object attribute properties ........................14
Identifying business object application-specific information ...................15
Chapter 4. Generating business objects using i2 ODA ...............17
Overview of i2 ODA ................................17
Installing i2 ODA .................................17
Using i2 ODA in Business Object Designer .........................19
Create the metaobject for polling ............................25
Chapter 5. Troubleshooting and error handling ..................27
Logging error messages ...............................27
Tracing messages .................................30
Tips for troubleshooting ...............................31
Appendix A. Standard configuration properties for connectors ...........33
New and deleted properties ..............................33
Configuring standard connector properties for WebSphere InterChange Server .............34
Configuring standard connector properties for WebSphere MQ Integrator ..............46
Appendix B. Connector Configurator .......................55
Using Connector Configurator in an internationalized environment.................55
Starting Connector Configurator ............................56
Choosing your broker ................................57
Using a connector-specific property template ........................58
Using Connector Configurator with ICS as the broker .....................61
Setting the configuration file properties (ICS) ........................63
Setting the configuration file properties (WebSphere MQ Integrator Broker) ..............68
Using standard and connector-specific properties with Connector Configurator.............71
Completing the configuration .............................72
Appendix C. Connector feature list .......................73
Event notification features ..............................73
© Copyright IBM Corp. 2002, 2003 v
Service call request handling features ...........................73
General features ..................................74
Appendix D. Notices ..............................77
Programming interface information ...........................78
Trademarks and service marks .............................78
vi Adapter for i2 User Guide
About this document
IBM(R) WebSphere(R) Business Integration Adapters supply integration
connectivity for leading e-business technologies and enterprise applications.This
document describes the installation, configuration, and business object
development for the adapter for i2..
This document describes the installation, configuration, troubleshooting, and
business object development for the connector component of the IBM WebSphere
Business Integration Adapter for i2.
Audience
This document is for consultants, developers, and system administrators who use
the connector at customer sites.
Related documents
The complete set of documentation available with this product describes the
features and components common to all WebSphere Business Integration Adapter
installations, and includes reference material on specific components.
To access the documentation, go to the directory where you installed the product
and open the documentation subdirectory. If a welcome.html file is present, open it
for hyperlinked access to all documentation. If no documentation is present, you
can install it or read it directly online at one of the following sites:
v If you are using WebSphere MQIntegrator as your integration broker:
http://www.ibm.com/websphere/integration/wbiadapters/infocenter
v If you are using InterChange Server as your integration broker:
http://www.ibm.com/websphere/integration/wicserver/infocenter
The documentation set consists primarily of Portable Document Format (PDF) files,
with some additional files in HTML format. To read it, you need an HTML
browser such as Netscape Navigator or Internet Explorer, and Adobe Acrobat
Reader 4.0.5 or higher. For the latest version of Adobe Acrobat Reader for your
platform, go to the Adobe website (www.adobe.com).
Typographic conventions
This document uses the following conventions:
courier font
italic, italic Indicates a new term the first time that it appears, a variable
blue text Blue text, which is visible only when you view the manual
{}
© Copyright IBM Corp. 2002, 2003 vii
Indicates a literal value, such as a command name, file
name, information that you type, or information that the
system prints on the screen.
name, or a cross-reference.
online, indicates a cross-reference hyperlink. Click any blue
text to jump to the object of the reference.
In a syntax line, curly braces surround a set of options from
which you must choose one and only one.
|
[]
...
<>
/, \
%text% and $text Text within percent (%) signs indicates the value of the
In a syntax line, a pipe separates a set of options from which
you must choose one and only one.
In a syntax line, square brackets surround an optional
parameter.
In a syntax line, ellipses indicate a repetition of the previous
parameter. For example, option[,...] means that you can
enter multiple, comma-separated options.
Angle brackets surround individual elements of a name to
distinguish them from each other, as in
<server_name><connector_name>tmp.log.
In this document, backslashes (\) are used as the convention
for directory paths. For UNIX installations, substitute slashes
(/) for backslashes. All product pathnames are relative to the
directory where the connector for i2 is installed on your
system.
Windows text system variable or user variable. The
equivalent notation in a UNIX environment is $text,
indicating the value of the text UNIX environment variable.
viii Adapter for i2 User Guide
Chapter 1. Overview of the connector
This chapter describes the connector component of the IBM WebSphere Business
Integration Adapter for i2 and the relevant business integration system
architecture.
The i2 connector integrates with i2 application modules through i2’s Common
Integration Services (CIS) API. CIS API from i2 is an implementation of JCA
Common Client Interface. i2 has a suite of application modules that support CIS.
The i2 connector is metadata driven, has object discovery capability, and enables
integration to any version 6.0 SDK CIS-enabled i2 application. Many i2 modules
versions 5.2 and above, support version 6.0 CIS SDK. This connector is available
on Windows, Solaris, and AIX.
Connectors consist of two parts: the application-specific component and the connector
framework. The application-specific component contains code tailored to a particular
application or technology (in this case, i2). The connector framework, whose code
is common to all connectors, acts as an intermediary between the integration
broker and the application-specific component. The connector framework provides
the following services between the integration broker and the application-specific
component:
v Receives and sends business objects
v Manages the exchange of startup and administrative messages
Note: This document contains information about both the connector framework
and the application-specific component. It refers to both of these as the
connector.
For more information about the relationship of the integration broker to the
connector, see IBM WebSphere InterChange Server System Administration Guide or IBM
WebSphere Business Integration Adapters Implementation Guide for MQ Integrator
Broker.
This chapter contains the following sections:
v “Connector architecture” on page 1
v “How the connector works” on page 3
Connector architecture
i2’s Common Integration Service (CIS) enables connectivity between external
applications and i2 application modules.
CIS includes three primary components:
v CIS Front Bus--used by applications to specify an XML metadata format
interface that details the available functions and their expected input and output
data. CIS scripts generate the required representations of input and output data
in an XML schema and Java Beans. Product teams implement these functions by
writing handlers in Java that implement standard CIS interfaces and perform the
required logic. These handlers can deal with data as XML or Java Beans. CIS
infrastructure deploys these interfaces so that the client can invoke this
functionality from a variety of resources.
© Copyright IBM Corp. 2002, 2003 1
v CIS Back Bus--used by applications to create a bulk import/export interface for
data transfers.
v CIS Single Sign-On--a standard set of Java interfaces used by Web applications
to authenticate users against a central authentication. store.
The i2 connector interacts with the CIS Front Bus using the CIS Client API
provided by i2 along with its CIS adapters. CIS Client API is the implementation
of JCA Common Client Interface. CIS adapters operate based on CIS metadata
information using the various bindings.
The following diagram shows the i2 connector and components of the i2
framework.
I2 Application
modules
Ex:OM
Integration broker
XML DH
WBIA API
CIS server
I2 connector
Event notification
BOHandler
CIS message
CIS agent
CIS adapter
The following table describes the terminology used for the components of the i2
connector and framework.
Component Description
CIS Common Integration Services provided by i2 to enable connectivity
between the external applications and i2 application modules
OM Order Management, just an example of an i2 application module
CIS agent CIS server application that runs on a central server. It maintains
connection information about client applications and manages and
monitors all the client applications that are part of the solution. The CIS
adapter and i2 application modules register with the CIS agent.
JCA CCI Java Connector Architecture’s Common Client Interface
CIS adapter i2’s CIS Client API and implementation of JCA-CCI
WBIA API API used by the i2 connector to communicate with the designated
integration broker.
integration
broker
XML DH IBM’s data handler (DH) used to transform XML messages to the IBM
A program that handles the execution of the business object processing
logic. Supported brokers are ICS and WMQI.
business objects and vice versa. You need to configure the XML DH for
use with the i2 connector.
2 Adapter for i2 User Guide
Component Description
CIS server Integration container which handles operation invocations. Integration
How the connector works
The i2 connector is a CIS (Common Integration Services) client. It connects to the
CIS client API in a non-managed environment, that is, it connects to the CIS
adapter directly without an application server. No authentication is necessary (no
user name or password is required). At present, the CIS client API does not
support any connection pooling mechanism. Hence, connections are created for
every transaction. For information on configuration properties, see “Configuring
the connector” on page 8.
The i2 connector is bi-directional. It can process events originating from i2
applications, as well as requests sent by the broker to the application.
For event subscriptions, the i2 connector uses the information in the i2 metaobjects.
It registers the operations on the types specified in these metaobjects with i2’s CIS
agent. CIS agent listens to the registered operations and detects event messages
only for registered operations. The i2 connector obtains these messages with the
poll call.
container and CIS server are used interchangeably in this document.
For request processing, the i2 connector processes the requests coming from the
integration broker by transforming incoming business objects into CIS records and
using the appropriate CIS Client API calls to execute the operation on the i2
application modules.
The i2 connector follows the metadata design principles outlined in the IBM
Connector Developer’s Guidelines. This means new IBM business objects can be
defined without additional coding or customization at the i2 connector code level.
For more information, see Chapter 3, “Understanding business objects for the
connector”, on page 11.
Processing subscriptions
The following sections describe how the connector processes application events.
Event detection and notification
Events for the purpose of this document are the CIS messages published from the
i2 application modules. The i2 application notifies the connector of all the events
occurring in the modules for which corresponding operations have been registered
with the CIS agent.
The onus of registering the operations of interest lies with the i2 connector.
Example: If the i2 connector is interested in the Bidding type operation addBid,
any new Bidding additions to the i2 application module will be queued in the CIS
server once the i2 connector registers for the addBid operation.
The i2 connector uses the information in the i2 metaobjects. It registers its intent to
listen to some of the operations with the poll call. Effectively, this tells the CIS
agent that the i2 connector wants to check for the output of the registered
operations.
Chapter 1. Overview of the connector 3
Status updates
No status updates are made to the i2 applications. Typically, the event status, for
example, SUCCESS, FAIL, UNSUBSCRIBED, is written to the application’s event
store. Since no event store is maintained for i2, the status update strategy is not
relevant for the i2 connector. Error messages, if any, are logged to the i2 adapter
log file. For more information, see Chapter 5, “Troubleshooting and error
handling”, on page 27.
Event retrieval
For the i2 connector, polling is single threaded. The connector uses i2 metaobjects
to register the operations of interest with the CIS agent for polling. These
metaobject names have the i2MO prefix and store information about the operation
and the corresponding IBM wrapper business object name for the specified
operation and type. The attributes for the metaobject are specified as static default
values. Default value is an attribute property, which can be set at the business
object design time. For information on the wrapper business object structure and
attribute properties, see Chapter 3, “Understanding business objects for the
connector”, on page 11 and Chapter 4, “Generating business objects using i2 ODA”,
on page 17.
The steps involved in retrieving a subscription message are as follows:
1. The i2 connector registers the operations with the CIS agent after reading the
i2MO metaobject information. The information in the metaobjects is cached by
the i2 connector with the first poll call.
2. Each poll call is issued from the integration broker based on the connector
property PollFrequency. In case there were any registration failures in the first
poll call, the i2 connector tries to register the same operation with the
subsequent poll calls.
3. With all the poll calls, the i2 connector checks on the output of the operations
that it has registered with the CIS agent. If there is any output from any of the
operations, it retrieves the output in the form of a CIS record. The i2 connector
retrieves the PollQuantity (connector property) number of messages for each
poll call for each registered operation.
Example: If the PollQuantity is set to 5 and there are 5 registered operations,
each poll call will result in checking the output 25 times. If the PollQuantity is
not set, a default of 1 message is retrieved for each poll call for each operation.
4. The retrieved XML message is converted to a business object. The business
object is set as the child attribute in the wrapper business object for the
operation. The instance ID from which this output was retrieved is set as the
instance ID in the metaobject attribute of the wrapper. For more information,
see Chapter 3, “Understanding business objects for the connector”, on page 11.
5. The connector sends the wrapper business object to the integration broker for
further processing.
Processing verbs (operations)
Operations are i2’s equivalent for verbs and are defined by the XML structure
provided by i2 for each port. For more information, see Chapter 3, “Understanding
business objects for the connector”, on page 11, and Chapter 4, “Generating
business objects using i2 ODA”, on page 17.
Processing service call requests
When the i2 connector receives a service call request from an integration broker to
perform an operation in an application, the request takes the form of a wrapper
business object. The wrapper business object encompasses the instance ID
4 Adapter for i2 User Guide
metaobject (MO_Instance) and the input and output business objects as its
children. The verb for the wrapper business object must be a valid operation for
the specified instance.
The information about the child business object, whether it is an input or output
type, is obtained from the Application Specific Information (ASI) of the wrapper
business object’s attributes.
Example: ASI Type=input indicates that the child business object is of input type.
The input child business object is first converted to an XML message by the XML
data handler. The business object is then transformed into a CIS record using the
CIS utility. Then the operation is executed using the CIS Client API.
If the operation sends some output XML message, it is converted to an output
child business object; and the output child business object in the wrapper business
object is populated with the appropriate value.
Status updates
Any error conditions that occur while processing are logged as detailed error
messages in the adapter log.
ReturnStatusDescriptor: The connector populates a structure called the
ReturnStatusDescriptor with the message and status of the latest error that
occurred during the processing of a service call request. You can access the
ReturnStatusDescriptor to find the reason for the cause of a failure during a service
call request. The adapter framework propagates the structure, as appropriate.
Chapter 1. Overview of the connector 5
6 Adapter for i2 User Guide
Chapter 2. Installing and configuring the connector
This chapter describes how to install and configure the connector component of
IBM WebSphere Business Integration Adapter for i2 and how to configure
applications to work with the connector. It contains the following sections:
v “Prerequisites for installing the connector” on page 7
v “Installing the connector on a Windows or UNIX system” on page 7
v “Configuring the connector” on page 8
v “Starting the connector” on page 10
Prerequisites for installing the connector
Before you install the connector, be sure that your system has the required
hardware and software for using the connector.
Required hardware and software:
v Applications:
– CIS SDK 6.0
– J2EE.jar
– Appropriate CIS adapter (MetadataService adapter is required for i2 ODA)
v One of the following application platforms:
– Windows: 2000
– UNIX: Solaris, HP, or AIX
v One of the following adapter platforms:
– Windows: NT, 2000
– UNIX: Solaris 8.0, or AIX 4.3
Note: For instructions on installing the software and installing prerequisites
specific to your integration broker, see IBM WebSphere Business Integration
Adapter Implementation Guide for MQ Integrator Broker; or for InterChange
Server, see IBM WebSphere InterChange Server System Installation Guide for
UNIX or for Windows.
As part of the default software installation, the data handlers are installed to
your system. When you install the i2 connector from Passport Advantage,
the XML data handler is also installed. For the procedures to configure the
data handlers for the connector, see IBM WebSphere Business Integration
Adapter Data Handler Guide.
Installing the connector on a Windows or UNIX system
This section describes how to install the connector on a Windows or UNIX system.
Step for installing the standard files
Before you begin: You need to have WebSphere InterChange Server on your
system.
Perform the following step to install the standard files associated with the i2
connector:
© Copyright IBM Corp. 2002, 2003 7
v Run the Installer utility for IBM WebSphere Business Integration Adapters from
the product CD and select the IBM WebSphere Business Integration Adapter for
i2.
The utility allows you to browse and select the directory into which it will
install the connector subdirectories and files. You must install to the
%ProductDir% product directory that you used for your installation of the IBM
WebSphere InterChange Server system. Use the browse button in the Installer to
locate the directory and select it.
Result: The Installer utility copies the standard files into your system.
Tip: After you have installed your business integration system, you can install
additional connectors from the product CD-ROM at any time. To do this, insert the
product CD-ROM, run the installation program, and choose the connectors that
you want to install.
Installed file structure
The following table describes the file structure used by the connector and shows
the files that are automatically installed with Installer.
Notes:
1. This document uses (\) backslashes as the convention for directory paths. For
UNIX installations, substitute slashes (/) for backslashes.
2. All product path names are relative to the directory where the product is
installed on your system.
3. For Windows, Installer adds an icon for the connector file to the IBM
WebSphere Business Integration Adapters menu. For a fast way to start the
connector, create a shortcut to this file on the desktop.
Subdirectory of %ProductDir% Description
connectors\i2 Contains the connector CWi2.jar file, Version 1.0.0, which
has the connector code and the start_i2.bat files (WIN) or
start_i2.sh files (UNIX).
connectors\messages Contains the i2Adapter.txt file for error messages.
repository\i2 Contains the CN_i2.txt file.
connectors\i2\Sample Contains sample files for creating business objects.
For more information on installing the connector component, see one of the
following guides, depending on the integration broker you are using:
v IBM WebSphere InterChange Server System Installation Guide for your platform
(when usingthe WebSphere InterChange Server as the integration broker)
v IBM WebSphere Business Integration Adapters Implementation Guide for MQIntegrator
Broker (when using WebSphere MQIntegrator as the integration broker)
Configuring the connector
Connectors have two types of configuration properties: standard configuration
properties and connector-specific configuration properties. You must set the values
of these properties before running the connector. As you enter the configuration
values, they are saved in the repository.
To configure connector properties, use one of the following tools:
v Connector Designer--if ICS is the integration broker
8 Adapter for i2 User Guide
Tip: Access this tool from the System Manager.
v Connector Configurator--if WebSphere MQIntegrator is the integration broker
Tip: Access this tool from the IBM WebSphere Business Integration Adapter
program folder.
For more information about Connector Configurator, see Appendix B,
“Connector Configurator”, on page 55.
A connector obtains its configuration values at startup. During a run-time session,
you may want to change the values of one or more connector properties. Changes
to some connector configuration properties, such as AgentTraceLevel, are dynamic,
taking effect immediately. Changes to other connector properties are static,
requiring component restart or system restart after a change. To determine whether
a property is dynamic or static, refer to the update method column in Connector
Designer.
Standard connector properties
Standard configuration properties provide information that all connectors use. For
detailed information about these properties, see Appendix A, “Standard
configuration properties for connectors”, on page 33.
Note: Because the connector for i2 supports both the ICS and WebSphere
MQIntegrator integration brokers, configuration properties for both brokers
are relevant to the connector.
In addition, the following supplemental information on standard connector
properties applies to i2.
LogAtInterchangeEnd
Tells whether to log errors on the InterChange Server (ICS).
The default value is false.
MessageFileName
Path of the error message file if it is not located in the standard message location
%ProductDir%\connectors\messages. If the message file name is not in a fully
qualified path, the message file is assumed to be located in the directory specified
by the HOME environment variable or the startup parameter user.home.Ifa
connector message file does not exist, the WBIA API message file is used. If that
file does not exist, the InterchangeSystem.txt file is used as the message file.
The default value is i2Adapter.txt.
Connector-specific properties
Connector-specific configuration properties provide information needed by the
connector at run time. They also provide a way of changing static information or
logic within the connector without having to recode and rebuild it.
The following table lists the connector-specific configuration properties for the
connector along with their descriptions and possible values.
Property Description Possible values
ApplicationName Unique name specified for each
connector
Chapter 2. Installing and configuring the connector 9
i2Adapter
Property Description Possible values
ApplicationUserName User name for the i2 connection Not used in this release
ApplicationPassword Password for the i2 connection Not used in this release
CISAgentHostName Used when the CIS agent is running on
a remote machine. If it is not set, the
current local host is assumed to have the
CIS agent running. If it is set, the i2
connector establishes a connection with
this remote host.
ExecutionTimeout Time in milliseconds before the call
to i2 application terminates.
PollQuantity Number of messages that will be
retrieved from the client queue; it will be
pollQuantity multiplied by the number
of registered operations.
UseDefaults The connector checks for this value to
look for the default value of the
attributes during request processing.
This is not used by the i2 connector.
String host name
Example: any machine name
like California
Default is 30000
Default is 1
Not required for this connector
Configuring start_i2.bat (for Windows) or start_i2.sh (for UNIX)
You need to add the proper path to the start files for CIS-SDK and j2ee.jar.
Example: The following path information needs to be added to start_i2.bat file:
set I2_CIS_HOME_DIR=C:\i2\CIS\6.0\cis-sdk
set J2EE_PATH=C:\J2EE_JAR
Note: These are just examples. You should change the path information depending
on your local installation.
Configuring DataHandler
You also need to configure the data handler. Set the following values for the child
business object text/xml in MO_DataHandler_Default:
Validation false
ClassName com.crossworlds.DataHandlers.text.xml
UseNewLine false
InitialBufferSize any appropriate value like 2097152
DummyKey 1
Note: The rest of the fields should be blank.
For detailed information about data handler configuration, see IBM WebSphere
Business Integration Adapters Data Handler Guide.
Starting the connector
For information on starting and stopping a connector, see one of the following
documents, depending on the integration broker you are using:
v IBM WebSphere System InterChange Server Installation Guide for your platform
(when using InterChange server as the integration broker)
v IBM WebSphere Business Integration Adapters Implementation Guide for MQIntegrator
(when using WebSphere MQIntegrator Broker as the integration broker)
10 Adapter for i2 User Guide
Chapter 3. Understanding business objects for the connector
This chapter describes the structure of i2 business objects, how the connector
processes the business objects, and the assumptions the connector makes about
them. Use this information as a guide to modifying existing business objects for i2
or as suggestions for implementing new business objects.
The chapter contains the following sections:
v “Defining connector metadata” on page 11
v “Overview of business object structure” on page 11
v “i2 business object structure” on page 12
v “Specifying business object attribute properties” on page 14
v “Identifying business object application-specific information” on page 15
For information on the Object Discovery Agent (ODA) utility that automates the
creation of business objects for the IBM WebSphere Business Integration Adapter
for i2, see Chapter 4, “Generating business objects using i2 ODA”, on page 17.
Defining connector metadata
The i2 connector is metadata-driven. In the WebSphere business integration system,
metadata is application-specific information that is stored in a business object and
that helps the connector interact with the application. A metadata-driven connector
handles each business object that it supports based on the metadata encoded in the
business object definition rather than on instructions hardcoded in the connector.
Business object metadata includes the structure of the business object, the settings
of its attribute properties, and the content of its application-specific information.
Because the connector is metadata-driven, it can handle new or modified business
objects without requiring modifications to the connector code.
The connector makes assumptions about the structure of its supported business
objects, the relationships between parent and child business objects, and the format
of the application-specific information.
Therefore, when you create or modify a business object, your modifications must
conform to the rules the connector is designed to follow, or the connector will not
be able to process new or modified business objects correctly.
Overview of business object structure
In the WebSphere business integration system, a business object definition consists
of a type name, supported verbs, and attributes. An application business object is
an instance of a business object definition. It reflects a specific application’s data
structure and attribute properties.
Some attributes, instead of containing data point to child business objects or arrays
of child business objects that contain the data for these objects. Keys relate the data
between the parent record and child records.
WebSphere Business Integration Adapter business objects can be flat or
hierarchical. A flat business object only contains simple attributes, that is, attributes
that represent a single value (such as a String) and do not point to child business
© Copyright IBM Corp. 2002, 2003 11
objects. A hierarchical business object contains both simple attributes and child
business objects or arrays of child business objects that contain the values.
A cardinality 1 container object, or single-cardinality relationship, occurs when an
attribute in a parent business object contains a single child business object. In this
case, the child business object represents a collection that can contain only one
record. The type of the attribute is the same as that of the child business object.
A cardinality n container object, or multiple-cardinality relationship, occurs when
an attribute in the parent business object contains an array of child business
objects. In this case, the child business object represents a collection that can
contain multiple records. The type of the attribute is the same as the type of the
array of child business objects.
A hierarchical business object can have simple attributes and can also have
attributes that represent a single-cardinality child business object or an array of
child business objects. In turn, each of these business objects can contain
single-cardinality child business objects and arrays of business objects, and so on.
In each type of cardinality, the relationship between the parent and child business
objects is described by the application-specific text of the key attribute of the child
object.
i2 business object structure
The i2 IBM business object is the IBM representation of the i2 message. Each type
of message has a corresponding IBM business object.
The business objects are generated using the WebSphere Business Integration
Adapter utility XML ODA, which reads the XML schema files for these types and
generates the corresponding IBM business object. (See Chapter 4, “Generating
business objects using i2 ODA”, on page 17 and Chapter 3, ″XML data handler″ in
IBM WebSphere Business Integration Adapters Data Handler Guide.)
The i2 business object is a wrapper business object that encapsulates a metaobject,
an operation, and input and/or output data (one or the other, both, or none) types
for the operation. There is one wrapper business object for each operation. For
more information, see Chapter 4, “Generating business objects using i2 ODA”, on
page 17.
The following diagram shows the parts of a wrapper business object. A description
of each part follows the diagram.
Wrapper BO
Supported Verb=
Operation
Metaobject (MO Instance)
Input type BO
Output type BO
v The metaobject embedded within the wrapper is used to configure the instance
12 Adapter for i2 User Guide
ID. For more information, see “Configuring metaobjects for polling” on page 13.
v The operation is set as the verb on the wrapper business object and is associated
with a port. i2 does not have standard verbs. If multiple operations have the
same set of input and output types, but are supported on different ports, there
will be two different wrapper business objects for the different ports.
v The types are business object attributes which represent data types for an
operation.
The following diagram illustrates a sample business object IBM_Bidding_BO,
which has three child business objects. In the diagram:
v IBM_OptParams and IBM_OptimizationResults represent the top level business
object generated by the XML ODA.
v The application-specific information for the business object is in the Port
(Bidding) and Types (input--IBM_OptParams and output--
IBM_OptimizationResults) attributes.
v The operation is addBid.
v The child business objects are:
– IBM_OptParams, which has two attributes--LaneId and Price
– IBM_OptimizationResults, which has one attribute--WinningBid
– MO_Instance, which has one attribute--InstanceId
IBM_Bidding_BO
Port=Bidding
IBM_OpParams
Type=input
IBM_OptimizationResults
Type=output
MO_Instance
Verb=addBid
IBM_OptParams
LaneId
Price
Configuring metaobjects for polling
The connector uses i2 metaobjects to register its interest in specific operations with
the CIS agent so that polling can take place. You need to configure one metaobject
for each operation of interest.
The metaobject name always starts with i2MO. Each metaobject holds information
about the instance that supports the operation and the wrapper business object
name for the operation. You need to add a dummy verb to all the metaobjects.
The attributes (instance ID, wrapper business object name, and operation name)
within the metaobjects have a static default value. For registering the same
operation on a different instance, you either have to change the default value and
restart the i2 instance or configure another metaobject for the new instance.
IBM_OptimizationResults
WinningBid
MO_Instance
InstanceId
In the following diagram, the metaobject named i2MO_AddBid is used to
configure the instance ID CA_Instance, for the Bidding operation addBid, which is
set on the wrapper business object named IBM_Bidding_BO. The values shown are
default values for the attributes.
Chapter 3. Understanding business objects for the connector 13
I2MO_AddBid
InstanceId=CA_Instance
WrapperBOName=IBM_Bidding_BO
Verb=Dummy
Specifying business object attribute properties
The i2 connector has various properties that you can set on its business object
attributes. This section describes how the connector interprets several of these
properties and describes how to set them when modifying a business object.
The following table shows the properties for simple attributes.
Attribute Description
Name Unique name of the attribute
Type All simple attributes should be of type String.
MaxLength Not used
IsKey Each business object must have at least one key attribute, which you
specify by setting the key property to true for an attribute. The i2
connector does not check for this property.
IsForeighKey Not used.
Is Required Set to true if the attribute must have a value in the outgoing XML
message.
AppSpecInfo Not used
DefaultValue Specifies a default value that the connector uses for a simple attribute in
the inbound business object if the attribute is not set and is a required
attribute.
The following table shows the properties for child object attributes.
Attribute Description
Name Name of the child object.
Type Business object type for the child.
Contained
ObjectVersion
Relationship If the child is a container attribute, this is set to Containment.
IsKey Not used
IsForeighKey Not used.
Is Required For relationship details between XML elements and requiredness, see
14 Adapter for i2 User Guide
Rule: You must set and use the default value for the attributes of the
polling metaobjects and MO_Instance metaobject. If the default value is
set for the instance ID, and no value is set in the incoming business
object, the connector takes the default value and tries to connect with
this instance.
For all attributes that represent child business objects, this property
specifies the child’s business object version number.
Chapter 3, ″XML data handler,″ in IBM WebSphere Business Integration
Adapters Data Handler Guide.
Attribute Description
AppSpecInfo For information on this property, see “Identifying business object
application-specific information” on page 15,
Cardinality For relationship details between XML elements and cardinality, see
Chapter 3, ″XML data handler,″ in IBM WebSphere Business Integration
Adapters Data Handler Guide.
Special attribute values
Simple attributes in business objects can have the special value, CxIgnore. When it
receives a business object from the integration broker, the connector ignores all
attributes with a value of CxIgnore. It is as if those attributes were invisible to the
connector. No XML is generated for them.
Because the i2 connector requires at least one primary key attribute to create a
business object, you need to ensure that business objects passed in to the connector
should have at least one primary key that is not set to CxIgnore.
Additionally, The i2 connector assumes that no attribute of business object type has
a value of CxBlank. Simple (String) attributes with a value of CxBlank are included
in an XML document. Empty double quotation marks (″″) in an XML document are
used as the PCDATA equivalent of CxBlank.
Identifying business object application-specific information
Application-specific information provides the connector with applicationdependent instructions on how to process business objects. If you extend or modify
an application-specific business object, you must make sure that the
application-specific information in the business object definition matches the syntax
that the connector expects.
Application-specific information at the business object- level
The following table provides application-specific information at the business
object-level for the wrapper business object supported by the i2 connector.
Parameter Description
Port= The name of the i2 port type for the operation.
Application-specific information at the attribute level
The following table provides application-specific information at the attribute level
for the wrapper business object supported by the i2 connector.
Parameter Description
Type= The type represented by the attribute at the wrapper business object
attribute level. The type could be input or output representing the input
and output for the operation.
Chapter 3. Understanding business objects for the connector 15
16 Adapter for i2 User Guide
Chapter 4. Generating business objects using i2 ODA
This chapter describes i2 ODA, an object discovery agent (ODA), which, working
with XML schema ODA, generates business objects for the IBM WebSphere
Business Integration Adapter for i2.
This chapter contains the following sections:
v “Overview of i2 ODA” on page 17
v “Installing i2 ODA” on page 17
v “Using i2 ODA in Business Object Designer” on page 19
Overview of i2 ODA
i2 Object Discovery Agent (ODA) is a utility to use to obtain the specifications for
the i2 business object from the metadata information in i2’s CIS registry. The
Business Object Development wizard automates the process. You can view or make
modifications to the business object before saving it to the server.
The process for generating an i2 business object has three distinct stages:
1. Identifying the ports, operations, and types for which i2 ODA generates the
schema files; generating the XML schema for the types; and generating the
wrapper business object representing the operations with the types as
attributes.
2. Processing the i2 generated XML schema files and converting the XML schema
to the actual business object for the type.
3. Prior to saving the wrapper business object, saving to the repository the
MO_Instance business object and the business objects that were generated for
the types using XML ODA.
For details, see “Steps for using i2ODA” on page 20.
Installing i2 ODA
This section describes how to install and launch i2 ODA, run multiple instances of
i2 ODA, and work with error and trace message files.
Steps for installing i2 ODA
Before you begin: This chapter assumes you have already installed the i2
connector, as well as the required software for using the connector (see Chapter 2,
“Installing and configuring the connector”, on page 7). Be sure you are using i2
application version 6.0 and i2 ODA 1.0.0.
To install i2 ODA, use the Installer for IBM WebSphere Business Integration
Adapters. Follow the instructions in IBM WebSphere Business Integration Adapters
Implementation Guide for MQIntegrator or for InterChange Server (ICS),orIBM
WebSphere Business Integration System Installation Guide for UNIX or for Windows.
When the installation is complete, the following files are installed in the directory
on your system where you have installed the product:
v ODA\i2\i2ODA.jar
v ODA\messages\i2ODAAgent.txt
© Copyright IBM Corp. 2002, 2003 17
v ODA\i2\start_i2ODA.bat (Windows only)
v ODA/i2/start_i2ODA.sh (UNIX only)
Notes:
1. Except as otherwise noted, this document uses backslashes (\) as the
convention for directory paths. For UNIX installations, substitute slashes (/) for
backslashes.
2. All product path names are relative to the directory where the product is
installed on your system.
Other installation requirements
v i2 provides the MetadataService adapter to obtain the metadata information
from the registry. You need to install this adapter on an instance of the i2
application. Be sure to start the adapter prior to using the MetadataService.
v The bindings file for the port MetadataService, for example, TDMMetadata.xml,
which contains the port, operation, and type information, needs to be in the i2
configuration directory.
v The Visibroker Object Activation Daemon needs to run on the machine that is
running the agent and the one on which Business Object Designer is installed.
Launching i2 ODA
Before you begin: Ensure that the i2 ODA and XML schema ODA are installed on
your system.
You can launch i2 ODA in either of the following ways:
v Automatically—If you registered i2 ODA with the Visibroker Object Activation
Daemon (OAD), you do not need to start i2 ODA manually. OAD maintains a
list of registered ODA names and listens for requests to start the ODA. When
you select the ODA’s name in Business Object Designer, OAD starts the ODA.
For information on registering i2 ODA, see IBM WebSphere System Installation
Guide for UNIX or for Windows.
v Manually—If you have not registered i2 ODA with the Visibroker Object
Activation Daemon, start it by running the appropriate file:
UNIX: start_i2ODA.sh
Windows: start_i2ODA.bat
You have to add the proper path to the start files for CIS-SDK and j2ee.jar
Example: The following path information needs to be added to start_i2.bat file:
set I2_CIS_HOME_DIR=C:\i2\CIS\6.0\cis-sdk
set J2EE_PATH=C:\J2EE_JAR
Note: These are just examples. You should change the path information
depending on your local installation.
You configure and run i2 ODA using Business Object Designer. Business Object
Designer locates each ODA by the name specified in the AGENTNAME variable of
each script or batch file. The default ODA name for this connector is i2ODA.
During installation, if you register the ODA with the Visibroker Object Activation
Daemon, the wizard automatically prefixes the host name to the AGENTNAME
value to make it unique.
18 Adapter for i2 User Guide
Loading...