14094079 Message Broker Message Flows

WebSphere Message Broker

Message FlowsVersion 6 Release 1

NoteBefore you use this information and the product that it supports, read the information in the Notices appendix.

This edition applies to version 6, release 1, modification 0, fix pack 3 of IBM WebSphere Message Broker and to allsubsequent releases and modifications until otherwise indicated in new editions.

Copyright International Business Machines Corporation 2000, 2008.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

ContentsAbout this topic collection. . . . . . . v

Part 1. Developing message flows . . 1

Developing message flows . . . . . . 3Message flows overview . . . . . . . . . . 4Getting started with Quick Start wizards . . . . 152Designing a message flow . . . . . . . . . 161Managing message flows . . . . . . . . . 238Defining message flow content . . . . . . . 251Developing message flow applications usingWebSphere Adapters . . . . . . . . . . . 269Developing ESQL . . . . . . . . . . . . 282Developing PHP . . . . . . . . . . . . 438Using XPath. . . . . . . . . . . . . . 458Using TCP/IP in message flows . . . . . . . 470Developing Java . . . . . . . . . . . . 497Developing message mappings . . . . . . . 520Defining a promoted property . . . . . . . . 611Collecting message flow accounting and statisticsdata . . . . . . . . . . . . . . . . 619Developing a user exit . . . . . . . . . . 625Configuring aggregation flows . . . . . . . 628Creating message collections . . . . . . . . 646Configuring timeout flows . . . . . . . . . 656Configuring flows to handle WebSphere MQmessage groups . . . . . . . . . . . . 663

Part 2. Working with Web services 667

Working with Web services . . . . . 669WebSphere Message Broker and Web services . . 669What is SOAP? . . . . . . . . . . . . . 671What is WSDL? . . . . . . . . . . . . 683What is SOAP MTOM? . . . . . . . . . . 687WS-Addressing. . . . . . . . . . . . . 688WS-Security . . . . . . . . . . . . . . 699WebSphere Service Registry and Repository . . . 720External standards. . . . . . . . . . . . 736Message flows for Web services . . . . . . . 744

Part 3. Working with files . . . . . 771

Working with files . . . . . . . . . 773How the broker processes files . . . . . . . 773How the file nodes and additional instances shareaccess to files . . . . . . . . . . . . . 776Using LocalEnvironment variables with file nodes 777File name patterns. . . . . . . . . . . . 780mqsiarchive subdirectory . . . . . . . . . 782Reading a file . . . . . . . . . . . . . 783Writing a file . . . . . . . . . . . . . 791

Part 4. Reference . . . . . . . . . 799

Message flows . . . . . . . . . . . 803Message flow preferences . . . . . . . . . 803Description properties for a message flow . . . . 803Built-in nodes . . . . . . . . . . . . . 806User-defined nodes . . . . . . . . . . . 1235WebSphere Adapters properties . . . . . . . 1235Supported code pages . . . . . . . . . . 1353WebSphere MQ connections . . . . . . . . 1381Listing database connections that the broker holds 1382Quiescing a database . . . . . . . . . . 1382Support for Unicode and DBCS data in databases 1382Data integrity within message flows . . . . . 1385Validation properties . . . . . . . . . . 1385Parsing on demand . . . . . . . . . . . 1389Exception list structure . . . . . . . . . . 1390Configurable message flow properties . . . . . 1398Message flow porting considerations . . . . . 1400Monitoring profile . . . . . . . . . . . 1401The monitoring event . . . . . . . . . . 1406Message flow accounting and statistics data . . . 1408Coordinated message flows . . . . . . . . 1424Element definitions for message parsers . . . . 1425Message mappings . . . . . . . . . . . 1435XML constructs . . . . . . . . . . . . 1462Data sources on z/OS . . . . . . . . . . 1477

ESQL reference . . . . . . . . . . 1479Syntax diagrams: available types . . . . . . 1480ESQL data types in message flows . . . . . . 1480ESQL variables . . . . . . . . . . . . 1493ESQL field reference overview . . . . . . . 1493ESQL operators . . . . . . . . . . . . 1500ESQL statements . . . . . . . . . . . . 1507ESQL functions: reference material, organized byfunction type . . . . . . . . . . . . . 1592ESQL constants . . . . . . . . . . . . 1692Broker properties that are accessible from ESQLand Java . . . . . . . . . . . . . . 1693Special characters, case sensitivity, and commentsin ESQL . . . . . . . . . . . . . . . 1696ESQL reserved keywords . . . . . . . . . 1698ESQL non-reserved keywords . . . . . . . 1698Example message . . . . . . . . . . . 1701

Message mappings . . . . . . . . 1703Message Mapping editor . . . . . . . . . 1703Mapping node . . . . . . . . . . . . 1714Migrating message mappings from Version 5.0 1725Restrictions on migrating message mappings . . 1726

Part 5. Appendixes . . . . . . . 1731

Copyright IBM Corp. 2000, 2008 iii

||

||

Appendix. Notices for WebSphereMessage Broker. . . . . . . . . . 1733Trademarks in the WebSphere Message Brokerinformation center . . . . . . . . . . . 1735

Index . . . . . . . . . . . . . . 1737

iv Message Flows

About this topic collectionThis PDF has been created from the WebSphere Message Broker Version 6.1(November 2008) information center topics. Always refer to the WebSphereMessage Broker online information center to access the most current information.The information center is periodically updated on the document update site andthis PDF and others that you can download from that Web site might not containthe most current information.

The topic content included in the PDF does not include the Related Linkssections provided in the online topics. Links within the topic content itself areincluded, but are active only if they link to another topic in the same PDFcollection. Links to topics outside this topic collection are also shown, but theseattempt to link to a PDF that is called after the topic identifier (for example,ac12340_.pdf) and therefore fail. Use the online information to navigate freelybetween topics.

Feedback: do not provide feedback on this PDF. Refer to the online information toensure that you have access to the most current information, and use the Feedbacklink that appears at the end of each topic to report any errors or suggestions forimprovement. Using the Feedback link provides precise information about thelocation of your comment.

The content of these topics is created for viewing online; you might find that theformatting and presentation of some figures, tables, examples, and so on are notoptimized for the printed page. Text highlighting might also have a differentappearance.

Copyright IBM Corp. 2000, 2008 v

vi Message Flows

Part 1. Developing message flowsDeveloping message flows . . . . . . . . . 3Message flows overview . . . . . . . . . . 4

Message flow projects . . . . . . . . . . 5Message flow nodes . . . . . . . . . . . 5Configurable services . . . . . . . . . . 58Message flow version and keywords . . . . . 59Message flow connections . . . . . . . . 60Threading . . . . . . . . . . . . . . 61Execution model. . . . . . . . . . . . 61The message tree . . . . . . . . . . . 61Parsers . . . . . . . . . . . . . . . 82Properties . . . . . . . . . . . . . 118Message flow transactions . . . . . . . . 122Broker schemas. . . . . . . . . . . . 123Monitoring message flows . . . . . . . . 125Message flow accounting and statistics data . . 141Message flow aggregation . . . . . . . . 146Message collections . . . . . . . . . . 148Converting data with message flows . . . . 150User exits . . . . . . . . . . . . . 151

Getting started with Quick Start wizards . . . . 152Quick Start wizards overview . . . . . . . 153Creating an application from scratch . . . . 153Creating an application based on WSDL or XSDfiles . . . . . . . . . . . . . . . 154Creating an application based on an existingmessage set . . . . . . . . . . . . . 156Creating an application using WebSphereAdapters . . . . . . . . . . . . . . 157Creating an application using the ConfigureNew Web Service Usage wizard . . . . . . 157

Designing a message flow . . . . . . . . . 161Deciding which nodes to use . . . . . . . 163Using more than one input node . . . . . . 174Defining input message characteristics . . . . 175Using nodes for decision making . . . . . . 176Using subflows. . . . . . . . . . . . 179Optimizing message flow response times . . . 180System considerations for message flowdevelopment . . . . . . . . . . . . 182Creating destination lists . . . . . . . . 184Using WebSphere MQ cluster queues for inputand output . . . . . . . . . . . . . 185Using WebSphere MQ shared queues for inputand output (z/OS) . . . . . . . . . . 186Validating messages . . . . . . . . . . 187Viewing the logical message tree in trace output 189Accessing databases from message flows . . . 192Accessing databases from ESQL . . . . . . 195Configuring globally coordinated message flows 196Configuring JMSInput and JMSOutput nodes tosupport global transactions . . . . . . . . 199Configuring the broker to enable a JMSproviders proprietary API . . . . . . . . 205Changing connection details for IMS nodes . . 206Configuring message flows for data conversion 207

Using MQGet nodes . . . . . . . . . . 209Exploiting user exits . . . . . . . . . . 222Ensuring that messages are not lost . . . . . 224Providing user-defined properties to controlbehavior . . . . . . . . . . . . . . 227Handling errors in message flows . . . . . 227

Managing message flows . . . . . . . . . 238Creating a message flow project . . . . . . 239Deleting a message flow project . . . . . . 240Creating a broker schema . . . . . . . . 241Creating a message flow. . . . . . . . . 242Opening an existing message flow . . . . . 243Copying a message flow using copy. . . . . 244Renaming a message flow . . . . . . . . 245Moving a message flow . . . . . . . . . 246Deleting a message flow. . . . . . . . . 247Deleting a broker schema . . . . . . . . 248Version and keyword information fordeployable objects . . . . . . . . . . . 248Saving a message flow . . . . . . . . . 249

Defining message flow content . . . . . . . 251Using the node palette . . . . . . . . . 252Adding a message flow node . . . . . . . 255Adding a subflow . . . . . . . . . . . 258Renaming a message flow node . . . . . . 258Configuring a message flow node . . . . . 259Using dynamic terminals . . . . . . . . 261Removing a message flow node . . . . . . 262Connecting message flow nodes . . . . . . 263Removing a node connection . . . . . . . 266Adding a bend point . . . . . . . . . . 266Removing a bend point . . . . . . . . . 267Aligning and arranging nodes . . . . . . . 268

Developing message flow applications usingWebSphere Adapters . . . . . . . . . . . 269

Preparing your system to use WebSphereAdapters nodes . . . . . . . . . . . 269Activating IBM Tivoli License Manager forWebSphere Adapters . . . . . . . . . . 270Adding external software dependencies for SAP 271Configuring the SAP server to work with theadapter . . . . . . . . . . . . . . 272Adding external software dependencies forSiebel . . . . . . . . . . . . . . . 274Configuring the Siebel application to work withthe adapter . . . . . . . . . . . . . 275Adding external software dependencies forPeopleSoft . . . . . . . . . . . . . 277Creating a custom event project in PeopleTools 278Connecting to an EIS using the AdapterConnection wizard . . . . . . . . . . 280Changing connection details for SAP adapters 281

Developing ESQL . . . . . . . . . . . . 282ESQL overview. . . . . . . . . . . . 283Managing ESQL files . . . . . . . . . . 293Writing ESQL . . . . . . . . . . . . 305

Copyright IBM Corp. 2000, 2008 1

||

||

||

Developing PHP . . . . . . . . . . . . 438PHP overview . . . . . . . . . . . . 439Creating PHP code for a PHPCompute node 439Using PHP arrays . . . . . . . . . . . 445Deploying code in a PHPCompute node . . . 448Accessing elements in the message tree from aPHPCompute node . . . . . . . . . . 448Creating and transforming messages using aPHPCompute node . . . . . . . . . . 450XML support . . . . . . . . . . . . 454Routing a message using a PHPCompute node 454Accessing other parts of the message tree usingthe PHPCompute node . . . . . . . . . 455Calling Java from PHP . . . . . . . . . 458

Using XPath. . . . . . . . . . . . . . 458XPath overview . . . . . . . . . . . 459Node properties that accept either ESQL orXPath expressions . . . . . . . . . . . 461Namespace support . . . . . . . . . . 463XPath Expression Builder . . . . . . . . 465Creating XPath expressions . . . . . . . . 467Selecting the grammar mode . . . . . . . 468

Using TCP/IP in message flows . . . . . . . 470TCP/IP overview . . . . . . . . . . . 470TCP/IP nodes . . . . . . . . . . . . 473Connection management . . . . . . . . 476Scenarios for WebSphere Message Broker andTCP/IP . . . . . . . . . . . . . . 478Working with TCP/IP . . . . . . . . . 482

Developing Java . . . . . . . . . . . . 497Managing Java Files . . . . . . . . . . 497Writing Java . . . . . . . . . . . . . 502

Developing message mappings . . . . . . . 520Message mappings overview . . . . . . . 521Creating message mappings . . . . . . . 524Message mapping scenarios . . . . . . . 572

Defining a promoted property . . . . . . . . 611Promoting a property . . . . . . . . . 612Renaming a promoted property . . . . . . 615Removing a promoted property . . . . . . 616Converging multiple properties . . . . . . 617

Collecting message flow accounting and statisticsdata . . . . . . . . . . . . . . . . 619

Starting to collect message flow accounting andstatistics data . . . . . . . . . . . . 620Stopping message flow accounting and statisticsdata collection . . . . . . . . . . . . 623Viewing message flow accounting and statisticsdata collection parameters . . . . . . . . 623Modifying message flow accounting andstatistics data collection parameters . . . . . 624Resetting message flow accounting and statisticsarchive data . . . . . . . . . . . . . 625

Developing a user exit . . . . . . . . . . 625Deploying a user exit. . . . . . . . . . 626

Configuring aggregation flows . . . . . . . 628Creating the aggregation fan-out flow . . . . 628Creating the aggregation fan-in flow . . . . 632Associating fan-out and fan-in aggregationflows . . . . . . . . . . . . . . . 637Setting timeouts for aggregation . . . . . . 639

Using multiple AggregateControl nodes . . . 640Correlating input request and output responseaggregation messages . . . . . . . . . 641Using control messages in aggregation flows 641Handling exceptions in aggregation flows . . . 644

Creating message collections . . . . . . . . 646Creating a flow that uses message collections 646Configuring the Collector node . . . . . . 648Using control messages with the Collector node 655

Configuring timeout flows . . . . . . . . . 656Sending timeout request messages . . . . . 656Sending a message after a timed interval . . . 658Sending a message multiple times after aspecified start time . . . . . . . . . . 659Automatically generating messages to drive aflow . . . . . . . . . . . . . . . 661Performance considerations for timeout flows 662

Configuring flows to handle WebSphere MQmessage groups . . . . . . . . . . . . 663

Receiving messages in a WebSphere MQmessage group . . . . . . . . . . . . 663Sending messages in a WebSphere MQ messagegroup . . . . . . . . . . . . . . . 665Sending message segments in a WebSphere MQmessage . . . . . . . . . . . . . . 665

2 Message Flows

|||||||||||||||||||||||||

Developing message flowsDesign, create and maintain message flows using the workbench.

A message flow is a sequence of processing steps that run in the broker when aninput message is received. The topics in this section describe how to create andmaintain message flows.

Concept topics:

v Message flows overview on page 4v Message flow projects on page 5v Message flow nodes on page 5v Message flow version and keywords on page 59v Message flow connections on page 60v Threading on page 61v Execution model on page 61v The message tree on page 61v Parsers on page 82v Properties on page 118v Message flow transactions on page 122v Broker schemas on page 123v Monitoring message flows on page 125v Message flow accounting and statistics data on page 141v Message flow aggregation on page 146v Message collections on page 148v Converting data with message flows on page 150v User exits on page 151

Task topics:

v Getting started with Quick Start wizards on page 152v Designing a message flow on page 161v Managing message flows on page 238v Defining message flow content on page 251v Developing message flow applications using WebSphere Adapters on page 269v Developing ESQL on page 282v Using XPath on page 458v Developing Java on page 497v Developing message mappings on page 520v Defining a promoted property on page 611v Configuring monitoring event sources using a monitoring profile on page 133v Collecting message flow accounting and statistics data on page 619v Developing a user exit on page 625v Configuring aggregation flows on page 628v Creating message collections on page 646

Copyright IBM Corp. 2000, 2008 3

v Configuring timeout flows on page 656v Configuring flows to handle WebSphere MQ message groups on page 663

See also a section of topics that contain reference information about message flows.

The workbench provides a set of toolbar icons that invoke wizards that you canuse to create any of the resources associated with message flows, for example,message flow projects and ESQL files. Hover your mouse pointer over each icon tosee its function.

The workbench lets you open resource files with other editors. Use only theworkbench message flow editor to work with message flow files, because thiseditor correctly validates all changes that you make to these files when you savethe message flow.

When you have completed developing your message flow, deploy it to a broker tostart its execution.

Tip: You can debug your message flow using the flow debugger.

For a basic introduction to developing message flows, see the IBM Redbookspublication WebSphere Message Broker Basics.

Message flows overviewA message flow is a sequence of processing steps that run in the broker when aninput message is received.

You define a message flow in the workbench by including a number of messageflow nodes, each of which represents a set of actions that define a processing step.The connections in the flow determine which processing steps are carried out, inwhich order, and under which conditions. A message flow must include an inputnode that provides the source of the messages that are processed. You must thendeploy the message flow to a broker for execution.

When you want to exchange messages between multiple applications, you mightfind that the applications do not understand or expect messages in exactly thesame format. You might need to provide some processing between the sending andreceiving applications that ensures that both can continue to work unchanged, butcan exchange messages successfully.

You define the processing that is required when you create and configure amessage flow. The way that you do this determines what actions are performed ona message when it is received, and the order in which the actions are completed.

You can create a message flow using the built-in nodes, nodes that you or a vendorhave created (user-defined nodes), or other message flows (known as subflows).When you want to invoke a message flow to process messages, you deploy it to abroker, where it is executed within an execution group.

The mode in which your broker is working, can affect the number of executiongroups and message flows that you can deploy, and the types of node that you canuse. See Restrictions that apply in each operation mode.

The following topics describe the concepts that you need to understand to design,create, and configure a message flow and its associated resources:

4 Message Flows

v Projectsv Nodesv Version and keywordsv Message flow connections on page 60v Execution model on page 61v Threading on page 61v Parsers on page 82v Logical tree structure on page 68v Properties on page 118v Monitoring message flows on page 125v Accounting and statistics datav Message flow transactions on page 122v Aggregationv Message collections on page 148v Converting data with message flows on page 150v Message flows, ESQL, and mappings on page 57v Broker schemas on page 123v Message mappings overview on page 521v ESQL overview on page 283

For a basic introduction to developing message flows, see the IBM Redbooks

publication WebSphere Message Broker Basics.

Message flow projectsA message flow project is a specialized container in which you create and maintainall the resources associated with one or more message flows.

You can create a message flow project to contain a single message flow and itsresources, or you can group together related message flows and resources in asingle message flow project to provide an organizational structure to your messageflow resources.

Message flow project resources are created as files, and are displayed within theproject in the Broker Development view. These resources define the content of themessage flow, and additional objects that contain detailed configurationinformation, in the form of ESQL modules and mappings, for one or more nodeswithin the message flow.

Import one of the following samples from the Samples Gallery to see how thesamples message flow resources are stored in a Message Flow project. If thesample has a message set, its message set resources are stored in a Message Setproject.v Video Rental samplev Comma Separated Value (CSV) sampleYou can view samples only when you use the information center that is integratedwith the Message Broker Toolkit.

Message flow nodesA message flow node is a processing step in a message flow.

A message flow node receives a message, performs a set of actions against themessage, and optionally passes the message on to the next node in the messageflow. A message flow node can be a built-in node, a user-defined node, or asubflow node.

Developing message flows 5

A message flow node has a fixed number of input and output points known asterminals. You can make connections between the terminals to define the routesthat a message can take through a message flow.

The mode that your broker is working in can affect the types of node that you canuse; see Restrictions that apply in each operation mode.

Built-in nodeA built-in node is a message flow node that is supplied by WebSphere

Message Broker. The built-in nodes provide input and output,manipulation and transformation, decision making, collating requests, anderror handling and reporting functions.

For information about all of the built-in nodes supplied by WebSphereMessage Broker, see Built-in nodes on page 806.

User-defined nodeA user-defined node is an extension to the broker that provides a newmessage flow node in addition to those supplied with the product. It mustbe written to the user-defined node API provided by WebSphere MessageBroker for both C and Java languages. The following sampledemonstrates how you can write your own nodes in both C and Javalanguages.v User-defined Extension sampleYou can view samples only when you use the information center that isintegrated with the Message Broker Toolkit.

SubflowA subflow is a directed graph that is composed of message flow nodes andconnectors and is designed to be embedded in a message flow or inanother subflow. A subflow must include at least one Input node or oneOutput node. A subflow can be executed by a broker only as part of themessage flow in which it is embedded, and therefore cannot beindependently deployed.

A message is received by an Input node and processed according to thedefinition of the subflow. That might include being stored through aWarehouse node, or delivered to another message target, for examplethrough an MQOutput node. If required, the message can be passedthrough an Output node back to the main flow for further processing.

The subflow, when it is embedded in a main flow, is represented by asubflow node, which has a unique icon. The icon is displayed with thecorrect number of terminals to represent the Input and Output nodes thatyou have included in the subflow definition.

The most common use of a subflow is to provide processing that isrequired in many places within a message flow, or is to be shared betweenseveral message flows. For example, you might code some error processingin a subflow, or create a subflow to provide an audit trail (storing theentire message and writing a trace entry).

The use of subflows is demonstrated in the following samples:v Error Handler samplev Coordinated Request Reply sampleThe Error Handler sample uses a subflow to trap information about errorsand store the information in a database. The Coordinated Request Replysample uses a subflow to encapsulate the storage of the ReplyToQ and

6 Message Flows

ReplyToQMgr values in a WebSphere MQ message so that the processinglogic can be reused in other message flows and to allow alternativeimplementations to be substituted. You can view samples only when youuse the information center that is integrated with the Message BrokerToolkit.

A node does not always produce an output message for every output terminal:often it produces one output for a single terminal based on the message receivedor the result of the operation of the node. For example, a Filter node typicallysends a message on either the true terminal or the false terminal, but not both.

If more than one terminal is connected, the node sends the output message oneach terminal, but sends on the next terminal only when the processing hascompleted for the current terminal. Updates to a message are never propagated topreviously-executed nodes, only to nodes following the node in which the updatehas been made. The order in which the message is propagated to the differentoutput terminals is determined by the broker; you cannot change this order. Theonly exception to this rule is the FlowOrder node, in which the terminals indicatethe order in which the message is propagated to each.

The message flow can accept a new message for processing only when all pathsthrough the message flow (that is, all connected nodes from all output terminals)have been completed.

The following sample uses Environment variables in the XML_Reservation sampleto store information that has been taken from a database table and to pass thatinformation to a node downstream in the message flow.v Airline Reservations sampleYou can view samples only when you use the information center that is integratedwith the Message Broker Toolkit.

WebSphere Adapters nodesA WebSphere Adapters node is a message flow node that is used to communicatewith Enterprise Information Systems (EIS).

SAP, Siebel, and PeopleSoft adapters are supported by the following nodes:v SAPInput nodev SAPRequest nodev SiebelInput nodev SiebelRequest nodev PeopleSoftInput nodev PeopleSoftRequest nodeThe TwineballInput and TwineballRequest nodes are sample nodes with their ownsample EIS. You can use the TwineBall nodes to see how adapters nodes work. Youcannot use the TwineBall nodes to connect to the external SAP, Siebel, andPeopleSoft EIS systems.

The mode in which your broker is working, can affect the number of executiongroups and message flows that you can deploy, and the types of node that you canuse. See Restrictions that apply in each operation mode.

The following terms are associated with WebSphere Adapters:

EIS Enterprise information systems. This term is used to describe theapplications that comprise an enterprises existing system for handling


company-wide information. An enterprise information system offers awell-defined set of services that are exposed as local or remote interfaces orboth. Enterprise Resource Planning (ERP) and Customer RelationshipManagement (CRM) are typical enterprise information systems.

EMD Enterprise Metadata Discovery. A specification that you can use to examinean EIS and get details of business object data structures and APIs. An EMDstores definitions as XML schemas by default, and builds components thatcan access the EIS. In WebSphere Message Broker you use the AdapterConnection wizard to examine an EIS.

Business objectA set of attributes that represent a business entity (such as Employee), anaction on the data (such as a create or update operation), and instructionsfor processing the data. Components of the business integration system usebusiness objects to exchange information and trigger actions.

The WebSphere Adapters support two modes of communication:v Inbound: An event is generated on the EIS and the adapter responds to theevent by sending a message to the message broker. The WebSphere Adaptersinput nodes support inbound communication. When the EIS sends an event tothe adapter, a message is propagated from the WebSphere Adapters input node.

v Outbound: The message broker uses the adapter to send a request to the EIS.The WebSphere Adapters request nodes support outbound communication.When a message is propagated to the WebSphere Adapters request node, theadapter sends a request to the EIS.

The WebSphere Adapters nodes need an adapter component to access the EIS. Theinput nodes need an inbound adapter component, which allows the EIS to invokethe message flow when an event occurs. The request nodes need an outboundadapter component, which is used by the message flow to invoke a service in theEIS.

The WebSphere Adapters nodes also need a message set to ensure that theWebSphere Message Broker messages that are propagated to and from the nodesreflect the logical structure of the data in the EIS.

For more information about support for adapters on different operating systems,see WebSphere Message Broker Requirements.

The following topics provide an overview of the WebSphere Adapters:v Overview of WebSphere Adapter for SAP Softwarev Overview of WebSphere Adapter for Siebel Business Applications on page 38v Overview of WebSphere Adapter for PeopleSoft Enterprise on page 45

Overview of WebSphere Adapter for SAP Software:

With WebSphere Adapter for SAP Software you can create integrated processesthat include the exchange of information with an SAP server, without specialcoding.

Using the adapter, an application component (the program or piece of code thatperforms a specific business function) can send requests to the SAP server (forexample, to query a customer record in an SAP table or to update an orderdocument) or receive events from the server (for example, to be notified that acustomer record has been updated). The adapter creates a standard interface to the

8 Message Flows

applications and data on the SAP server, so that the developer of the applicationcomponent does not have to understand the lower-level details (theimplementation of the application or the data structures) on the SAP server.

WebSphere Adapter for SAP Software complies with the Java ConnectorArchitecture (JCA) 1.5, which standardizes the way in which applicationcomponents, application servers, and Enterprise Information Systems (EIS), such asan SAP server, interact with each other.

The adapter, which you generate with the Adapter Connection wizard, uses astandard interface and standard data objects. The adapter takes the standard dataobject sent by the application component and calls the SAP function. The adapterthen returns a standard data object to the application component. The applicationcomponent does not have to deal directly with the SAP function; it is the SAPadapter that calls the function and returns the results.

For example, the application component that requested the list of customers sendsa standard business object with the range of customer IDs to the SAP adapter. Theapplication component receives, in return, the results (the list of customers) in theform of a standard business object. The adapter performs all the interactionsdirectly with the actual SAP function.

Similarly, the message flow might want to know about a change to the data on theSAP server (for example, a change to a particular customer). You can generate anadapter component that listens for such events on the SAP server and notifiesmessage flows with the update. In this case, the interaction begins at the SAPserver.

For more information, see Technical overview of Adapter for SAP Software.

Technical overview of Adapter for SAP Software:

WebSphere Adapter for SAP Software provides multiple ways to interact withapplications and data on SAP servers. Outbound processing (from an applicationto the adapter to the SAP server) and inbound processing (from the SAP server tothe adapter to an application) are supported.

WebSphere Adapter for SAP Software connects to SAP systems running on SAPWeb application servers. The adapter supports Advanced Event Processing (AEP)and Application Link Enabling (ALE) for inbound processing, and the BusinessApplication Programming Interface (BAPI), AEP, ALE, and Query Interface for SAPSystems (QISS) for outbound processing. You set up the adapter to performoutbound and inbound processing by using the Adapter Connection wizard togenerate business objects based on the services it discovers on the SAP server.

For outbound processing, the adapter client invokes the adapter operation tocreate, update, or delete data on the SAP server or to retrieve data from the SAPserver.

For inbound processing, an event that occurs on the SAP server is sent from theSAP server to the adapter. The ALE inbound and BAPI inbound interfaces startevent listeners that detect the events. Conversely, the Advanced event processinginterface polls the SAP server for events. The adapter then delivers the event to anendpoint, which is an application or other consumer of the event from the SAPserver.


You configure the adapter to perform outbound and inbound processing by usingthe Adapter Connection wizard to create a message set that includes the interfaceto the SAP application as well as business objects based on the functions or tablesthat it discovers on the SAP server.

Overview of the outbound processing interfaces

WebSphere Adapter for SAP Software provides multiple interfaces to the SAPserver for outbound processing.v Through its BAPI interfaces, the adapter issues remote function calls (RFCs) toRFC-enabled functions, such as a Business Application Programming Interface(BAPI) function. These remote function calls create, update, or retrieve data onan SAP server. The BAPI interface works with individual BAPIs (simple BAPIs). For

example, you might want to check to see whether specific customerinformation exists in an SAP database.

The BAPI work unit interface works with ordered sets of BAPIs. For example,you might want to update an employee record. To do so, you use threeBAPIs:1. To lock the record (to prevent any other changes to the record)2. To update the record3. To have the record approved

The BAPI result set interface uses two BAPIs to select multiple rows of datafrom an SAP database.

BAPI calls are useful when you need to perform data retrieval or manipulationand a BAPI or RFC function that performs the task already exists.Simple BAPIs can be sent through the synchronous RFC, asynchronoustransactional RFC, or asynchronous queued RFC protocol. With synchronous RFC, both the adapter and the SAP server must be

available when the call is made from the adapter to the SAP server. Theadapter sends a request to the SAP server and waits for a response.

With asynchronous transactional RFC, a transaction ID is associated with thecall from the adapter to the SAP server. The adapter does not wait for aresponse from the SAP server. Only the transaction ID is returned to themessage flow.

With asynchronous queued RFC, the call from the adapter is delivered to apredefined queue on the SAP server. As with asynchronous RFC, atransaction ID is associated with the call, and the adapter does not wait for aresponse from the SAP server.This interface is useful when the event sequence must be preserved.

v The Query interface for SAP Software retrieves data from specific SAPapplication tables. It can return the data or check for the existence of the data.You can use this type of interaction with SAP if you need to retrieve data froman SAP table without using an RFC function or a BAPI.

v With the Application Link Enabling (ALE) interface, you exchange data usingSAP Intermediate Data structures (IDocs). For outbound processing, you send anIDoc or a packet of IDocs to the SAP server.The ALE interface, which is particularly useful for batch processing of IDocs,provides asynchronous exchange. You can use the queued transactional (qRFC)protocol to send the IDocs to a queue on the SAP server. The qRFC protocolensures the order in which the IDocs are received. It is often used for systemreplications or system-to-system transfers.

10 Message Flows

v With the ALE pass-through IDoc interface, the adapter sends the IDoc to theSAP server with no conversion of the IDoc. The Message tree contains a BLOBfield that represents the IDoc.

v With the Advanced event processing interface, you send data to the SAP server.The data is then processed by an ABAP handler on the SAP server.

Overview of the inbound processing interfaces

WebSphere Adapter for SAP Software provides the following interfaces to the SAPserver for inbound processing.v Through its BAPI inbound interface, the adapter listens for events and receivesnotifications of RFC-enabled function calls from the SAP server. With synchronous RFC, both the adapter and the SAP server must be

available when the call is made from the SAP server to the adapter. Theadapter sends the request to a predefined application and returns theresponse to the SAP server.

With asynchronous transactional RFC, the event is delivered to the adaptereven if the adapter is not available when the call is made. The SAP serverstores the event on a list of functions to be invoked and continues to attemptto deliver it until the adapter is available.You also use asynchronous transaction RFC if you want to deliver thefunctions from a predefined queue on the SAP server. Delivering the filesfrom a queue ensures the order in which the functions are sent.If you select assured once-only delivery, the adapter uses a data source topersist the event data received from the SAP server. Event recovery isprovided to track and recover events in case a problem occurs when theadapter attempts to deliver the event to the endpoint.

v With the ALE inbound processing interface, the adapter listens for events andreceives one or more IDocs from the SAP server. As with ALE outboundprocessing, ALE inbound processing provides asynchronous exchange.You can use the qRFC interface to receive the IDocs from a queue on the SAPserver, which ensures the order in which the IDocs are received.If you select assured once-only delivery, the adapter uses a data source to persistthe event data, and event recovery is provided to track and recover events incase a problem occurs when the adapter attempts to deliver the event to theendpoint.

v With the ALE pass-through IDoc interface, the SAP server sends the IDocthrough the adapter to the endpoint with no conversion of the IDoc. TheMessage tree contains a BLOB field that represents the IDoc.

v The Advanced event processing interface polls the SAP server for events. Itdiscovers events waiting to be processed. It then processes the events and sendsthem to the endpoint. For more information, see The Advanced eventprocessing interface on page 31.

How the adapter interacts with the SAP server

The adapter uses the SAP Java Connector (SAP JCo) API to communicate with SAPapplications. An application sends a request to the adapter, which uses the SAPJCo API to convert the request into a BAPI function call. The SAP system processesthe request and sends the results to the adapter. The adapter sends the results in aresponse message to the calling application.

For more information, see the following topics.


v The Adapter Connection wizard (SAP)v The BAPI interfacesv The ALE interfaces on page 19v Query interface for SAP Software on page 29v The Advanced event processing interface on page 31

The Adapter Connection wizard (SAP):

The Adapter Connection wizard is a tool that you use to create services. TheAdapter Connection wizard establishes a connection to the SAP server, discoversservices (based on search criteria that you provide), and generates business objects,interfaces, and import or export files, based on the services that are discovered.

By using WebSphere Message Broker, you establish a connection to the SAP serverto browse the metadata repository on the SAP server. The SAP metadatarepository, which is a database of the SAP data, provides a consistent and reliablemeans of access to that data.

You specify connection information (such as the user name and password neededto access the server), and you specify the interface that you want to use (forexample, BAPI). The service metadata that is associated with that interface isdisplayed. You can then provide search criteria and select the information (forexample, you can list all BAPIs that relate to CUSTOMER by using the searchfilter with BAPI_CUSTOMER*, then select one or more BAPIs).

The result of running the Adapter Connection wizard is an adapter connectionproject and a message set project that contain the interfaces and business objects aswell as the adapter.

The Adapter Connection wizard also produces an import file (for outboundprocessing) or an export file (for inbound processing).v The import file contains the managed connection factory property settings thatyou provide in the wizard.

v The export file contains the activation specification property settings youprovide in the wizard.

The BAPI interfaces:

The WebSphere Adapter for SAP Software supports outbound processing forsimple BAPIs, BAPI units of work, and BAPI result sets. In outbound processing,message flows call BAPIs and other RFC-enabled functions on the SAP server. Theadapter supports inbound processing for simple BAPIs only. In inboundprocessing, the SAP server sends an RFC-enabled function (such as a BAPIfunction) through the adapter to an endpoint.

For example, you want to build a service that creates a new customer on the SAPserver. You run the Adapter Connection wizard to discover theBAPI_CUSTOMER_CREATEFROMDATA function, and the wizard generates thebusiness-object definition for BAPI_CUSTOMER_CREATEFROMDATA, as well asother Service Component Architecture (SCA) service resources. During BAPIoutbound processing, the adapter receives the service request and converts thedata into a BAPI invocation.

12 Message Flows

||||

BAPI interface (simple BAPIs)

A simple BAPI performs a single operation, such as retrieving a list of customers.The adapter supports simple BAPI calls by representing each with a singlebusiness object schema.

Simple BAPIs can be used for outbound or inbound processing. You can specifysynchronous RFC processing or asynchronous transactional RFC (tRFC) processingwhen you configure a module for a simple BAPI. In addition, for outboundprocessing, you can specify asynchronous queued RFC (qRFC) processing, inwhich BAPIs are delivered to a predefined queue on the SAP server.v In synchronous RFC processing, the SAP server and the adapter must beavailable during processing. In outbound processing, the message flow sends a request and then waits for

a response from the SAP server. In inbound processing, the SAP server sends a request through the adapter to

an endpoint and waits for a response from the adapter.v In asynchronous tRFC outbound processing, the adapter associates a transactionID with the function call to the SAP server. The adapter does not wait for aresponse from the SAP server. If the delivery is unsuccessful, the message flowcan use the SAP transaction ID (TID) to make the request again. The TID is afield in your message.

v In asynchronous tRFC inbound processing, the adapter does not have to beavailable when the SAP server runs the function call. The function call is placedon a list of functions to be invoked, and the call is attempted until it issuccessful.To send function calls from a user-defined outbound queue on the SAP server,you also specify asynchronous tRFC inbound processing.

v In asynchronous qRFC outbound processing, the process is similar toasynchronous tRFC outbound processing. A TID is associated with the functioncall, and the adapter does not wait for a response from the SAP server. Inaddition, the BAPIs are delivered to a predefined queue on the SAP server. Bysending BAPIs to the predefined queue, you can ensure the order in which theyare delivered.

BAPI work unit interface

A BAPI work unit consists of a set of BAPIs that are processed in sequence tocomplete a task. For example, to update an employee record in the SAP system,the record needs to be locked before being updated. This task is accomplished bycalling three BAPIs, in sequence, in the same work unit. The following three BAPIsillustrate the kind of sequence that forms such a unit of work:v BAPI_ADDRESSEMP_REQUESTv BAPI_ADDRESSEMP_CHANGEv BAPI_ADDRESSEMP_APPROVE

The first BAPI locks the employee record, the second updates the record, and thethird approves the update. The advantage of using a BAPI unit of work is that themessage flow can request the employee record change with a single call, eventhough the work unit consists of three separate functions. In addition, if SAPrequires that the BAPIs be processed in a specific sequence for the business flow tocomplete correctly, the work unit supports this sequence.


BAPI result set interface

BAPI result sets use the GetList and GetDetail functions to retrieve an array ofdata from the SAP server. The information that is returned from the GetListfunction is used as input to the GetDetail function.

For example, if you want to retrieve information on a set of customers, you useBAPI_CUSTOMER_GETLIST, which acts as the query BAPI, andBAPI_CUSTOMER_GETDETAIL, which acts as the result BAPI. The BAPIs performthe following steps:1. The BAPI_CUSTOMER_GETLIST call returns a list of keys (for example,

CustomerNumber).2. Each key is mapped dynamically to the business object for

BAPI_CUSTOMER_GETDETAIL.3. BAPI_CUSTOMER_GETDETAIL is processed multiple times, so that an array of

customer information is returned.

You use the Adapter Connection wizard to discover theBAPI_CUSTOMER_GETLIST and BAPI_CUSTOMER_GETDETAIL functions andbuild the key relationship between the two BAPIs. The wizard then generatesbusiness object definitions for these BAPIs as well as other SCA service resources.At run time, the client sets the values in the BAPI_CUSTOMER_GETLIST businessobject, and the adapter returns the corresponding set of customer detail recordsfrom the SAP server.

For more information, see the following topics.v Outbound processing for the BAPI interfacev Business objects for the BAPI interface on page 17

Outbound processing for the BAPI interface:

In BAPI outbound processing, a message flow sends a request to the SAP server.For BAPI units of work and BAPI result sets, processing is handled synchronously(the message flow waits for a response from the SAP server). For simple BAPIs,you can request that processing be handled synchronously or asynchronously (themessage flow does not wait for a response from the SAP server).

For BAPI units of work and BAPI result sets, the processing is handled asdescribed in Synchronous RFC. For simple BAPIs, you make a selection, duringconfiguration, about the type of remote RFC call you want to make.

Synchronous RFC

If you select Synchronous RFC (the default) during configuration for a simpleBAPI, or if you are using BAPI units of work or BAPI result sets, the followingprocessing steps occur:1. The adapter receives a request from a message flow in the form of a BAPI

business object.2. The adapter converts the BAPI business object to an SAP JCo function call.3. The adapter uses the Remote Function Call (RFC) interface to process the BAPI

or RFC function call in the SAP application.4. After passing the data to the SAP server, the adapter handles the response from

SAP and converts it back into the business object format required by themessage flow.

14 Message Flows

5. The adapter then sends the response back to the message flow.

Asynchronous transactional RFC

If you select Asynchronous transactional RFC during configuration, the followingprocessing steps occur:1. The adapter receives a request from a message flow in the form of a BAPI

business object.2. The adapter checks the business object to see whether the SAP transaction ID

attribute has a value assigned. (The SAP transaction ID (TID) is a field in yourmessage.)v If the SAP transaction ID attribute has a value, the adapter uses that valueduring processing.

v If the attribute does not have a value, the adapter makes a call to the SAPserver and gets a transaction ID from the SAP server.

3. The adapter converts the BAPI business object to an SAP JCo function call.4. The adapter uses the transactional Remote Function Call (tRFC) protocol to

make the call to the SAP server.The adapter does not wait for a response from the SAP server.

5. After the function data is passed to the SAP application, control returns to theadapter.v If the call to the SAP server fails, the SAP server throws an ABAPException.v If the call to the SAP server succeeds but contains invalid data, no exceptionis returned to the adapter. For example, if the adapter sends a request thatcontains an invalid customer number, the adapter does not respond with anexception indicating that no such customer exists.

6. The request node builds a message tree that contains the transaction ID as oneof the fields.

Asynchronous queued RFC

If you select Asynchronous queued RFC during configuration, the followingprocessing steps occur:1. The adapter receives a request from a message flow in the form of a BAPI

business object.2. The adapter checks the business object to see whether the SAP transaction ID

attribute has a value assigned. (The SAP transaction ID (TID) is a field in yourmessage.)v If the SAP transaction ID attribute has a value, the adapter uses that valueduring processing.

v If the attribute does not have a value, the adapter makes a call to the SAPserver and gets a transaction ID from the SAP server.

3. The adapter converts the BAPI business object to an SAP JCo function call.4. The adapter uses the tRFC protocol to make the call to the specified queue on

the SAP server.The adapter does not wait for a response from the SAP server.

5. After the function data is passed to the SAP application, control returns to theadapter.v If the call to the SAP server fails, the SAP server throws an ABAPException.v If the call to the SAP server succeeds but contains invalid data, no exceptionis returned to the adapter. For example, if the adapter sends a request thatcontains an invalid customer number, the adapter does not respond with anexception indicating that no such customer exists.

6. The request node builds a message tree that contains the transaction ID as oneof the fields.


Inbound processing for the BAPI interface:

The adapter supports inbound processing (from the SAP server to the adapter) forsimple BAPIs.

A client application on the SAP server invokes a function through the adapter toan end point.

For more information, see the following topics:v Synchronous and asynchronous RFCv Event recovery for the BAPI interface on page 17

Synchronous and asynchronous RFC:

For BAPI outbound processing, you can specify that the processing be handledsynchronously or asynchronously. However, for BAPI inbound processing inWebSphere Message Broker, you can specify that the processing be handledasynchronously only. In asynchronous processing, the SAP application does notwait for a response and the adapter does not have to be available when the SAPapplication makes the function call.

The BAPI interface has a set of activation specification properties for asynchronousRFC, which you use to set up inbound processing. You specify values for theproperties with the Adapter Connection wizard.

The sequence of processing actions that result from an inbound request differ,depending on the selection you make during configuration from the SAP RemoteFunction Call (RFC) type list.

Asynchronous transactional RFC

If you select Asynchronous Transactional/Queued RFC during configuration, thefollowing processing steps occur:1. A client on the SAP server invokes an RFC-enabled function call on the

adapter.

Note: To send the RFC-enabled functions from a queue on the SAP server, theclient program on the SAP server delivers the events to a user-definedoutbound queue.

A transaction ID is associated with the call.The calling program on the SAP server does not wait to see whether the call tothe adapter was successful, and no data is returned to the calling program.

2. The RFC-function call is placed on a list of functions to be delivered.You can see the event list by entering transaction code SM58 on the SAP server

3. The RFC-function call is invoked on the adapter. If the adapter is not available,the call remains in the list on the SAP server, and the call is repeated at regularintervals until it can be processed by the adapter.When the SAP server successfully delivers the call event, it removes thefunction from the list.

4. If you selected Ensure once-only event delivery, the adapter sets thetransaction ID in the event persistent table.This is to ensure the event is not processed more than once.

5. The adapter resolves the operation and business object name using the receivedRFC-enabled function name.

6. The adapter sends the business object to an endpoint.

16 Message Flows

|||||||||||||||||||||||||||||||||||||||||||||

If you are sending functions from a user-defined queue on the SAP server, thefunctions are delivered in the order in which they exist on the queue. You cansee the contents of the queue by entering transaction code SMQ1 on the SAPserver.

7. If the delivery is successful, and if you selected Ensure once-only eventdelivery, the adapter removes the transaction ID from the event persistenttable.If there is a failure when the adapter attempts to deliver the business object, thetransaction ID remains in the event table. When another event is received fromthe SAP server, the following processing occurs:a. The adapter checks the transaction ID.b. If the event matches an ID in the table, the adapter processes the failed

event once.In other words, it does not send the event with the duplicate ID, therebyensuring that the event is processed only once.

Event recovery for the BAPI interface:

You can configure the adapter for BAPI inbound processing so that it supportsevent recovery in case a failure occurs while the event is being delivered from theadapter to the endpoint. When event recovery is specified, the adapter persists theevent state in an event recovery table that resides on a data source.

Event recovery is not the default; you must specify it by enabling once-onlydelivery of events during adapter configuration.

Business objects for the BAPI interface:

A business object is a structure that consists of data, the action to be performed onthe data, and additional instructions for processing the data.

For outbound processing, the broker uses business objects to send data to SAP orobtain data (through the adapter) from SAP. In other words, the broker sends abusiness object to the adapter, and the adapter converts the data in the businessobject to a format that is compatible with an SAP API call. The adapter then runsthe SAP API with this data.

For inbound processing, the SAP server sends a BAPI function call through theadapter to an endpoint. The adapter converts the BAPI function call into a businessobject.

The adapter uses the BAPI metadata that is generated by the Adapter Connectionwizard to construct a business-object definition. This metadata containsBAPI-related information such as the operation of the business object, importparameters, export parameters, table parameters, transaction information, anddependent or grouped BAPIs.

The BAPI business-object definition that is generated by the Adapter Connectionwizard is modeled on the BAPI function interface in SAP. The business-objectdefinition represents a BAPI function, such as a BAPI_CUSTOMER_GETLISTfunction call.

If you change the BAPI interface, you must run the Adapter Connection wizardagain to rebuild the business object definition.


||||||||||||||||||||||

How business-object definitions are created

You create business-object definitions by using the Adapter Connection wizard.The wizard connects to the application, discovers data structures in the application,and generates business-object definitions to represent them. It also generates otherresources that are needed by the adapter, such as the interface information thatindicates the input and output parameters.

Business object structure

The structure of a BAPI business object depends on the interface type (simpleBAPI, BAPI work unit, or BAPI result set).

For more information, see the following topics.v Business object structure for a simple BAPIv Business object structure for a nested BAPIv Business object structure for a BAPI work unit on page 19v Business object structure for a BAPI result set on page 19

Business object structure for a simple BAPI:

A business object for a simple BAPI call reflects a BAPI method or function call inSAP. Each business object property maps to a BAPI parameter. The metadata ofeach business-object property indicates the corresponding BAPI parameter. Theoperation metadata determines the correct BAPI to call.

For a simple BAPI that performs Create, Update, Retrieve, and Delete operations,each operation is represented by a business object, with the business objects beinggrouped together within a wrapper.

The business object wrapper can be associated with multiple operations, but for asimple BAPI, each business object is associated with only one operation. Forexample, while a wrapper business object can contain BAPIs for Create and Deleteoperations, BAPI_CUSTOMER_CREATE is associated with the Create operation,not the Delete operation.

The BAPI business objects are children of the business object wrapper, and,depending on the operation to be performed, only one child object in this wrapperneeds to be populated at run time in order to process the simple BAPI call. Onlyone BAPI, the one that is associated with the operation to be performed, is calledat a time.

If you select Asynchronous Transactional RFC (for outbound or inboundprocessing) or Asynchronous Queued RFC (for outbound processing) , the BAPIwrapper business object also contains a transaction ID. The transaction ID is usedto resend the BAPI call if the receiving system is not available at the time of theinitial call.

Business object structure for a nested BAPI:

A nested BAPI business object contains structure parameters that can contain oneor more other structures as components.

18 Message Flows

A BAPI business object can contain both simple parameters and structureparameters. A business object that contains structure parameters can in turncontain other structures, such as simple parameters and a business object.

Business object structure for a BAPI work unit:

A business object that represents a BAPI work unit (also known as a BAPItransaction) is actually a wrapper object that contains multiple child BAPI objects.Each child BAPI object within the wrapper object represents a simple BAPI.

The adapter supports a BAPI work unit using a top-level wrapper business objectthat consists of multiple child BAPIs, each one representing a simple BAPI in thesequence. The BAPI wrapper object represents the complete work unit, while thechild BAPI objects contained within the BAPI wrapper object represent theindividual operations that make up the work unit.

Business object structure for a BAPI result set:

The top-level business object for a result set is a wrapper that contains a GetDetailbusiness object. The GetDetail business object contains the results of a query forSAP data. The GetDetail business object also contains, as a child object, the querybusiness object. The query business object represents a GetList BAPI. These twoBAPIs work together to retrieve information from the SAP server.

The ALE interfaces:

The SAP Application Link Enabling (ALE) interface and ALE pass-through IDocinterface enable business process integration and asynchronous datacommunication between two or more SAP systems or between SAP and externalsystems. The data is exchanged in the form of Intermediate Documents (IDocs).

The adapter supports outbound and inbound processing by enabling the exchangeof data in the form of business objects.v For inbound processing, SAP pushes the data in IDocs to the SAP adapter. Theadapter converts the IDocs to business objects and delivers them to theendpoint.

v For outbound processing, the SAP adapter converts the business object to anIDoc and delivers it to SAP.

To use the ALE interface or ALE pass-through IDoc interface for inboundprocessing, make sure that your SAP server is properly configured (for example,you must set up a partner profile and register a program ID to listen for events).

Application systems are loosely coupled in an ALE integrated system, and the datais exchanged asynchronously.

IDocs

Intermediate Documents (IDocs) are containers for exchanging data in a predefined(structured ASCII) format across system boundaries. The IDoc type indicates theSAP format that is to be used to transfer the data. An IDoc type can transferseveral message types (the logical messages that correspond to different businessprocesses). IDocs can be used for outbound and inbound processing.

For example, if an application developer wants to be notified when a sales order iscreated on the SAP server, the developer runs the Adapter Connection wizard to


discover the ORDERS05 IDoc on the SAP server. The wizard then generates thebusiness object definition for ORDERS05. The wizard also generates otherresources, such as an EIS export component and Service Component Architecture(SCA) interfaces.

IDocs are exchanged for inbound and outbound events, and IDocs can beexchanged either as individual documents or in packets.

The processing of IDoc data depends on whether you are using the ALE interfaceor the ALE pass-through IDoc interface.v ALE interfaceFor outbound processing, the adapter uses the IDoc business object to populatethe appropriate RFC-enabled function call made to the SAP server.For inbound processing, IDocs can be sent from the SAP server as parsed orunparsed documents For parsed documents, the adapter parses the IDoc and creates a business

object that reflects the internal structure of the IDoc. For unparsed IDocs, the adapter processes the IDoc but does not convert the

data portion of the IDoc.v ALE pass-through IDoc interfaceFor both outbound and inbound processing, the adapter does no conversion ofthe IDoc, which is useful when the client wants to perform the IDoc parsing.

Transactional RFC processing

The adapter uses tRFC (transactional RFC) to assure delivery and to ensure thateach IDoc is exchanged only once with SAP. The tRFC component stores the calledRFC function in the database of the SAP system with a unique transactionidentifier (TID). The TID is a field in your message.

The message flow must determine how to store the SAP transaction ID and how torelate the SAP transaction ID to the data being sent to the adapter. When theevents are successful, the message flow should not resubmit the event associatedwith this TID again to prevent the processing of duplicate events.v If the message flow does not send an SAP transaction ID with the businessobject, the adapter returns one after running the transaction.

v If the message flow has an SAP transaction ID, it must populate the SAPtransaction ID property in the business object with that value before running thetransaction.

The SAP transaction ID can be used for cross-referencing with a global unique IDthat is created for an outbound event. You can create the global unique ID formanaging integration scenarios.

Queued RFC processing

The adapter uses qRFC (queued transactional RFC) to ensure that IDocs aredelivered in sequence to a queue on the SAP server or are received in sequencefrom the SAP server. Additional threads can increase the throughput of a messageflow but you should consider the potential impact on message order. To maintainmessage order, ensure that your message flow is single threaded.

For more information about ALE interfaces, see the following topics:v Outbound processing for the ALE interface on page 21

20 Message Flows

v Inbound processing for the ALE interfacev Pass-through support for IDocs, and MQSeries link for R/3 link migration onpage 26

v ALE business objects on page 28

Outbound processing for the ALE interface:

The adapter supports outbound processing (from the adapter to the SAP server)for the ALE interface and the ALE pass-through IDoc interface. ALE uses IDocs fordata exchange, and the adapter uses business objects to represent the IDocs.

The following list describes the sequence of processing actions that result from anoutbound request using the ALE interface and ALE pass-through IDoc interface.

The message flow that makes the request uses the interface information that wasgenerated by the Adapter Connection wizard.1. The adapter receives a request, which includes an IDoc business object, from a

message flow.For pass-through IDocs, the Message tree contains a BLOB field that representsthe IDoc. No separate IDoc business object exists for pass-through IDocs.

2. The adapter uses the IDoc business object to populate the appropriateRFC-enabled function call used by the ALE interface.

3. The adapter establishes an RFC connection to the ALE interface and passes theIDoc data to the SAP system. If you are using the qRFC protocol, the adapterpasses the IDoc data in the order specified in the wrapper business object tothe specified queue on the SAP server.

4. After passing the data to SAP, the adapter performs one of the following steps:v If the call is not managed by a local transaction using the brokers LocalTransaction Manager, the adapter releases the connection to SAP and doesnot return any data to the caller. When no exceptions are raised, theoutbound transaction is considered successful. You can verify whether thedata is incorporated into the SAP application by inspecting the IDocs thathave been generated in SAP.

v If the call is managed by a local transaction using the brokers LocalTransaction Manager, the adapter returns the transaction ID.The adapter uses the tRFC protocol to support J2C local transactions.

Inbound processing for the ALE interface:

The adapter supports inbound processing (from the SAP server to the adapter) forthe ALE interface and the ALE pass-through IDoc interface.

When you are configuring a module for the ALE interface or the ALE pass-throughinterface, you indicate whether the IDocs are sent as a packet and, for the ALEinterface, you can specify whether they are sent parsed or unparsed. You makethese selections in the Adapter Connection wizard. When you use the ALEpass-through IDoc interface, the Message tree contains a BLOB field that representsthe IDoc. No separate IDoc business object exists for pass-through IDocs.

The following list describes the sequence of processing actions that result from aninbound request using the ALE interface.1. The adapter starts event listeners to the SAP server.2. Whenever an event occurs in SAP, the event is sent to the adapter through the

event listeners.


3. The adapter converts the event into a business object before sending it to theendpoint.

The adapter uses the event recovery mechanism to track and recover events in caseof abrupt termination. The event recovery mechanism uses a data source forpersisting the event state.

The following table provides an overview of the differences between the ALEinterface and the ALE pass-through IDoc interface for inbound processing.

Interface When to use SplitIDoc = true SplitIDoc = false Parsed IDoc = true

ALE inbound This interfaceconverts the rawincoming IDocs tobusiness objects,which are readilyconsumable by theclient at the endpoint.

On receiving the IDocpacket from SAP, theadapter converts theIDocs to businessobjects, one by one,before sending eachone to the endpoint.

On receiving the IDocpacket from SAP, theadapter converts theIDocs in the packet asone business objectbefore sending it tothe endpoint.

The incoming IDoc isonly partially parsed(the control record ofthe IDoc is parsedbut the data record isnot). The client at theendpoint isresponsible forparsing the datarecord.

ALE pass-throughIDoc

This interface wrapsthe raw incomingIDoc in a businessobject beforedelivering it to theclient at the endpoint.The client isresponsible forparsing the raw IDoc.

On receiving the IDocpacket from SAP, theadapter wraps eachraw IDoc within abusiness object beforesending the objects,one by one, to theendpoint.

On receiving the IDocpacket from SAP, theadapter wraps theraw IDoc packet in abusiness object beforesending it to theendpoint.

This attribute is notapplicable to the ALEpass- through IDocinterface. (Neither thecontrol record nor thedata record of theIDoc is parsed.)

For more information, see the following topics.v Event error handlingv Event recovery for the ALE interface on page 23v Event processing for parsed IDoc packets on page 23v Event processing for unparsed IDocs on page 24v IDoc status updates on page 26

Event error handling:

WebSphere Adapter for SAP Software provides error handling for inbound ALEevents by logging the errors and attempting to restart the event listener.

When the adapter detects an error condition, it performs the following actions:1. The adapter logs the error information in the event log or trace file.

Log and trace files are in the /profiles/profile_name/logs/server_name path ofthe folder in which WebSphere Message Broker is installed.

2. The adapter attempts to restart the existing event listeners.The adapter uses the activation specification values for RetryLimit andRetryInterval.v If the SAP application is not active, the adapter attempts to restart thelisteners for the number of times configured in the RetryLimit property.

22 Message Flows

v The adapter waits for the time specified in the RetryInterval parameterbefore attempting to restart the event listeners.

3. If the attempt to restart the event listeners fails, the adapter performs thefollowing actions:v The adapter logs the error condition in the event log or trace file.v The adapter cleans up the existing ALE event listeners.v The adapter starts new event listeners.The adapter uses the values of the RetryLimit and RetryInterval propertieswhen starting the new event listeners.

4. If all the retry attempts fail, the adapter logs the relevant message and CEIevents and stops trying to recover the ALE event listener.You must restart the adapter or Service Component Architecture (SCA)application in this case.

Event recovery for the ALE interface:

You can configure the adapter for ALE inbound processing so that it supportsevent recovery in case of abrupt termination.

When event recovery is specified, the adapter persists the event state in an eventrecovery table that resides on a data source. Event recovery is not the defaultbehavior; you must specify it by enabling once-only delivery of events duringadapter configuration.

Event processing for parsed IDoc packets:

An inbound event can contain a single IDoc or multiple IDocs, with each IDoccorresponding to a single business object. The multiple IDocs are sent by the SAPserver to the adapter in the form of an IDoc packet. You can specify, duringadapter configuration, whether the packet can be split into individual IDocs orwhether it must be sent as one object (non-split).

Event processing begins when the SAP server sends a transaction ID to theadapter. The following sequence occurs.1. The adapter checks the status of the event and takes one of the following

actions:v If this is a new event, the adapter stores an EVNTID (which corresponds tothe transaction ID) along with a status of 0 (Created) in the event recoverytable.

v If the event status is -1 (Rollback), the adapter updates the status to 0(Created).

v If the event status is 1 (Executed), the adapter returns an indication ofsuccess to the SAP system.

2. The SAP system sends the IDoc to the adapter.3. The adapter converts the IDoc to a business object and sends it to the endpoint.

For single IDocs and non-split IDoc packets, the adapter can deliver objects toendpoints that support transactions as well as to endpoints that do not supporttransactions.v For endpoints that support transactions, the adapter delivers the object aspart of a unique XA transaction. When the endpoint processes the event andthe transaction is committed, the status of the event is updated to 1(Executed).The endpoint must be configured to support XA transactions.


v For endpoints that do not support transactions, the adapter delivers theobject to the endpoint and updates the status of the event to 1 (Executed).The adapter delivers the business object without the quality of service (QOS)that guarantees once-only delivery.

4. For split packets only, the adapter performs the following tasks:a. The adapter updates the BQTOTAL column (or table field) in the event

recovery table to the number of IDocs in the packet. This number is usedfor audit and recovery purposes.

b. The adapter sends the business objects to the message endpoint, one afterthe other, and updates the BQPROC property to the sequence number of theIDoc it is working on. The adapter delivers the objects to the appropriateendpoint as part of a unique XA transaction (a two-phase committransaction) controlled by the application server.

c. When the endpoint receives the event and the transaction is committed, theadapter increments the number in the BQPROC property.The message endpoint must be configured to support XA transactions.If theadapter encounters an error while processing a split IDoc packet, it canbehave in one of two ways, depending on the IgnoreIDocPacketErrorsconfiguration property:v If the IgnoreIDocPacketErrors property is set to false, the adapter stopsprocessing any additional IDocs in the packet and reports errors to theSAP system.

v If the IgnoreIDocPacketErrors property is set to true, the adapter logs anerror and continues processing the rest of the IDocs in the packet. Thestatus of the transaction is marked 3 (InProgress). In this case, the adapterlog shows the IDoc numbers that failed, and you must resubmit thoseindividual IDocs separately. You must also manually maintain theserecords in the event recovery table.

This property is not used for single IDocs and for non-split IDoc packets.d. The SAP system sends a COMMIT call to the adapter.e. After the adapter delivers all the business objects in the IDoc packet to the

message endpoint, it updates the event status to 1 (Executed).f. In case of abrupt interruptions during IDoc packet processing, the adapter

resumes processing the IDocs from the current sequence number. Theadapter continues updating the BQPROC property, even ifIgnoreIDocPacketErrors is set to true. The adapter continues the processingin case you terminate the adapter manually while the adapter is processingan IDoc packet.

5. If an exception occurs either while the adapter is processing the event or if theendpoint generates an exception, the event status is updated to -1 (Rollback).

6. If no exception occurs, the SAP server sends a CONFIRM call to the adapter.7. The adapter deletes the records with a 1 (Executed) status and logs a common

event infrastructure (CEI) event that can be used for tracking and auditingpurposes.

Event processing for unparsed IDocs:

Unparsed IDocs are passed through, with no conversion of the data (that is, theadapter does not parse the data part of the IDoc). The direct exchange of IDocs inthe adapter enables high-performance, asynchronous interaction with SAP, becausethe parsing and serializing of the IDoc occurs outside the adapter. The consumer ofthe IDoc parses the IDoc.

24 Message Flows

The adapter processes the data based on whether the packet IDoc is split ornon-split and whether the data needs to be parsed.v The adapter can process packet IDocs as a packet or as individual IDocs. Whenan IDoc is received by the adapter from SAP as a packet IDoc, it is either splitand processed as individual IDocs, or it is processed as a packet. The value ofthe SplitIDocPacket metadata at the business-object level determines how theIDoc is processed.In the case of split IDocs, the wrapper contains only a single, unparsed IDocobject.

v The Type metadata specifies whether the data should be parsed. For unparsedIDocs, this value is UNPARSEDIDOC; for parsed IDocs, the value is IDOC. This valueis set by the Adapter Connection wizard.

Unparsed data format

In the fixed-width format of an unparsed IDoc, the segment data of the IDoc is setin the IDocData field of the business object. It is a byte array of fixed-length data.

The entire segment length might not be used. The adapter pads spaces to the fieldsthat have data; the rest of the fields are ignored, and an end of segment is set. Theend of segment is denoted by a null value.

The following figure shows a segment with fields demarcated by the | symbol forreference.

When the adapter processes this segment into unparsed data, it takes into accountonly those fields that have data in them. It maintains the field width for eachsegment field. When it finds the last field with data, it appends a null value tomark the end of segment.

The next segment data processed as unparsed data would be appended after thenull value.

Limitations

The unparsed event feature introduces certain limitations on the enterpriseapplication for a particular IDoc type.v The enterprise application supports either parsed or unparsed business-objectformat for a given IDoc type or message type.

v For a given IDoc type, if you select unparsed business-object format for inbound,you cannot have inbound and outbound interfaces in the same EAR file, becauseoutbound is based on parsed business objects.

v The DummyKey feature is not supported for unparsed IDocs.

Figure 1. Example of a segment before processing

Figure 2. Example of a segment after processing


IDoc status updates:

To monitor IDoc processing, you can configure the adapter to update the IDocstatus.

When the adapter configuration property ALEUpdateStatus is set to true(indicating that an audit trail is required for all message types), the adapterupdates the IDoc status of ALE business objects that are retrieved from the SAPserver. After the event is sent to the message endpoint, the adapter updates thestatus of the IDoc in SAP to indicate whether the processing succeeded or failed.Monitoring of IDocs applies only to inbound processing (when the IDoc is sentfrom the SAP server to the adapter).

The adapter updates a status IDoc (ALEAUD) and sends it to the SAP server.

An IDoc that is not successfully sent to the endpoint is considered a failure, andthe IDoc status is updated by the adapter. Similarly, an IDoc that reaches theendpoint is considered successfully processed, and the status of the IDoc isupdated.

The status codes and their associated text are configurable properties of theadapter, as specified in the activation specification properties and shown in thefollowing list:v ALESuccessCodev ALEFailureCodev ALESuccessTextv ALEFailureText

Perform the following tasks to ensure that the adapter updates the standard SAPstatus code after it retrieves an IDoc:v Set the AleUpdateStatus configuration property to true and set values for theAleSuccessCode and AleFailureCode configuration properties.

v Configure the inbound parameters of the partner profile of the logical system inSAP to receive the ALEAUD message type. Set the following properties to thespecified values:

Table 1. Inbound properties of the logical system partner profileSAP property Value

Basic Type ALEAUD01

Logical Message Type ALEAUD

Function module IDOC_INPUT_ALEAUD

Process Code AUD1

Pass-through support for IDocs, and MQSeries link for R/3 link migration:

Both the inbound and outbound SAP adapters support a pass-through mode forIDocs.

In this mode, the bit stream for the IDoc is provided without any form of parsing.The bit stream can then be used directly in a message flow, and parsed by otherparsers, or sent unchanged over transports.

26 Message Flows

Use the Adapter Connection wizard to select pass-through support: on theConfigure settings for adapter pane, select ALE pass-through IDoc as the interfacetype.

A business object is created that contains one field, which is the bit stream of theIDoc. You can transform this business object in a Compute node to an MQSeries

link for R/3 format message, as shown in the following example.DECLARE ns NAMESPACE'http://www.ibm.com/xmlns/prod/websphere/j2ca/sap/sapmatmas05';

CREATE COMPUTE MODULE test4_ComputeCREATE FUNCTION Main() RETURNS BOOLEANBEGINCALL CopyMessageHeaders();-- CALL CopyEntireMessage();set OutputRoot.MQSAPH.SystemNumber = '00';set OutputRoot.BLOB.BLOB =

InputRoot.DataObject.ns:SapMatmas05.IDocStreamData;RETURN TRUE;END;

CREATE PROCEDURE CopyMessageHeaders() BEGINDECLARE I INTEGER 1;DECLARE J INTEGER;SET J = CARDINALITY(InputRoot.*[]);WHILE I < J DOSET OutputRoot.*[I] = InputRoot.*[I];SET I = I + 1;END WHILE;END;

CREATE PROCEDURE CopyEntireMessage() BEGINSET OutputRoot = InputRoot;END;END MODULE;

You can also create a request business object from an MQSeries link for R/3message, as shown in the following example.CREATE COMPUTE MODULE test4_ComputeCREATE FUNCTION Main() RETURNS BOOLEANBEGINset

OutputRoot.DataObject.ns:SapMatmas05.IDocStreamData =InputRoot.BLOB.BLOB;

RETURN TRUE;END;END MODULE;

The name of the SapMatmas05 element depends on selections that you make whenyou run the Adapter Connection wizard.

ALE pass-through IDoc business object structure:

During ALE processing, the adapter exchanges business objects with the SAPapplication. The Message tree contains a BLOB field that represents the IDoc.

The Message tree contains a transaction ID, a queue name, stream data, and theIDoc type. The transaction ID (SAPTransactionID) is used to ensure once-onlydelivery of business objects, and the queue name (qRFCQueueName) specifies thename of the queue on the SAP server to which the IDocs should be delivered. Ifyou are not using transaction IDs or queues, these properties are blank.


ALE business objects:

A business object is a structure that consists of data, the action to be performed onthe data, and additional instructions for processing the data. The adapter clientuses business objects to send data to SAP or to obtain data (through the adapter)from SAP.

The adapter uses the IDoc metadata that is generated by the Adapter Connectionwizard to construct a business-object definition. This metadata containsALE-related information such as segment information, field names, and anindication of whether the business object handles a single IDoc or an IDoc packet.

The Message tree contains a BLOB field that represents the IDoc.

How business-object definitions are created

You create business-object definitions by using the Adapter Connection wizard.The wizard connects to the application, discovers data structures in the application,and generates business-object definitions to represent them. It also generates otherresources that are needed by the adapter, such as the interface information thatindicates the input and output parameters.

For more information, see the following topics.v ALE business object structurev Transaction ID support on page 29

ALE business object structure:

During ALE processing, the adapter exchanges business objects with the SAPapplication. The business object represents an individual IDoc or an IDoc packet.This business object is a top-level wrapper object that contains one or more IDocchild objects, each one corresponding to a single IDoc. The same business objectformat is used for inbound and outbound processing.

Wrapper business object

The wrapper business object contains a transaction ID, a queue name, and one ormore IDoc business objects. The transaction ID (SAPTransactionID) is used toensure once-only delivery of business objects, and the queue name(qRFCQueueName) specifies the name of the queue on the SAP server to whichthe IDocs should be delivered. If you are not using transaction IDs or queues,these properties are blank.

For individual IDocs, the wrapper business object contains only one instance of anIDoc business object. For IDoc packets, the wrapper business object containsmultiple instances of an IDoc business object.

IDoc business object

The IDoc business object contains the following objects:v The control record business object contains the metadata required by the adapterto process the business object.

v The data record business object contains the actual business object data to beprocessed by the SAP application and the metadata required for the adapter toconvert it to an IDoc structure for the RFC call.

28 Message Flows

Unparsed IDocs

For an unparsed IDoc, in which the data part of the IDoc is not parsed by theadapter, the IDoc business object contains a dummy key, a control record, and theIDoc data.

Transaction ID support:

An SAP transaction ID (TID) is contained in the ALE wrapper business object andis therefore available as a field in the message tree. You can use transaction IDsupport to ensure once-only delivery of ALE objects.

The most common reason for using transaction ID support is to ensure once andonly once delivery of data. The SAP transaction ID property is always generatedby the Adapter Connection wizard.

The message flow must determine how to store the SAP transaction ID and how torelate the SAP transaction ID to the data being sent to the adapter. When theevents are successful, the message flow should not resubmit the event associatedwith this TID again to prevent the processing of duplicate events.v If the message flow does not send an SAP transaction ID with the businessobject, the adapter returns one after executing the transaction.

v If the message flow has an SAP transaction ID, it needs to populate the SAPtransaction ID property with that value before executing the transaction.

The SAP transaction ID can be used for cross-referencing with a global unique IDthat is created