Related Manuals for IBM WebSphere Business Integration Adapter
Summary of Contents for IBM WebSphere Business Integration Adapter
- Page 1 IBM WebSphere Business Integration Adapters Adapter for i2 User Guide Adapter V ersion 1.0.x...
- Page 3 IBM WebSphere Business Integration Adapters Adapter for i2 User Guide Adapter V ersion 1.0.x...
- Page 4 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.
- Page 5 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...
- Page 6 Adapter for i2 User Guide...
-
Page 7: Table Of Contents
Appendix C. Connector feature list Event notification features © Copyright IBM Corp. 2002, 2003 ..... . . 73 . vii . - Page 8 Service call request handling features . General features . Appendix D. Notices ......77 Programming interface information .
-
Page 9: About This Document
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. - Page 10 < > /, \ %text% and $text viii Adapter for i2 User Guide 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.
-
Page 11: Chapter 1. Overview Of The Connector
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. - Page 12 A program that handles the execution of the business object processing logic. Supported brokers are ICS and WMQI. IBM’s data handler (DH) used to transform XML messages to the IBM business objects and vice versa. You need to configure the XML DH for use with the i2 connector.
-
Page 13: How The Connector Works
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. - Page 14 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.
- Page 15 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.
- Page 16 Adapter for i2 User Guide...
-
Page 17: Chapter 2. Installing And Configuring The Connector
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”... -
Page 18: Configuring The Connector
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. - Page 19 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.
-
Page 20: 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) -
Page 21: Chapter 3. Understanding Business Objects For The Connector
“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. -
Page 22: 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. - Page 23 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.
-
Page 24: Specifying Business Object Attribute Properties
If the child is a container attribute, this is set to Containment. Not used Not used. For relationship details between XML elements and requiredness, see Chapter 3, ″XML data handler,″ in IBM WebSphere Business Integration Adapters Data Handler Guide. -
Page 25: Identifying Business Object Application-Specific Information
For information on this property, see “Identifying business object application-specific information” on page 15, For relationship details between XML elements and cardinality, see Chapter 3, ″XML data handler,″ in IBM WebSphere Business Integration Adapters Data Handler Guide. Description The name of the i2 port type for the operation. - Page 26 Adapter for i2 User Guide...
-
Page 27: Chapter 4. Generating Business Objects Using I2 Oda
“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), or IBM WebSphere Business Integration System Installation Guide for UNIX or for Windows. - Page 28 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.
-
Page 29: Using I2 Oda In Business Object Designer
Using i2 ODA in Business Object Designer This section describes how to use i2 ODA in Business Object Designer to generate business objects. For information on launching Business Object Designer, see IBM WebSphere Business Integration Adapters Business Object Development Guide. - Page 30 You can save these properties in a named profile so that you do not need to re-enter them each time you use i2 ODA. For information on specifying an ODA profile, see IBM WebSphere Business Integration Adapters Business Object Development Guide.
- Page 31 Property name number DefaultBOPrefix SchemaFileLocation MessageFile CISAgentHostName You can also configure several optional parameters for the agent when it starts up. v TraceFileName--File into which i2 ODA writes trace information. The command line option for this parameter is -t. i2ODA names the file according to the naming convention.
- Page 32 Metadata (Top tree node) (Expanding Metadata lists all the port types) v Select the port, operation, and type for generating the business object. Each operation has an input and output type on a port, and each of these types needs to have a corresponding business object.
- Page 33 v Port information v Instance ID v Dummy key (as the business object creation will fail without a key) v Two single cardinality attributes representing the input and output types for the operation. The attributes are named as BOPrefix_in_operation_type and BOPrefix_out_operation_type.
- Page 34 The following diagram shows the business object that the XML schema ODA generates for i2_order.xsd. The XML data handler uses the combination of the element next to CISDocument and BOPrefix to get the business object name. I2BO_order Save the business object files Now that all the required business objects are generated, you need to save them to the InterChange server for use by the collaborations.
-
Page 35: Create The Metaobject For Polling
Create the metaobject for polling Once the business objects are created, you need to create the metaobjects for polling using the CSM. These objects shall have the i2MO prefix followed by the operation. The attributes need to have a default value. This information is used during polling to register the specific operation and check the output from i2 applications for the registered operation. - Page 36 Adapter for i2 User Guide...
-
Page 37: Chapter 5. Troubleshooting And Error Handling
ID. nnnnn Not able to get a connection for this instance {1}. [EXPL] Please ensure that the instance specified is up. {1}--Parameter to the error message, in this case the instance id. © Copyright IBM Corp. 2002, 2003... - Page 38 Polling-related error messages The following table describes polling-related error messages. These are logged in the i2 Adapter log file. Notes: 1. In some cases, the connector logs a fatal error (log message type of XRD_FATAL) so that e-mail notification can be triggered. For logging this error with the integration broker, you need to set the connector property LogAtInterchangeEnd to true.
- Page 39 Error description Fail to convert XML message to IBM business object Any error when posting event to the broker Event not subscribed to Service call request processing error messages The following table describes service call request processing error messages. These are logged in the i2 Adapter log file.
-
Page 40: Tracing Messages
The following table describes the types of tracing messages that the i2 connector outputs at each trace level. All the trace messages appear in the file specified by the connector property TraceFileName. These messages are in addition to any tracing messages output by the IBM WebSphere Business Integration Adapter architecture. Tracing Level... -
Page 41: Tips For Troubleshooting
Tracing Level Level 5 Tips for troubleshooting Use the following tips for troubleshooting problems: v If the CIS agent is running remotely, try to ping the remote machine and also ping this machine from the remote machine. v Check the CIS agent service. v Check that the adapters are running. - Page 42 Adapter for i2 User Guide...
-
Page 43: Appendix A. Standard Configuration Properties For Connectors
2.2 release of the adapters. v New properties CharacterEncoding Local JVMMinHeapSize JVMMaxHeapSize JVMMaxStackSize WireFormat MaxEventCapacity DuplicateEventElimination jms.NumConcurrentRequests ContainerManagedEvents jms.Messagebrokername (replaces jms.BrokerName) v Deleted properties RequestTransport PingFrequency TraceLevel AgentProxyType MaxThreadPoolSize Anonymous Connections GW Name Agent URL © Copyright IBM Corp. 2002, 2003... -
Page 44: Configuring Standard Connector Properties For Websphere Interchange Server
For general information about how connectors work with InterChange Server, see the Technical Introduction to IBM WebSphere InterChange Server. Important: Not all properties are applicable to all connectors that use InterChange You configure connector properties from Connector Configurator, which you access from System Manager. - Page 45 JvmMaxHeapSize heap size in megabytes JvmMaxNativeHeapSize size of stack in kilobytes JvmMinHeapSize heap size in megabytes jms.MessageBrokerName If FactoryClassName is IBM, use crossworlds.queue.manager. If FactoryClassName is Sonic, use localhost:2506. jms.FactoryClassName CxCommon.Messaging. jms.IBMMQSeriesFactory CxCommon.Messaging. jms.SonicMQFactory or any Java class name Default...
- Page 46 Property Name Possible values jms.NumConcurrentRequests positive integer jms.Password Any valid password jms.UserName Any valid name Locale en_US , ja_JP, ko_KR, zh_C, zh_T, fr_F, de_D, it_I, es_E, pt_BR Note: These are only a subset of supported locales. LogAtInterchangeEnd true or false MaxEventCapacity 1-2147483647 MessageFileName...
- Page 47 When there is a large request/response workload for a particular connection, the IBM WebSphere administrator can increase this value to enhance performance. Recommended values are in the range of 2 to 4. Increasing the value of this property increases the scalability of the Visigenic software, which establishes the IIOP connections.
- Page 48 ApplicationName Name that uniquely identifies the connector’s application. This name is used by the system administrator to monitor the WebSphere business integration system environment. This property must have a value before you can run the connector. BrokerType Identifies the integration broker type that you are using. If you are using an ICS connector, this setting must be ICS.
- Page 49 multi-threaded, or be capable of using Connector Agent Parallelism and be configured for multiple processes (setting the Parallel Process Degree configuration property greater than 1). Important: To determine whether a specific connector is single- or multi-threaded, see the installing and configuring chapter of its adapter guide. The ConcurrentEventTriggeredFlows property has no effect on connector polling, which is single-threaded and performed serially.
- Page 50 DeliveryQueue The queue that is used by the connector to send business objects to the integration broker. The default value is DELIVERYQUEUE. DeliveryTransport Specifies the transport mechanism for the delivery of events. Possible values are MQ for WebSphere MQ, IDL for CORBA IIOP, or JMS for Java Messaging Service. If ICS is the broker type, the value of the DeliveryTransport property can be MQ, IDL, or JMS, and the default is IDL.
- Page 51 (on the server side) and the connector (on the client side) due to memory use within the WebSphere MQ client. If your installation uses less than 768M of process heap size, IBM recommends that you set: v The LDR_CNTRL environment variable in the CWSharedEnv.sh script.
- Page 52 JvmMinHeapSize The minimum heap size for the agent (in megabytes). This property is applicable only if the RepositoryDirectory value is <REMOTE>. The default value is 1m. jms.FactoryClassName Specifies the class name to instantiate for a JMS provider. You must set this connector property when you choose JMS as your delivery transport mechanism (DeliveryTransport).
- Page 53 codeset The default is en_US. Important: By default only a subset of supported locales display in the drop list. To add other supported values to the drop list, you must manually modify the \Data\Std\stdConnProps.xml file in the product directory. For more information, see the appendix on Connector Configurator. Attention: If the connector has not been internationalized, the only valid value for this property is en_US.
- Page 54 The default value is false. OADMaxNumRetry Specifies the maximum number of times that the OAD automatically attempts to restart the application-specific component after an abnormal shutdown. The default value is 1000. OADRetryTimeInterval Specifies the number of minutes of the retry time interval that the OAD automatically attempts to restart the application-specific component after an abnormal shutdown.
- Page 55 RepositoryDirectory The location of the repository from which the connector reads the XML schema documents that store the meta-data of business object definitions. When the integration broker is ICS, this value must be set to <REMOTE> because the connector uses the InterChange Server repository to obtain its connector-definition information ResponseQueue Designates the JMS response queue, which delivers a response message from the...
-
Page 56: Configuring Standard Connector Properties For Websphere Mq Integrator
SynchronousRequestTimeout Specifies the time in minutes that the connector waits for a response to a synchronous request. If the response is not received within the specified time then the connector moves the original synchronous request message into the fault queue along with an error message. - Page 57 WebSphere MQ queue name DeliveryTransport DuplicateEventElimination true, false FaultQueue valid WebSphere MQ queue name jms.FactoryClassName jms.MessageBrokerName If FactoryClassName is IBM, use crossworlds.queue.manager. If FactoryClassName is Sonic, use localhost:2506. jms.NumConcurrentRequests jms.Password jms.UserName Locale en_US , ja_JP, ko_KR, zh_C, zh_T, fr_F, de_D,...
- Page 58 IBM WebSphere-delivered connector, the property is also likely to be set to the name of the connector. Set the...
- Page 59 manually modify the \Data\Std\stdConnProps.xml file in the product directory. For more information, see the appendix on Connector Configurator. Attention: Do not run a non-internationalized connector against InterChange Server version 4.1.1 if you cannot guarantee that only ISO Latin-1 data will be processed.
- Page 60 The default value is CONNECTORNAME/FAULTQUEUE. jms.FactoryClassName Specifies the class name to instantiate for a JMS provider. The default is CxCommon.Messaging.jms.IBMMQSeriesFactory. jms.MessageBrokerName Specifies the broker name to use for the JMS provider. The default is crossworlds.queue.manager. jms.NumConcurrentRequests Specifies the maximum number of concurrent service call requests that can be sent to a connector at the same time.
- Page 61 Attention: v WebSphere MQ Integrator supports only one locale at a time. Ensure that every component of the installation (for example, all adapters, applications, and the integration broker itself) is set to the same locale. v If the connector has not been internationalized, the only valid value for this property is en_US.
- Page 62 example, C:\WebSphereAdapters\repository. The value must be a directory path. Do not use <REMOTE> as the RepositoryDirectory value for a connector that is not using ICS as the broker. RequestQueue The queue that is used by the integration broker to send business objects to the connector.
- Page 63 WireFormat The data format for messages exchanged by the connector. The default value CwXML is the only valid value, and directs the connector to compose the messages in XML. Appendix A. Standard configuration properties for connectors...
- Page 64 Adapter for i2 User Guide...
-
Page 65: Appendix B. Connector Configurator
The drop list for the CharacterEncoding and Locale standard configuration properties displays only a subset of supported values. To add other values to the drop list, you must manually modify the \Data\Std\stdConnProps.xml file in the product directory. © Copyright IBM Corp. 2002, 2003... -
Page 66: Starting Connector Configurator
Connector folder (to edit an existing configuration), or v From the System Manager menu, choose Tools>Connector Configurator, or v With System Manager already running, from Start>Programs choose IBM WebSphere InterChange Server>IBM WebSphere Business Integration Toolset>Development>Connector Configurator. -
Page 67: Choosing Your Broker
Running Configurator independently of System Manager When you run Connector Configurator without connecting to System Manager, you can save a connector configuration file (an XML document with the extension *.cfg) to a directory that you specify, but you cannot save or open a System Manager project. -
Page 68: Using A Connector-Specific Property Template
After you have completed the configuration file and set its properties, it will need to be deployed to the appropriate location for your connector. v If you are using ICS as your broker, save the configuration in a System Manager project, and use System Manager to load the file into InterChange Server. - Page 69 Specifying general characteristics The Properties - Connector-Specific Property Template dialog appears. The dialog has tabs for General characteristics of the defined properties and for Value restrictions. The General display has the following fields: v Edit properties Use the buttons provided (or right-click within the Edit properties display) to add a new property to the template, to edit or delete an existing property, or to add a child property to an existing property.
- Page 70 Setting dependencies After you have finished making changes in both the General and the Value tabs, choose Next. The Dependencies dialog appears. A dependent property is a property that is included in the template and used in the configuration file only if the value of another property meets a specific condition.
-
Page 71: Using Connector Configurator With Ics As The Broker
display. When you select a name in the Template Name display, the Property Template Preview display shows the connector-specific properties that have been defined in that template. After you have chosen the template you want to use, choose OK. 3. A configuration screen will display for the connector that you are configuring. The title bar of the configuration screen shows the broker that you are using and the name that you have given to the connector. - Page 72 appropriate type for your broker--either ICS or WebSphere MQ Integrator Broker (for WMQI). If it does not, change the broker value before you configure the connector. To do so: 1. Under the Standard Properties tab, select the value field for the BrokerType property.
-
Page 73: Setting The Configuration File Properties (Ics)
v All files (*.*) Choose this option if a *.txt file was delivered in the adapter package for the connector, or if a definition file is available under another extension. 3. In the directory display, navigate to the appropriate connector definition file, select it, and choose Open. - Page 74 default values and some do not; you can modify some of the default values. The installation and configuration chapter of each adapter guide describes the application-specific properties and the recommended values. The fields for Standard Properties and Connector-Specific Properties are color-coded to show which are configurable: v A field with a grey background indicates a standard property.
- Page 75 Encryption for connector properties (ICS) Application-specific properties can be encrypted by clicking the Encrypt check box in the Edit Property window. To decrypt a value, click to clear the Encrypt check box, enter the correct value in the Verification dialog box, and choose OK. If the entered value is correct, the value is decrypted and displays.
- Page 76 4. In the File menu of the Connector Configurator window, choose Save to Project. The revised connector definition, including designated support for the added business object definition, is saved to the project in System Manager. To delete a business object from the supported list: 1.
- Page 77 If you are using maps that are uniquely defined for specific source and destination business objects, the maps will already be associated with their appropriate business objects when you open the display, and you will not need (or be able) to change them.
-
Page 78: Setting The Configuration File Properties (Websphere Mq Integrator Broker)
To change the logging and tracing values: 1. Choose the Trace/Log Files tab. 2. For either logging or tracing, you can choose to write messages to one or both of the following: v To console (STDOUT): Writes logging or tracing messages to the STDOUT display. - Page 79 Important: Connector Configurator accepts property values in either English or non-English character sets. However, the names of both standard and connector-specific properties, and the names of supported business objects, must use the English character set only. Standard properties differ from connector-specific properties as follows: v Standard properties of a connector are shared by both the application-specific component of a connector and its broker component.
- Page 80 2. Enter a name or value. 3. To encrypt a property, click the Encrypt box. 4. Choose to save or discard changes, as described for Setting Standard Connector Properties. The Update Method displayed for each property indicates whether a component or agent restart is necessary to activatechanged values.
-
Page 81: Using Standard And Connector-Specific Properties With Connector Configurator
4. When you add business objects to the configuration, you must load their message set files. If you attempt to load a message set that contains a business object name that already exists in the configuration, or if you attempt to load a message set file that contains a duplicate business object name, Connector Configurator detects the duplicate and displays the Load Results dialog. -
Page 82: Completing The Configuration
For connector-specific properties, however, you will need to both define the properties and set their values. Connector Configurator provides the interface for performing both of these tasks. Completing the configuration After you have created a configuration file for a connector and modified it, make sure that the connector can locate the configuration file when the connector starts up. -
Page 83: Appendix C. Connector Feature List
Appendix C. Connector feature list This appendix details the features supported by the i2 connector. For descriptions of these features, see “Appendix A: Connector feature checklist” in IBM WebSphere Business Integration Adapters Connector Development Guide. Event notification features The following table details the event notification features supported by the connector. -
Page 84: General Features
Category Feature Logical delete Exist Exist verb Misc Attribute names Business object names Retrieve Ignore missing child object N/A RetrieveByContent Ignore missing child object N/A Multiple results RetrieveByContent verb Update After-image support Delta support KeepRelations Verbs Retrieve verb Subverb support Verb stability General features The following table details the general features supported by the connector. - Page 85 Category Feature Connector properties ApplicationPassword ApplicationUserName UseDefaults Message tracing General messaging generateMsg() Trace level 0 Trace level 1 Trace level 2 Trace level 3 Trace level 4 Trace level 5 Misc. CDK method LogMsg Java Package Names Logging messages NT service compliance Transaction support Special value CxBlank processing...
- Page 86 Adapter for i2 User Guide...
-
Page 87: Appendix D. Notices
Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. -
Page 88: Programming Interface Information
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. - Page 89 United States, other countries, or both. Other company, product or service names may be trademarks or service marks of others. IBM WebSphere InterChange Server V4.2, IBM WebSphere Business Integration Toolset V4.2, IBM WebSphere Business Integration AdaptersV4.2, IBM WebSphere Business Integration Collaborations V4.2...
- Page 90 Adapter for i2 User Guide...
- Page 92 Printed in U.S.A.