exchange b2b dg.511 - docs.oracle.com integrator jms reference guide egate_jms_ref.pdf einsight...

SUN B2B SUITE 2.0

eXchange Integrator Developer’s Guide

Release 5.1.1

Copyright © 2007 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms. This distribution may include materials developed by third parties. Sun, Sun Microsystems, the Sun logo, Java, Sun Java Composite Application Platform Suite, SeeBeyond, eGate, eInsight, eVision, eTL, eXchange, eView, eIndex, eBAM, eWay, and JMS are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon architecture developed by Sun Microsystems, Inc. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd. This product is covered and controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited.

Copyright © 2007 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, Etats-Unis. Tous droits réservés. Sun Microsystems, Inc. détient les droits de propriété intellectuels relatifs à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier, et ce sans limitation, ces droits de propriété intellectuels peuvent inclure un ou plus des brevets américains listés à l'adresse http://www.sun.com/patents et un ou les brevets supplémentaires ou les applications de brevet en attente aux Etats - Unis et dans les autres pays. L'utilisation est soumise aux termes de la Licence. Cette distribution peut comprendre des composants développés par des tierces parties. Sun, Sun Microsystems, le logo Sun, Java, Sun Java Composite Application Platform Suite, Sun, SeeBeyond, eGate, eInsight, eVision, eTL, eXchange, eView, eIndex, eBAM et eWay sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d'autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc. UNIX est une marque déposée aux Etats-Unis et dans d'autres pays et licenciée exclusivement par X/Open Company, Ltd. Ce produit est couvert à la législation américaine en matière de contrôle des exportations et peut être soumis à la règlementation en vigueur dans d'autres pays dans le domaine des exportations et importations. Les utilisations, ou utilisateurs finaux, pour des armes nucléaires, des missiles, des armes biologiques et chimiques ou du nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou réexportations vers les pays sous embargo américain, ou vers des entités figurant sur les listes d'exclusion d'exportation américaines, y compris, mais de manière non exhaustive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une façon directe ou indirecte, aux exportations des produits ou des services qui sont régis par la législation américaine en matière de contrôle des exportations et la liste de ressortissants spécifiquement désignés, sont rigoureusement interdites.

Part Number: 820-0266-10

Version 20081125145231

eXchange Integrator Developer’s Guide 2 Sun Microsystems, Inc.

Contents

Contents

List of Tables 6

List of Figures 7

Chapter 1

Introduction 8Overview 8

What’s in This Document 8Text Conventions 9Screenshots 9

Related Documents 9

Sun Microsystems, Inc. Web Site 10

Documentation Feedback 10

Chapter 2

Overview 11Review of eXchange 11

eXchange Protocol Concepts and Terminology 11Business Protocols 11Delivery Protocols 12Delivery Channels and Transport 12

eXchange Components 12OTDs 12B2B Host and eXchangeService 13Business Processes / B2B Protocol Processes (BPs) 13Java Collaboration Definitions (JCDs) 13Databases 13

eXchange Partner Manager (ePM) 14

Logical View of eXchange Architecture 14Purpose and Function of the Layers 15


Section Contents

Chapter 3

eXchange Architecture and Components 18Architectural Overview 18

Inbound Main 18Selectors and Handlers 19Trading Partner Interactions 20Error Handling 22

ExStdEvent 23Background 23

ExStdEvent and the TP profile 23Selector/Handler BPs, ExStdEvent, and the eXchangeService 24

Overview of ExStdEvent Hierarchy 24ExStdEvent MetaDataSection 24ExStdEvent KeysSection 26ExStdEvent SelectableBusinessProcessesSection 29ExStdEvent ConfigurationSection 33

ToPartner and FromPartner Subnodes in the Configuration Section 34ExStdEvent PayloadSection 38ExStdEvent ErrorSection 39

eXchange Services 41Overview 42Services Provided by eXCommonService 42

Example of Retry Service in AS2 44Services Provided by eXBusinessProtocolService 45Services Provided by eXDeliveryProtocolService 46

Default eXchange BPs 47Overview 47Core and Protocol BPs (bpEX_*) 47

Core BPs: SeeBeyond > eXchange > Core Components > BPs 48Protocol BPs: SeeBeyond > eXchange > Protocol Managers > BPs 52User BPs: SeeBeyond > User Components 54

Default eXchange JMS Topics 55Summary of JMS Topics 55Outbound Topics 56Inbound Topics 56Error Topics 56

Chapter 4

Custom Protocols 58Custom Protocol Concepts 58

Creating a Generic Business Protocol 59Setting Up Handlers for Selectors 59

Creating Handlers for Custom Protocols 62Inbound = FromTP 62

Flow for Inbound = FromTP 63


Section Contents

Glossary

Glossary of Acronyms 68

Index 71


List of Tables


List of Tables

Table 1 Text Conventions 9

Table 2 Metadata Section: exstd:EventMetaInformationSectionType 25

Table 3 Keys Section: exstd:EventCorrelationKeysSectionType 26

Table 4 Keys Section: exstd:ExternalIDsType 27

Table 5 Keys Section: exstd:CorrelationKeysType 27

Table 6 Keys Section: exstd:InternalIDsType 28

Table 7 SelectableBPs Section: exstd:SelectableBusinessProcessesSectionType 29

Table 8 SelectableBPs Section: exstd:InvocableBPSignatureType 31

Table 9 SelectableBPs Section: FromPartner 32

Table 10 SelectableBPs Section: ToPartner 32

Table 11 Configuration Section: exstd:TransportConfigurationType 34

Table 12 Configuration Section: CommonProtocolConfigurationType 35

Table 13 Configuration Section: KeysType (ToPartner only) 37

Table 14 Configuration Section: ResendsType (ToPartner only) 37

Table 15 Configuration Section: CertificatesType (FromPartner only) 37

Table 16 Payload Section 38

Table 17 Error Section: exstd:ExceptionDetailsType 40

Table 18 Primary Inputs Required by Retry Service 43

List of Figures


List of Figures

Figure 1 Relationship of eGate to eXchange’s Architectural Layers 14

Figure 2 Outbound ToPartner Flow 16

Figure 3 Inbound FromPartner Flow 17

Figure 4 eXchange Architecture: Inbound Main 19

Figure 5 eXchange Architecture: Selectors and Handler 20

Figure 6 eXchange Architecture: Trading Partner with Batching 20

Figure 7 eXchange Architecture: Trading Partner with Batch-Splitting 21

Figure 8 eXchange Architecture: Trading Partner / Message Delivery 21

Figure 9 eXchange Architecture: Trading Partner Dialogs 22

Figure 10 eXchange Architecture: Error Handling 22

Figure 11 ExStdEvent Hierarchy: The Six Sections 24

Figure 12 ExStdEvent Hierarchy: MetaDataSection 25

Figure 13 ExStdEvent Hierarchy: KeysSection 26

Figure 14 ExStdEvent Hierarchy: SelectableBusinessProcessesSection 29

Figure 15 ExStdEvent Hierarchy: ConfigurationSection 33

Figure 16 ExStdEvent Hierarchy: PayloadSection 38

Figure 17 ExStdEvent Hierarchy: ErrorSection 39

Figure 18 BPs Used in Outbound and Inbound Message Processing 47

Figure 19 eXchange System Folders 58

Figure 20 eXchangeService Mapped to Handlers 60

Figure 21 Separate Inbound and Outbound eXchangeServices Mapped to Handlers 61

Figure 22 Handler BPs Displayed in an ePM Pull-Down List 62

Figure 23 BP Showing Handler Logic 63

Figure 24 Flow Inbound (FromTP) - Operational View 64

Figure 25 Flow Inbound (FromTP) - UML View 64

Figure 26 Core Services (in the Sun SeeBeyond > eXchange Folder) 66

Figure 27 Handler, After Being Dragged Onto the eInsight Canvas 67

Figure 28 Handler With Business Rules and Connections 67

Chapter 1

Introduction

This chapter provides an overview of the Developer’s Guide for Sun B2B Suite eXchange™ Integrator. eXchange is the prerequisite base product for all products in B2B Suite 2.0.

What’s in This Chapter

Overview on page 8

Related Documents on page 9

Sun Microsystems, Inc. Web Site on page 10

Documentation Feedback on page 10

1.1 OverviewThe Developer’s Guide provides information for very experienced users of the eXchange Integrator application. This guide is designed for business analysts and developers with a knowledge of EDI and/or B2B technologies and processes, who design custom business protocols for use with eXchange Integrator. (At the current release, this guide does not provide in-depth information on developing custom delivery protocols.)

1.1.1 What’s in This DocumentThis guide is organized into the following chapters:

Chapter 1, “Introduction” provides an overview of this document’s purpose, contents, writing conventions, and supported documents.

Chapter 2, “Overview” discusses general features and architecture of eXchange.

Chapter 3, “eXchange Architecture and Components” shows and explains the components provided with eXchange.

Chapter 4, “Custom Protocols” provides some hands-on steps for creating a custom protocol with a custom handler.

The Glossary of Acronyms on page 68 lists and explains special acronyms and initialisms that occur in this guide and throughout the B2B Suite..


Chapter 1 Section 1.2Introduction Related Documents

1.1.2 Text ConventionsThe following conventions are observed throughout this document.

1.1.3 ScreenshotsDepending on what products you have installed, and how they are configured, the screenshots in this document may differ from what you see on your system.

1.2 Related DocumentsFor late-breaking information on the B2B Suite, refer to the B2B_Readme file on the product media.

For information on other products in the B2B Suite, refer to the following guides:

eXchange Integrator User’s Guide

ASC X12 OTD Library User’s Guide

ASC X12 Protocol Manager User’s Guide

HIPAA OTD Library User’s Guide

HIPAA Protocol Manager User’s Guide

For more information about Java CAPS products, refer to the following:

Table 1 Text Conventions

Text Convention Used For Examples

Bold Names of buttons, files, icons, parameters, variables, methods, menus, and objects

Click OK.On the File menu, click Exit.Select the eGate.sar file.

Monospaced Command line arguments, code samples; variables are shown in bold italic

java -jar filename.jar

Blue bold Hypertext links within document

See Text Conventions on page 9

Blue underlined Hypertext links for Web addresses (URLs) or email addresses

http://www.sun.com

Title Filename

Java CAPS Installation Guide CAPS_Install_Guide.pdf

Java CAPS Deployment Guide CAPS_Deployment_Guide.pdf

eGate Integrator User’s Guide eGate_UG.pdf

eGate Integrator System Administration Guide eGate_Sys_Admin_Guide.pdf


http://www.sun.com

Chapter 1 Section 1.3Introduction Sun Microsystems, Inc. Web Site

1.3 Sun Microsystems, Inc. Web SiteThe Sun Microsystems web site is your best source for up-to-the-minute product news and technical support information. The site’s URL is:

http://www.sun.com

1.4 Documentation FeedbackWe appreciate your feedback. Please send any comments or suggestions regarding this document to:

[email protected]

eGate Integrator JMS Reference Guide eGate_JMS_Ref.pdf

eInsight Business Process Manager User’s Guide eInsight_UG.pdf

eWay Batch Adapter User’s Guide Batch_eWay_UG.pdf

eWay HTTPS Adapter User’s Guide HTTP_eWay_UG.pdf

eWay File Adapter User’s Guide File_eWay_UG.pdf

eWay LDAP Adapter User’s Guide LDAP_eWay_UG.pdf

eWay Adapter for Oracle User’s Guide Oracle_eWay_UG.pdf

Readme for Java CAPS / eGate Integrator Readme.txt

Title Filename


http://www.sun.com

mailto:[email protected]

Chapter 2

Overview

This chapter provides a general overview of eXchange and protocols.


Review of eXchange on page 11

eXchange Protocol Concepts and Terminology on page 11

eXchange Components on page 12

eXchange Partner Manager (ePM) on page 14

Logical View of eXchange Architecture on page 14

2.1 Review of eXchangeThis section provides a brief review of concepts, terminology, and components that are important for working with eXchange and the protocol managers it supports.

2.1.1 eXchange Protocol Concepts and TerminologyeXchange recognizes three types of protocol layers: business protocol, delivery protocol, and transport. Parameter bindings for these three layers are combined in a transaction profile.

Business Protocols

Business protocols, such as X12, HIPAA, or EDIFACT, codify formal agreements on business transaction types, acknowledgments, enveloping, batching, and message exchange. For each protocol and version, OTDs capture the vocabulary and syntax of business-level transactions.

Semantic metadata is stored in two kinds of extended attributes definitions.

BADs (business attribute definitions) address the functional group level: GS in X12, UNG in EDIFACT.

EADs (enveloping attribute definitions) address the outer enveloping level: ISA in X12, UNA/UNB in EDIFACT.

You can easily modify an existing *AD, or even design an entirely new one if you need it for a particular purpose. For details, see the eXchange Integrator User’s Guide.


Chapter 2 Section 2.1Overview Review of eXchange

Business action groups define choreography of message exchange between partners, such as a request/response pattern and whether or not to expect functional acknowledgments (997 in X12, CONTRL in EDIFACT).

Delivery Protocols

Delivery protocols, such as AS2 and ebXML, codify formal agreements with respect to packaging and package exchange: compression/decompression, encryption/decryption, signing/signature verification, message delivery receipts, and so forth. In general, delivery protocols are unconcerned with the syntax or semantics of the message payload itself.

A MAD (messaging attributes definition) captures the semantic metadata involved in messaging exchange for a particular delivery protocol.

A PAD (packaging attributes definition) captures the semantic metadata involved in outer packaging for a particular delivery protocol.

Delivery action groups define passthrough exchange patterns between B2B partners.

Note: This guide provides only limited coverage of delivery protocols.

Delivery Channels and Transport

Delivery channels reference transport protocols that codify formal agreements on transporting information electronically. Examples include: File, FTP, HTTP, and JMS.

A TAD (transport attributes definition) captures the semantic metadata for a particular transport protocol. The TADs shipped with core eXchange are designed to work with the corresponding SeeBeyond eWays.

2.1.2 eXchange ComponentseXchange’s relationship to protocols is mediated by OTDs, brokered by B2B hosts and corresponding eXchangeServices, handled by BPs and JCDs (both core and protocol-specific), and persisted by the eXchange database.

OTDs

The metadata in BADs, EADs, MADs, and TADs is encoded in XML strings that are marshaled and unmarshaled via their corresponding OTDs.

eXchange also supplies several small OTDs for specific limited purposes, such as parsing cron expressions.

ExStdEvent

A special OTD called ExStdEvent is used to marshal and unmarshal eXchange-specific data, such as metadata and values for a particular trading partner associated with a message, along with payload, headers and trailers, error information, and so forth.


Chapter 2 Section 2.1Overview Review of eXchange

B2B Host and eXchangeService

A B2B host represents an enterprise engaging in B2B e-commerce using eXchange. B2B hosts are designed using an Enterprise Designer GUI that allows the end user to combine and associate the various kinds of *ADs. For example, one BAD and one EAD are assigned to each business action, a MAD and a PAD to each delivery action, and a TAD to each delivery channel.

When a user connects a configured B2B host to a properly configured LDAP server and an Oracle external running the eXchange database, deploying it to an environment has the following effects:

Enterprise Designer creates a new type of external, called an eXchangeService, whose exposed services allow it to invoke (and/or be invoked by) any BP shipped with core eXchange, as well as al

The host's attribute metadata—that is, its *ADs—and its business dialogs and messaging services are exposed to eXchange Partner Manager (ePM); see “eXchange Partner Manager (ePM)” on page 14.

The eXchange database is made ready for storing information on trading partners and messages/packages to the eXchange message tracking facility.

Business Processes / B2B Protocol Processes (BPs)

eXchange B2B protocol processes are business processes (BPs) that model the logic and processing associated with business protocols and delivery protocols.

eXchange core BPs are protocol-nonspecific, and provide such services as driving other BPs, selecting error handlers, tracking duplicated messages and packages, and so forth.

Protocol-specific BPs are supplied with each protocol manager that SeeBeyond provides, tailored to meet the needs of that particular protocol. For example, the EDIFACT protocol manager supplies batcher, splitter, and acknowledgment-processing BPs that differ from their counterparts in X12, and the AS2 protocol manager supplies protocol-specific BPs for packaging/unpackaging, MDN generation, and the like.

Java Collaboration Definitions (JCDs)

As with BPs, eXchange supplies a set of core JCDs for protocol non-specific tasks (such as sequencing, generating GUIDs, and so forth), and each protocol manager supplies additional JCDs; for example, the AS2 protocol manager supplies JCDs for base64 decoding/encoding, cryptographic manipulation, and MDN processing, while X12 supplies JCDs for dealing with functional groups, interchanges, and TA1s.

Databases

At eXchange release 5.1.0, Oracle is used for the eXchange database that manages trading partner information and message/package tracking information). In addition, the optional eInsight database can be used to provide BP persistence/recovery and monitoring. Specific database version support is listed in the eXchange Integrator User’s Guide.


Chapter 2 Section 2.2Overview Logical View of eXchange Architecture

2.1.3 eXchange Partner Manager (ePM)eXchange Partner Manager (ePM) is the GUI where values are supplied for metadata parameters that were defined for the B2B host. In ePM, the end user assigns values to these metadata definitions; a well-configured named set of values is called a binding. Each trading partner profile consists of one or more bindings.

The parameters displayed in ePM come from three places:

Invariant parameters are determined by eXchange core.

Handler BPs appear in ePM when the corresponding selector BP is exposed by activating a project in the eXchange Deployment.

Other parameters come from the *ADs defined in the B2B host. For example, the last parameters in the To[From]Partner Transport tabs are governed by the TAD, the last parameters in the To[From]Partner Packaging tabs are governed by the MAD, the last parameters in the To[From]Partner Enveloping tabs are governed by the EAD, and the last parameters in each Business Actions tab are governed by the BAD.

2.2 Logical View of eXchange ArchitectureAs a message transits through eXchange, it is processed by up to four layers. The layers use selector/handler B2B protocol processes (BPs) that act on individual and batched messages as they travel outbound to, and inbound from, trading partners. See Figure 1.

Figure 1 Relationship of eGate to eXchange’s Architectural Layers

eGat

e (ty

pica

lly a

n eW

ay)

eGat

e (ty

pica

lly J

MS

)

Inte

rnal

Del

iver

y C

hann

el

Bus

ines

s Pr

otoc

ol

Del

iver

y Pr

otoc

ol

Exte

rnal

Del

iver

y C

hann

el

eXchange: Multi-Layer Processing

Outbound message (Sending: To TP from internal)

Inbound message (Receiving: From TP to internal)

IDC BP DP DC



For each layer, a read-only selector BP (from eXchange core) can dynamically invoke an appropriate handler BP; the handler can be a protocol-specific BP that was shipped with a SeeBeyond protocol manager, or it can be a custom protocol that was modified from an as-shipped protocol BP or created from scratch.

Outbound messages start in the internal eGate system and traverse the eXchange layers left to right, eventually reaching an external that transports them to the trading partner. Inbound messages come from a trading partner via one of many possible externals and traverse the eXchange layers right to left on their way to the internal eGate system.

This “big picture” suppresses some exceptions and details. For example: Some layers can be bypassed if not needed by a particular protocol or project; certain protocols require additional inter-layer processing for acknowledgments and message delivery notifications; and handling of errors and exceptions occurs at and between all layers.

Purpose and Function of the Layers

The purpose and function of each eXchange layer is described below.

The Internal Delivery Channel (IDC) layer handles the eGate/eXchange transition. Its services are provided through eXDeliveryChannelService.

The Business Protocol (BP) layer performs operations on messages, batches, and envelopes. Its services are provided through eXBusinessProtocolService.

This layer is heavily used for processing X12, HIPAA, and EDIFACT messages.

The Delivery Protocol (DP) layer deals with delivery protocols such as AS2 or ebXML. Its services are provided through eXDeliveryProtocolService.

When not used, the Delivery Protocol layer is bypassed.

The External Delivery Channel (DC) layer handles the eXchange/external transition. Its services are provided through eXDeliveryChannelService.

The eXchangeService for a particular B2B host is able to invoke all common external communication eWays, such as the Batch FTP and HTTP eWays.

Outbound: Sending from Internal to IDC to BP to DP to XDC to External

1 The internal system (eGate) supplies the message to eXchange. This is typically done via a JMS topic, but can also be accomplished by means of a file or via FTP, HTTP, SMTP, etc. The message must contain a pointer to a valid TP profile.

2 The eXchange IDC layer, if used, receives the message, examines its payload for a reference to a trading partner, looks up and adds the trading partner profile.

If the IDC layer is not used, then the eGate message must already have a string that corresponds to the TP profile that the IDC layer would have looked up and added, and all BPs normally invoked by the IDC layer are bypassed.

3 The eXchange BP layer invokes B2B protocol processes (bpEX_*) that perform one or more of the following: batching, enveloping, correlating requests with responses, checking for duplicates, generating acknowledgments, and message tracking.

4 The eXchange DP layer invokes B2B protocol processes (bpEX_*) that perform one or more of the following: signing/compressing/encrypting of the envelope, and package tracking.



5 The eXchange DC layer determines the transport method and attributes for the targeted trading partner, and supplies transport-specific parameters to be handed (through an eXchangeService proxy) to the corresponding communication eWay.

6 In eGate, the communication eWay (chosen by the eXchangeService, which also provides the eWay with communication parameters based on the environment it references and the previous message processing) passes data to the external system that corresponds to the TP profile.

7 The external system takes over for any further processing of the message.

The outbound ToPartner flow of ExStdEvent as it passes from BP to topic to BP is illustrated in Figure 2.

Figure 2 Outbound ToPartner Flow

Inbound: Receiving from External to XDC to DP to BP to IDC to Internal

1 The external system passes a message into eGate via a communication eWay. Based on the transport method and endpoint, eXchangeService routes the message to the appropriate DC.

2 The eXchange DC layer uses information in the TP profile to determine which Delivery Protocol(s) to invoke for further processing.

3 The eXchange DP layer invokes B2B protocol processes (bpEX_*) that perform one or more of the following: decryption/decompression/signature-verification on a per-envelope basis, checking for duplicate deliveries, and package tracking.

4 The eXchange BP layer invokes B2B protocol processes (bpEX_*) that perform one or more of the following: envelope and message validation, splitting(unbatching),



checking for duplicate messages, correlating, generating acknowledgments, and message tracking.

5 The eXchange IDC layer, based on information supplied by one or more business protocol processes (bpEX_*), supplies eGate with a message payload, typically via a JMS topic.

6 The internal system (eGate) takes over for any further processing of the message.

The inbound FromPartner flow of ExStdEvent as it passes from BP to topic to BP is illustrated in Figure 3.

Figure 3 Inbound FromPartner Flow


Chapter 3

eXchange Architecture and Components


Architectural Overview on page 18

ExStdEvent on page 23

eXchange Services on page 41

Default eXchange BPs on page 47

Default eXchange JMS Topics on page 55

3.1 Architectural OverviewInbound Main on page 18

Selectors and Handlers on page 19

Trading Partner Interactions on page 20

Error Handling on page 22

3.1.1. Inbound MainProcessing begins when an ExStdEvent contains sufficient “seed” information to identify the trading partner, service (business dialog or messaging service), direction (ToPartner or FromPartner), and business action. This allows a trading partner lookup to occur so that the remainder of the trading partner information can be written to the ExStdEvent.

For detailed information on ExStdEvent, see “ExStdEvent” on page 23.

After ExStdEvent is populated with information stored for that particular transaction type for that particular partner (as part of the trading partner profile), it is marshaled to JMS topic EX_FROMINTERNAL or EX_FROMTP for uptake by a selector in the FromInternal or FromTP core BP. See Figure 4.

eXchange Integrator Developer’s Guide 18 SeeBeyond Proprietary and Confidential

Chapter 3 Section 3.1eXchange Architecture and Components Architectural Overview

Figure 4 eXchange Architecture: Inbound Main

3.1.2. Selectors and HandlersAt various points, a populated ExStdEvent encounters a selector that performs a dynamic BP invocation, acting as a “switch” to the handler. Thus, custom protocols must be implemented as BPs that are invoked by selectors.

Each selector is a read-only core component that hands off to whatever value was set for the handler in ePM (and thus known to ExStdEvent), permitting the protocol designer to customize any handler BP and swap it in at the appropriate point. See Figure 5.



Figure 5 eXchange Architecture: Selectors and Handler

3.1.3. Trading Partner InteractionsTrading Partner Interactions with Batching on page 20

Trading Partner Interactions with Batch-Splitting on page 21

Trading Partner Interactions with Message Delivery on page 21

Trading Partner Interactions with Dialogs on page 22

Trading Partner Interactions with Batching

Figure 6 illustrates the flow by which batching takes place for business protocols and, if implemented, for delivery protocols as well. Instances of ExStdEvent flow from the EX_BATCHER topic, are processed by one or both batcher selectors, and ultimately flow into the EX_MESSAGETOTP topic.

Figure 6 eXchange Architecture: Trading Partner with Batching



Trading Partner Interactions with Batch-Splitting

Figure 7 illustrates the flow by which batch-splitting takes place for business protocols. The batch-splitter selector hands off to a BP that validates the batch envelope, extracts the individual messages, performs validation, duplicate-checking, and generation of business acknowledgments.

Figure 7 eXchange Architecture: Trading Partner with Batch-Splitting

Trading Partner Interactions with Message Delivery

Figure 8 illustrates the flow of ExStdEvents from the EX_MESSAGETOTP topic, where they undergo correlation tests and flow into the EX_TODELIVERY topic if they pass, or (if they fail) back into the EX_MESSAGETOTP topic.

Figure 8 eXchange Architecture: Trading Partner / Message Delivery



Trading Partner Interactions with Dialogs

Figure 9 illustrates the flow of ExStdEvents from the EX_DIALOG{TO|FROM}TP topic into the BPs that correlate for business acknowledgments.

Figure 9 eXchange Architecture: Trading Partner Dialogs

3.1.4. Error HandlingeXchange provides an error-handler BP whose selector reads from the EX_ERROR topic and hands off the item to one of two components: If the ExStdEvent OTD can parse the item—in other words, when the ExStdEvent has both message and error information— it is handed off to a (potentially customized) handler and is ultimately delivered to the EX_PROCESSEDERRORS topic; otherwise, if the item cannot be parsed, it is dumped into the EX_DEADLETTER topic. See Figure 10.

Figure 10 eXchange Architecture: Error Handling


Chapter 3 Section 3.2eXchange Architecture and Components ExStdEvent

3.2 ExStdEventThis section provides detailed information on eXchange’s standard Object Type, named ExStdEvent, located in SeeBeyond > eXchange > Core Components > OTDs.

3.2.1 BackgroundTo understand eXStdEvent’s progress through topics and BPs, you need to have a clear grasp of the roles played by the B2B host / eXchangeService) and the ePM parameters that constitute a TP profile. The concepts, covered elsewhere, are recapitulated below.

B2B Host and eXchangeService

When the design of a B2B host is completed, deploying the B2B host project—more precisely, activating a deployment profile in the project that contains the B2B host— creates an eXchangeService.

An eXchangeService acts like an external: It appears in the environment—specifically, in the environment referenced by the DP whose activation created it—and it also appears in the project tree as an item that can be dragged onto a connectivity map.

An instance of an eXchangeService on a connectivity map acts like a processing node. The eWay-like connections to it can be either inbound (=invoking the eXchangeService) or outbound (=invoked by the eXchangeService).

Activating a B2B host not only creates an eXchangeService, it also makes its toolset of components, services, metadata, and environment references available to eXchange Partner Manager (ePM).

eXchangeService, ePM Parameters, and TP profiles

In ePM, each TP profile is bound to a specific set of parameters: The types of parameters are determined by the settings in the B2B host whose activation produced the eXchangeService, but the specific values of the parameters is TP-specific, and is therefore supplied in ePM for each TP profile. After the required and optional parameters have been supplied, then activation of the TP profile writes the parameter set to the eXchange database, making all parameter values available for dynamic lookup by eXchangeServices such as getExStdEvent.

When an outbound ExStdEvent is entrained into eXchange, the first process that occurs is a lookup of the TP profile to determine parameter values. This content is added to the message as it enters eXchange for processing, and individual parameter values are used to determine further processing of the message.

ExStdEvent and the TP profile

Each eXchange message is marshaled and unmarshaled using the eXStdEvent OTD, which this section describes in detail; see below. As the message traverses the BPs in core eXchange and protocol manager composite applications, each BP in turn consumes the message, uses parameters in the message content (such as fields in the TP profile) to accomplish processing and/or to modify message content, and then passes it along to the next BP, usually via a specific JMS topic.



Selector/Handler BPs, ExStdEvent, and the eXchangeService

A “selector/handler” pattern is used by core eXchange BPs, with the eXchangeService (the activated B2B Host) acting as a broker. AbcXyzSelector reads ExStdEvent, queries the current value of a particular parameter, and then invokes eXchangeService as a proxy. From the available choices, eXchangeService chooses the correct handler to load and invokes eXevent.AbcXyzHandler:AbcXyz<n>. When AbcXyzHandler returns, eXchangeService returns control to AbcXyzSelector, which then continues processing the (possibly modified) eXStdEvent.

3.2.2 Overview of ExStdEvent HierarchyThe ExStdEvent OTD consists of a repeating required groupnode named Container, which contains six child groupnodes, called sections: Metadata (required), Keys (optional), SelectableBusinessProcesses (required), Configuration (required), Payload (required), and Error (optional), as shown in Figure 14.

Figure 11 ExStdEvent Hierarchy: The Six Sections

3.2.3 ExStdEvent MetaDataSectionThe ExStdEvent Metadata section is required. It contains the required Event groupnode and three optional leafnodes, as shown in Figure 12 and described in Table 2.



Figure 12 ExStdEvent Hierarchy: MetaDataSection

Table 2 Metadata Section: exstd:EventMetaInformationSectionType

Node Name Type[*] Description

Event > BusinessProtocolName Lf; Opt; Sgl; string

Identifies the business protocol.

Event > DialogName Lf; Opt; Sgl; string

Identifies the business dialog or messaging service where the transaction occurs.

Event > TradingPartnerExternalIdentifier

Lf; Opt; Sgl; string

Identifies the TP by profile ID.

Event > TradingPartnerName Lf; Opt; Sgl; string

Identifies the TP by name.

Event > BusinessTransactionIdentifier


Identifies the type of message. For example: Request, Reponse, Business Ack, BatchAck

Event > Direction Lf; Req; Sgl; string

Value must be either ToPartner or FromPartner.

Event > ProtocolRespondToMessageID


The value is supplied by an eXConfig call that uses the Group Service Map Table/call.

DeliveryChannelLf; Opt; Sgl; string

Reserved for future use.DeliveryProtocol

BusinessProtocol

[*] — Lf|Ch|Gr = leaf|choice|group; Opt|Req = optional|required; Sgl|Rep = singleton|repeating



3.2.4 ExStdEvent KeysSectionThe ExStdEvent Keys section is optional. It contains two optional leafnodes and three required groupnodes, as shown in Figure 13 and described in the following four tables.

Figure 13 ExStdEvent Hierarchy: KeysSection

Table 3 Keys Section: exstd:EventCorrelationKeysSectionType


SynchronousInboundTopicNameKey Lf; Opt; Sgl; string

The name of the temporary JMS topic for synchronous request/reply inbound into eXchange.Reserved for future use.

SynchronousOutboundTopicNameKey Lf; Opt; Sgl; string

The name of the temporary JMS topic for synchronous request/reply outbound from eXchange.Reserved for future use.

ExternalIDs > ... (see Table 4) Gr; Req; Sgl External identifiers provided by the application or protocol.

CorrelationKeys > ... (see Table 5) Gr; Req; Sgl Typically constructed by concatenating identifiers for the items to be correlated.

InternalIDs > ... (see Table 6) Gr; Req; Sgl GUIDs (globally unique identifiers) created by the system to uniquely identify the item.




The ExternalIDs groupnode contains leafnodes only, as described in Table 4. Contents of each leafnode are provided by the application or protocol.

The CorrelationKeys groupnode contains leafnodes only, as described in Table 5. Contents of each leafnode are typically constructed by concatenating identifiers.

Table 4 Keys Section: exstd:ExternalIDsType


TransactionBatchExternalID Lf; Opt; Sgl; string

External identifier for the batch; in X12, for example, the ISA control number.

TransactionGroupExternalID Lf; Opt; Sgl; string

External identifier for the group; in X12, for example, the GS control number.

TransactionConversationExternalID Lf; Opt; Sgl; string

External identifier for the “conversation” (=“all related messages for the current business or delivery transaction”).

TransactionExternalID Lf; Opt; Sgl; string

External identifier for the segment; in X12, for example, the ST control number.

DeliveryExternalUniqueID Lf; Opt; Sgl; string

External identifier for the delivery channel.


Table 5 Keys Section: exstd:CorrelationKeysType


ApplicationCorrelationKey Lf; Opt; Sgl; string

For correlating asynchronous interactions between Java CAPS and eXchange.

BizAckCorrelationKey Lf; Opt; Sgl; string

For correlating business acknowledgments; in X12, for example, this might combine TPID + TransactionType + ExGroupID + ST control number.

BizResponseCorrelationKey Lf; Opt; Sgl; string

For correlating a response to the initiating request, at the business level; in X12, for example, this might combine BizExternalUniqID + TPID + ExTransactionID.

BusinessReceiptAckCorrelationKey Lf; Opt; Sgl; string

For correlating a business receipt ack (that is, a technical ack) with the matching message, at the delivery level; in X12 for example, this could be TPID + BatchExternalUniqueID.

DeliveryReceiptAckCorrelationKey Lf; Opt; Sgl; string

For correlating a delivery receipt ack (that is, a technical ack) with the matching message, at the delivery level; in X12 for example, this could be TPID + ExternalUniqueID.




The InternalIDs groupnode contains leafnodes only, as described in Table 6. Contents of each leafnode are GUIDs generated by the system.

Table 6 Keys Section: exstd:InternalIDsType


ExDialogGUID Lf; Opt; Sgl; string

Uniquely identifies each instance of the pattern (= business dialog or messaging service).

ExStdEventGUID Lf; Opt; Sgl; string

Uniquely identifies a snapshot of ExStdEvent in the tracking tables.

ExDeliveryChannelContentGUID Lf; Opt; Sgl; string

Uniquely identifies the transport layer.

ExDeliveryProtocolContentGUID Lf; Opt; Sgl; string

Uniquely identifies the delivery protocol envelope (and possibly message content as well, depending on settings).

ExBatchContentGUID Lf; Opt; Sgl; string

Uniquely identifies an instance of a batch.

ExGroupContentGUID Lf; Opt; Sgl; string

Uniquely identifies instances of groups contained within a batch.

ExBizProtocolContentGUID Lf; Opt; Sgl; string

Uniquely identifies message payloads that are exchanged in a pattern which is itself identified by ExTransactionID.

ExHostGUID Lf; Opt; Sgl; string

Uniquely identifies the B2B Host.

ExTradingPartnerGUID Lf; Opt; Sgl; string

Uniquely identifies the trading partner.

ExAuditGUID Lf; Opt; Sgl; string

Uniquely identifies the message blob for auditing purposes: If auditing, the message is stored prior to the transaction or trading partner being known.

ExActionGUID Lf; Opt; Sgl; string

Uniquely identifies the individual items (business actions) in the pattern which is itself identified by ExDialogGUID.




3.2.5 ExStdEvent SelectableBusinessProcessesSectionThe ExStdEvent SelectableBusinessProcesses section is required, but all leafnodes are optional, and all contents are reserved for future use. The section contains four required groupnodes, as shown in Figure 14 and described in the following four tables.

Figure 14 ExStdEvent Hierarchy: SelectableBusinessProcessesSection

Table 7 SelectableBPs Section: exstd:SelectableBusinessProcessesSectionType


DeliveryChannel Gr; Req; Sgl Contains one optional groupnode:DeliveryChannelBP

This BP groupnode has six children leafnodes of type IBPS, as described in Table 8. Reserved for future use.

DeliveryProtocol Gr; Req; Sgl Contains six groupnodes, as follows:Four optional groupnodes of type IBPS:

DeliveryProtocolValidationBPDeliveryMessageSyntaxValidationBPCustomDeliveryProtocolValidationBPDeliveryProtocolEnveloperBP

Each of the four BP groupnodes above has six children leafnodes of type IBPS, as described in Table 8. Reserved for future use.Two required groupnodes:

FromPartner—See Table 9.ToPartner—See Table 10.



BusinessProtocol Gr; Req; Sgl Contains nine groupnodes, as follows:Seven optional groupnodes of type IBPS:

BusinessProtocolValidationBPBusinessMessageSyntaxValidationBPBusinessTransactionTypeBPCustomBusinessProtocolValidationBPBusinessAckGeneratorBPBusinessAckProcessorBPCustomBusinessTranslationBP

Each of the seven BP groupnodes above has six children leafnodes of type IBPS, as described in Table 8. Reserved for future use.

FromPartner—See Table 9.ToPartner—See Table 10.

Common Gr; Req; Sgl Contains two optional groupnodes:ErrorHandlerBPCustomExternalUniqueIDBP

Each of these two BP groupnodes has six children leafnodes of type IBPS, as described in Table 8. Reserved for future use.


Table 7 SelectableBPs Section: exstd:SelectableBusinessProcessesSectionType (Continued)




The InvocableBPSignatureType (IBPS) Groupnode

Within the SelectableBusinessProcesses section, the InvocableBPSignatureType group, or IBPS, is a child of several groupnodes. It contains four required leafnodes and two optional leafnodes, as described in Table 8.

The FromPartner Groupnode in the SelectableBPs Section

Within the SelectableBusinessProcesses section, the FromPartner group is a child of several groupnodes. It contains four groupnodes, as described in Table 9.

Table 8 SelectableBPs Section: exstd:InvocableBPSignatureType


Project Lf; Req; Sgl; string

Reserved for future use.

Deployment Lf; Req; Sgl; string

JndiNamespace Lf; Req; Sgl; string

Partner Lf; Req; Sgl; string

InvokeTimestamp Lf; Opt; Sgl; datetime

CompleteTimestamp Lf; Opt; Sgl; datetime




Table 9 SelectableBPs Section: FromPartner


Batch Gr; Req; Sgl Contains four optional groupnodes:BatchSplitterBPDecryptionBPSignatureValidationBPDecompressionBP

Each of the above four groupnodes contains the six children leafnodes of type IBPS, as described in Table 8.

DecryptionBP Gr; Opt; Sgl Contains the six children leafnodes of type IBPS, as described in Table 8.

SignatureValidationBP Gr; Opt; Sgl Contains the six children leafnodes of type IBPS, as described in Table 8.

DecompressionBP Gr; Opt; Sgl Contains the six children leafnodes of type IBPS, as described in Table 8.


The ToPartner Groupnode in the SelectableBPs Section

Within the SelectableBusinessProcesses section, the ToPartner group is a child of several groupnodes. It contains four groupnodes, as described in Table 10.

Table 10 SelectableBPs Section: ToPartner


Batch Gr; Req; Sgl Contains four optional groupnodes:BatcherBPEncryptionBPSigningBPCompressionBP

Each of the above four groupnodes contains the six children leafnodes of type IBPS, as described in Table 8.

EncryptionBP Gr; Opt; Sgl Contains the six children leafnodes of type IBPS, as described in Table 8.

SigningBP Gr; Opt; Sgl Contains the six children leafnodes of type IBPS, as described in Table 8.

CompressionBP Gr; Opt; Sgl Contains the six children leafnodes of type IBPS, as described in Table 8.




3.2.6 ExStdEvent ConfigurationSectionThe ExStdEvent Configuration section contains trading partner profile configuration information supplied by the ePM user; thus, protocols should consider all parameters in this section to be read-only. (However, parameter values to be used at run time can be modified in the Payload section via the RuntimeConfiguration mirror; see Table 16 on page 38.)

The Configuration section is required, and contains three required groupnodes:

DeliveryChannel—Contains all information needed for transport to/from the trading partner. Information in this section drives the configuration of eWays used for transport.

DeliveryProtocol—Contains all information relating to delivery protocols such as AS2 and ebXML.

BusinessProtocol—Contains all information relating to business protocols such as X12 and EDIFACT.

Each of these three groupnodes contains two subnodes, ToPartner and FromPartner, which are themselves groupnodes; see Figure 15.

Figure 15 ExStdEvent Hierarchy: ConfigurationSection



ToPartner and FromPartner Subnodes in the Configuration Section

For DeliveryChannel:

The contents of the ToPartner and FromPartner subnodes are each a TransportConfigurationType; see “TransportConfigurationType (under ToPartner and FromPartner)” on page 34.

For DeliveryProtocol and BusinessProtocol:

The ToPartner subnode contains three groupnodes; see “Subnodes Common, Keys, and Resends (under ToPartner)” on page 35.

The FromPartner subnode contains two groupnodes; see “Subnodes Common, Keys, and Resends (under ToPartner)” on page 35.

and FromPartner subnodes are each a TransportConfigurationType; see Table 11.

TransportConfigurationType (under ToPartner and FromPartner)

Within the Configuration section, the TransportConfigurationType group is a child of two groupnodes under DeliveryChannel. It consists of eight attributes and three optional nodes, as described in Table 11.

Table 11 Configuration Section: exstd:TransportConfigurationType


TransportProtocolName Lf; Opt; Sgl; string

(internal use)

TransportProtocolVersion Lf; Opt; Sgl; string

(internal use)

ServerSecurityDetailsRef Lf; Opt; Sgl; string


ClientSecurityDetailsRef Lf; Opt; Sgl; string

SecurityProtocolName Lf; Opt; Sgl; string

SecurityProtocolVersion Lf; Opt; Sgl; string

ClientCertificateRef Lf; Opt; Sgl; string

ServerSecurityDetailsRef Lf; Opt; Sgl; string

UseSynchronousChannel Lf; Opt; Sgl; boolean

(internal use)

ExtAttributes

Note: Holds values for the transport attributes definition (TAD).

Gr; Opt; Sgl Contains two optional leaf nodes:OTDIdentifier—Name of the TAD.ExtAttributeValue—XML string that codes the attributes in the TAD.



Subnodes Common, Keys, and Resends (under ToPartner)

Within the Configuration section, under both DeliveryProtocols and BusinessProtocols, the ToPartner subnode contains:

One required groupnode, named Common (see Table 12 on page 35).

Two optional groupnodes, named Keys (see Table 13 on page 37) and Resends (see Table 14 on page 37). These are both currently reserved for future use.

Subnodes Common and Certificates (under FromPartner)

Within the Configuration section, under both DeliveryProtocols and BusinessProtocols, the FromPartner subnode contains:

One required groupnode, named Common (see Table 12 on page 35).

One optional groupnode, named Certificates (see Table 15 on page 37). Currently reserved for future use.

TrackForAudit Lf; Opt; Sgl; boolean

Determines whether audit tracking of messages to/from this TP is to be performed. Reserved for future use.


Table 12 Configuration Section: CommonProtocolConfigurationType


DuplicationChecking Lf; Req; Sgl; boolean

When set to true, transactions are checked for duplication, and any duplicate detected is rejected.

UseEncryption Lf; Req; Sgl; boolean


UseSignature Lf; Req; Sgl; boolean


UseCompression Lf; Req; Sgl; boolean


UseAcknowledgements Lf; Req; Sgl; boolean

When set to true, inbound interchanges are acknowledged (in EDIFACT, for example, by sending a CONTRL); each inbound message is parsed to determine the appropriate acknowledgment to send.

Table 11 Configuration Section: exstd:TransportConfigurationType (Continued)




CharacterSetEncoding Lf; Opt; Sgl; string

(Can be any string that is meaningfully interpreted by the protocol.)

MessageEncoding Lf; Opt; Sgl; string

(Can be any string that is meaningfully interpreted by the protocol. Examples: base64, hex, binary.)

ContentType Lf; Opt; Sgl; string

(Can be any string that is meaningfully interpreted by the protocol. Example: MIME type.)

SendWarningsWithACK Lf; Req; Sgl; boolean

(Not currently used.)

Tracking Gr; Req; Sgl Reserved for future use.

BatchReleaseCriteria > ReleaseQty Lf; Opt; Sgl; int

Threshold (message count) beyond which a batch send is triggered.

BatchReleaseCriteria > ReleaseSize Lf; Opt; Sgl; string


BatchReleaseCriteria > ReleaseCronSchedule


Cron expression that signifies when and how often to run. Upon reaching a date/time that satisfies the expression, a batch is sent even if the message count has not exceeded ReleaseQty.

BatchReleaseCriteria > IsFastBatch Lf; Opt; Sgl; boolean


BatchReleaseCriteria > TPMessageSenderInfo

Gr; Req; Sgl Contains one subnode, Reliability, which contains two required leaf nodes:

Timeout—Maximum time to wait before attempting a re-send.MaxRetryCount—Maximum number of times to retry sending before giving up.

ProtocolExtAttributes

Note: Holds values for the business attributes definition (BAD).

Gr; Opt; Sgl Contains two optional leaf nodes:OTDIdentifier—Name of the BAD.ExtAttributeValue—XML string that codes the attributes in the BAD.

BatchExtAttributes

Note: Holds values for the enveloping attributes definition (EAD).

Gr; Opt; Sgl Contains two optional leaf nodes:OTDIdentifier—Name of the EAD.ExtAttributeValue—XML string that codes the attributes in the EAD.


Table 12 Configuration Section: CommonProtocolConfigurationType (Continued)




Table 13 Configuration Section: KeysType (ToPartner only)


EncryptionKey Gr; Opt; Sgl


EncryptionAlgorithm Lf; Opt; Sgl; string

EncryptionExtAttributes Gr; Opt; Sgl

SigningKey Gr; Opt; Sgl

SigningAlgorithm Lf; Opt; Sgl; string

SigningExtAttributes Gr; Opt; Sgl


Table 14 Configuration Section: ResendsType (ToPartner only)


MaxResends Lf; Req; Sgl; long


MinutesBetweenResends Lf; Req; Sgl; long

Timeout value for the business dialog; if this amount of time elapses without an acknowledgment or response, then an exception is thrown.


Table 15 Configuration Section: CertificatesType (FromPartner only)


SignatureVerificationCertificate Lf; Opt; Sgl; string

Reserved for future use.DecryptionCertificate Lf; Opt; Sgl;

string




3.2.7 ExStdEvent PayloadSectionThe ExStdEvent Payload section is required. It contains six nodes: two optional leafnodes, a required groupnode, two optional groupnodes, and an optional repeating groupnode. This is shown in Figure 16, and described in detail in Table 16.

Figure 16 ExStdEvent Hierarchy: PayloadSection

Table 16 Payload Section


RawData Lf; Opt; Sgl; string

The raw message carrying the protocol-specific business information. Not interpreted by core eXchange.

Reference Lf; Opt; Sgl; string

For referencing the location of protocol-specific payload data not passed by value.Reserved for future use.

RuntimeConfiguration Gr; Req; Sgl This area mirrors the DeliveryProtocol and BusinessProtocol nodes of the Configuration section (see Table 12 on page 35), allowing protocols to supply or override values at run time. Not interpreted by core eXchange.

PayloadExtAttributes Gr; Opt; Sgl OTD attributes set by the delivery protocol and used by the delivery channel (example: headers of an HTTP post). Reserved for future use.

Envelopes Gr; Opt; Sgl Envelopes only, without any data/payload. Reserved for future use.



3.2.8 ExStdEvent ErrorSectionThe ExStdEvent Error section is optional. It contains three optional groupnodes: ExException is single; Causes and BusinessErrors are both repeating. See Figure 17.

Figure 17 ExStdEvent Hierarchy: ErrorSection

The Error section holds exception information according to the following hierarchy:

Under the ExException node, ExceptionDetails holds exception information provided by the uppermost BP (with text such as “Error occurred in <BPname>”). For details, see Table 17.

The Causes node is populated if the BP invokes a sub-BP (which may invoke a sub-sub-BP, and so forth); under the Causes node, ExceptionDetails holds exception

UserData Gr; Opt; Rep Scratchpad area for use by protocols, and not interpreted by core eXchange.

The UsageID leafnode holds a static GUID (must be unique across all applications) for the user/application that owns the data).The Data groupnode holds a name/value pair, similar to a TAD, BAD, or EAD, where the name is human-readable and the value is an XML string (that is, marshaled data) that codes extended attribute information.


Table 16 Payload Section (Continued)




information provided by successively lower BPs in the invocation chain, and so the lowestmost is likely to be most informative (with text such as “Input not found”). Each BP provides details as shown in Table 17.

The BusinessErrors node contains exception information specific to the business context, such as “Invalid character found in claim number” or “Required address data was not provided”; this is not interpreted by core eXchange.

The ExceptionDetails groupnode for ExException and Causes is described in Table 17.

Table 17 Error Section: exstd:ExceptionDetailsType


ErrorCode Lf; Req; Sgl; string

Error code provided programmatically by the BP.

ErrorDescription Lf; Req; Sgl; string

Human-readable error-message text provided by the BP.

ErrorSeverity Lf; Opt; Sgl; string

Level of error: INFO, WARN, ERROR, and so forth.

BPContext Gr; Opt; Sgl Information from the BP reporting the error:TimeStamp—The date and time when the BP caught the exception.BPInstanceID—Instance ID of the BP.BPName—Name of the BP.ScopeName—Name of the scope within the BP (or “global” if no scope).ActivityName—Name of the activity where the exception occurred.

WebServiceError Gr; Opt; Sgl Information about the WS reporting the error:ServiceCategory—Identifies the category of WS that failed. Examples: Collaboration definition; external WS; OTD unmarshal.Name—Name of the service that failed.Type—For a Java exception, the exception class; for faults, the fault type.Message—Text describing the error.StackTrace—Java stack trace, if available.Location—OTD location, if available.

OTDParsingErrors Gr; Opt; Sgl Contains two optional leaf nodes:OTDIdentifier—Name of the OTD.ParsingErrorsXML—If an error occurs, this node contains error information marshaled ino an XML string that holds an internal description of the error in one of two formats: either the format provided by the OTD validation or the message body of a negative ACK (in EDIFACT, for example, the UCI segments of a CONTRL message).



Chapter 3 Section 3.3eXchange Architecture and Components eXchange Services

When eXchange receives an event the following scenarios are possible:

The message cannot be processed because it cannot even be unmarshaled. In this case, the event is written to the EX_DEADLETTER topic.

Message processing begins, but the trading partner specified in the message is the one specified in the trading partner profile. In this case, the message is suspect; it is not allowed to be processed, and the event is written to the EX_ERROR topic.

Processing of the message starts, but an error is encountered. The event is written to the EX_ERROR topic.

eXchange and the business protocol manager write error information to the ErrorSection of ExStdEvent and publish ExStdEvent to the appropriate topic. An error selector BP routes the error to the error handling routine specified in the error handler BP specified by the end user (when configuration is done in ePM).

Each error section in ExStdEvent has specific meaning:

eXException\ExceptionDetails contains the details of the error that occurred.

eXException\ExceptionDetails\BPContext provides the details of the error that occurred while processing within the BP.

eXException\ExceptionDetails\WebServiceError provides the details of the error that occurred while the BP was invoking a service such as a Java Collaboration.

eXException\ExceptionDetails\OTDParsingErrors provides the details of the error that occurred while processing an OTD.

eXchange makes subprocess invocations of other core eXchange and protocol-specific BPs which, in turn, can make their own sub-process invocations. Error handling within eXchange has been built so that any error that occurs within a subprocess invocation is bubbled up to the original invoking business process, as follows:

The original error information is written to the ExException\ExceptionDetails section of ErrorSectio. The subprocess instance is terminated.

When the invoking BP receives the fault, it writes ExException details to the Causes section and write its own error information to the ExException\ExceptionDetails section of ErrorSection. The subprocess instance is terminated.

This continues until the original invoking process receives the fault and terminates the BP instance after writing ExStdEvent to the Error topic.

3.3 eXchange ServicesThis section provides information on the services provided by core eXchange, located in SeeBeyond > eXchange > Core Services.

Naming convention for eXchange core services

Services provided by core eXchange have the form eX<AbcXyz>Service, where the <AbcXyz> string provides an indication of the processing performed by the service.



3.3.1 OvervieweXchange core services fall into five categories:

Common services—Services specific to ExStdEvent (such as reading and tracking), as well as selector/handlers for error-handling and compression/decompression. See “Services Provided by eXCommonService” on page 42.

Business protocol services—Selectors and handlers specific to business protocols (like X12 and EDIFACT). See “Services Provided by eXBusinessProtocolService” on page 45.

Delivery protocol services—Selectors and handlers specific to delivery protocols (like AS2 and ebXML). See “Services Provided by eXDeliveryProtocolService” on page 46.

Delivery channel services—Selector and handler for message transport (via FTP or HTTP, for example).

Crypto services—Selectors and handlers for private-key operations (decryption and signing) and public-key operations (encryption and signature-validation).

3.3.2 Services Provided by eXCommonServiceThe eXCommonService folder (under SeeBeyond > eXchange > Components) contains the following:

ErrorHandler—Allows for invocation from the Error Selector. This operation allows users to create their own error-handling routine.

CompressionHandler—Allows for invocation from appropriate compression selectors. This operation allows users to create their own message compression routine.

DecompressionHandler—Allows for invocation from appropriate decompression selectors. This operation allows users to create their own message decompression routine.

getExStdEvent—Gets and returns ExStdEvent.

getExStdEventByExtAttrs—Retrieves ExStdEvent using extended attributes (name/value pairs).

getExStdEventByExtAttrsAndSvcAndAction—Retrieves ExStdEvent using a combination of Dialog Group Name, Action (Transaction Profile) and extended attributes (name/value pairs) specific to the protocol.

getExStdEventByGroup—Uses the Dialog Group Name to get and return ExStdEvent.

getExStdEventByProtocolExtAttrs—Retrieves ExStdEvent using extended attributes (name/value pairs) along with protocol name and protocol type.

trackExStdEvent—Records ExStdEvent in the message tracking database. Used to persist information that will be used to perform message resends.

lookupExStdEventAsBytes—



Retry Service

The Retry Service is provided by eXchange to enable reliable messaging at the transport layer. For example, communication over a transport might fail for various reasons—the trading partner's server is down, or there is a network failure, and so forth. In such circumstances, the protocol message is not delivered to the trading partner on the first try, an exception is thrown, and the retry service is initiated so as to re-attempt delivery.

The primary inputs required for Retries are shown below.

When a Retry is registered and started, the underlying service schedules the requested message for the given interval. At the end of the interval, the message is posted to EX_TODELIVERY topic. The subscriber to this topic is the DeliveryChannel service that executes the underlying transport to Trading partner. In order to support retries, this DeliveryChannel service,, must invoke the Retry API as part of its logic. Please refer to the example below on how the API can be invoked.

If the service completes execution of all retries and is still unsuccessful, the default behavior is to post the message to EX_ERROR topic. It also records the status along with error details in the Database. You can refer to CA_RETRY table in the Database for the current status for a list of all messages that are being retried.

Table 18 Primary Inputs Required by Retry Service

Input Type Description

MaximumRetryCount int Maximum number of times a retry must be executed to send the message to Trading Partner successfully. The count excludes the first post that results in an exception and thus initiates the retries. For example, if MaxRetryCount = 3, the total number of attempts to post the message to TP would be 4, consisting of the failed first attempt and the three retries.

RetryInterval long Duration between successive retries. The sequence is thus as follows: first attempted post fails; initialize retry phase; wait for RetryInterval; retry (that is, try again to post the message to TP; wait for RetryInterval; and so forth.

Message Content eXStdEvent Must be the entire ExStdEvent— in other words, not just the B2B protocol message.

Retry ID Unique ID to identify a specific retry request. This could be the ID in the message provided that it is unique across all Trading Partners.



Example of Retry Service in AS2

This section provides an example showing how the AS2 protocol uses the Retry Service. Custom usage would be identical to most of the following except for a few changes that depend on the transport protocol you are using.

1 AS2, as part of its Extended Attributes Definition, adds two new properties: RetryInterval and MaxRetryCount. (Outbound only; that is, direction=ToPartner.) These properties go along with other properties defined for AS2 when the AS2 protocol is deployed along with the Host created in Enterprise Designer.

2 In ePM, these properties show up in the Outbound Transaction Profile under the Batch section (because the properties are defined under the Batch Extended Attributes).

3 Configure the required values for both the properties.

4 In the BPEL implementation of the eXchange service - eXDeliveryChannelService (for AS2, this is bpEX_HttpDeliveryChannel_AS2.bpel), a Java Collaboration is used for HTTP post. The method signature for the JCD would be as follows:

public void execute( exStdEvent.ExStdEvent_ input, exStdEvent.ExStdEvent_ output, com.stc.connector.appconn.http.HTTPPlientApplication HTTPClient_1 )

5 Within the method, the logic would be as followstry {

// .... logic as required before posting the message over HTTP ....HTTPClient_1.post();httpRespCode = HTTPClient_1.getResult().getResponseCode();

// Check response codeif (httpRespCode < 200 || httpRespCode > 299) {

throw new HTTPApplicationException( "Failed to post message to the trading partner: " + url );

} else {// .... logic as required when post is successful ....// Close Retry Service// Retrieve the unique ID used when registering Retries. // This ID is used to identify which Retry should be closed. // In this case it is AS2 message ID.String retryId = input.getContainer(

0 ).getKeysSection().getExternalIDs().getDeliveryBatchExternalID();

// Close the Retry svc// Check if another retry is requiredRetryRequest retryReq = getRetryRequest( input );-// Client-side validation: Check if Retry is configuredif (retryReq.getMaxRetryCount() > 0 && retryReq.getRetryInterval() > 0) {

RetryServiceAdapter retryServ = new RetryServiceAdapter();retryServ.closeRetry( retryId );

}}

} catch ( HTTPApplicationException he ) {String httpMsg = he.getMessage();String msg = "Failed to post to " + url + "; HTTP errors " + httpMsg;

// Create the Retry svc objectsRetryServiceAdapter retryServ = new RetryServiceAdapter();

// Use a utility method to create the Input bean to invoke Retry svc.RetryRequest retryReq = getRetryRequest( input );// Client-side validation: Check if Retry is configured.if (retryReq.getMaxRetryCount() > 0 && retryReq.getRetryInterval() > 0) {

if (httpRespCode == 0) {httpRespCode = 601;

}

// Set error details.retryReq.setCauseCode( Integer.toString( httpRespCode ) );if (httpMsg.length() > 3900) {

httpMsg = he.getCause().getMessage();retryReq.setCauseDescription( httpMsg.substring(0, 3900) );

}retryReq.setCauseDescription( httpMsg );

// Register and start the RetryretryServ.retry( retryReq );



// Throw exception to stop the BP from processing the further steps.throw new HTTPApplicationException( "Retry Service Invoked." );

}throw he;

}

// Utility method to create Retry svc input beanprivate RetryRequest getRetryRequest( exStdEvent.ExStdEvent_ input ) throws Throwable {

// Create the beanRetryRequest retryReq = new RetryRequestImpl();

// Retrieve Retry ID from ExStdEventString retryId = input.getContainer( 0

).getKeysSection().getExternalIDs().getDeliveryBatchExternalID();

// Retrieve the Extended Attr XML that contains Retry configuration // i.e., MaxRetryCount and RetryIntervalString extAttrXML = input.getContainer( 0

).getConfigurationSection().getDeliveryProtocol_().getToPartner().getCommon().getBatchExtAttributes().getExtAttributeValueXML();

//process the XML content and retrieve the 2 properties.int retryLimit = 0;long retryInterval = 0;if (extAttrXML != null || extAttrXML.length() > 0) {

XMLUtil extAttr = new XMLUtil( extAttrXML );try {

retryLimit = Integer.parseInt( extAttr.getElementValue( "OutboundProfile", "MaxRetryCount" ) );

retryInterval = Long.parseLong( extAttr.getElementValue("OutboundProfile", "RetryTimeOut" ) );

} catch ( NumberFormatException ne ) {retryLimit = 0;retryInterval = 0;

}}

retryReq.setRetryId( retryId ); //Retry IDretryReq.setMaxRetryCount( retryLimit ); //Maximum number of retriesretryReq.setRetryInterval( retryInterval ); //retry intervalretryReq.setMaxRetryDuration( 0 ); //this is currently not supported.

// Register the Callback handler that is invoked when Retry time triggers. // The default implementation posts to the EX_TODELIVERY topic.retryReq.setRetryEventListner(

"com.sun.compapps.services.reliablemsg.retry.actions.jms.RetryMessageActionImpl" );

// Register Callback handler to be invoked when all the Retry attempts are exhausted.// The default implementation provided by the below class, posts the ExStdEvent // to EX_ERROR topic.retryReq.setRetryExhaustionEventListner(

"com.sun.compapps.services.reliablemsg.retry.actions.jms.ExExhaustActionImpl" );

// Set the ExStdEvent.retryReq.setMessageContent( input.marshalToBytes() );return retryReq;

}

6 After making the changes noted above, be sure to deploy the project.

3.3.3 Services Provided by eXBusinessProtocolServiceThe eXBusinessProtocolService folder (under SeeBeyond > eXchange > Core Components) contains the following:

trackBusinessBatch—Records the business outer envelope information to the message tracking database. In X12, for example, this would be ISA-level information.

updateBusinessBatchSendCount—Used to update the message tracking resend count in the message tracking database.

trackBusinessGroup—Records the business inner envelope information to the message tracking database In X12, for example, this would be GS-level information.

trackBusinessTransaction—Records the business payload information to the message tracking database In X12, for example, this would be ST-level information.



lookupBatchDetails—

trackBusinessError—Enables the ability to add any business error to the Error tab of the message tracker.

trackBusinessBatchAck—Records the interchange acknowledgment to the message tracking database In EDIFACT, for example, this would be the CONTRL.

CustomExternalUniqueIDHandler—Allows the user to build and invoke a custom unique id validation.

BusinessProtocolValidationHandler—The main driver that performs the business message validation. Contains a selector for the syntax validation and the custom validation.

BusinessMessageSyntaxValidationHandler—Performs the OTD (structural) validation of the business protocol.

BusinessTransactionTypeHandler—Used to designate whether the message is a batch, request, reply, or acknowledgment message.

CustomBusinessProtocolValidationHandler—Performs validation specific to the trading partner.

BusinessAckGeneratorHandler—Used during inbound processing to perform the necessary business acknowledgment creation. Not used in X12.

BusinessAckProcessorHandler—Used during inbound processing to perform the necessary business acknowledgment reconciliation. Not used in X12.

BatchSplitterHandler—Performs batch splitting.

BatchHandler—Performs document batching.

CustomBusinessTranslationHandler—Performs translation that is specific to the trading partner.

3.3.4 Services Provided by eXDeliveryProtocolServiceThe eXDeliveryProtocolService folder (under SeeBeyond > eXchange > Core Components) contains the following:

DeliveryProtocolValidationHandler—The main driver that processes the inbound Delivery Protocol message that has already been wrapped in an ExStdEvent.

DeliveryMessageSyntaxValidationHandler—Validates the syntax of the Delivery Protocol message. This includes validation of dependencies across various fields in the message that are not validated by a structural validation.

CustomDeliveryProtocolValidationHandler—Externalized plug-in for user to add additional validation that may be required on the Delivery Protocol message.

DeliveryProtocolBatchHandler—Constructs the outgoing Delivery Protocol message.


Chapter 3 Section 3.4eXchange Architecture and Components Default eXchange BPs

3.4 Default eXchange BPsThis section provides detailed information on the B2B protocol processes (BPs) used by core eXchange and protocol manager composite applications.

Naming convention for eXchange core BPs

BPs provided by core eXchange have the form bpEX_<AbcXyz>, where the <AbcXyz> string provides an indication of the processing performed by the BP.

3.4.1 OverviewWhen a BP unmarshals an ExStdEvent message from a topic, the message is consumed. Depending on the nature of the processing (which may depend on values contained in the TP profile), the message may undergo modification. When the BP and all the BPs it invokes have accomplished their processing, the ExStdEvent is reconstituted and the marshaled message is handed off to one or more topics. See Figure 18.

Figure 18 BPs Used in Outbound and Inbound Message Processing

The BPs used in core eXchange and protocol manager composite applications are all named bpEX_<AbcXyz>, where the <AbcXyz> string provides an indication of the processing performed by the BP. In some cases, the core BP has a corresponding Java Collaboration Definition (JCD) named jcdEX_<AbcXyz>.

3.4.2 Core and Protocol BPs (bpEX_*)(core) bpEX_Batcher on page 48(protocol) bpEX_Batcher_<protocol> on page 53(core) bpEX_BatcherDriver on page 48(protocol) bpEX_BusinessAckProcessor_<protocol> on page 53



(protocol) bpEX_BusinessTransactionType_<protocol> on page 53(protocol) bpEX_BusinessValidation_<protocol> on page 54(user) bpEX_DeliveryChannel_<transport> on page 54(core) bpEX_DeliveryHandler on page 49(core) bpEX_DialogFromTP on page 49(core) bpEX_DialogToTP on page 49(core) bpEX_DupCheckAndMessageTracker on page 49(core) bpEX_ErrorHandlerSelector on page 50(user) bpEX_ExternalUniqueID_<protocol>_<code> on page 55(core) bpEX_HostInitiatedDialog on page 50(user) bpEX_JMSErrorHandler on page 54(core) bpEX_MainFromInternal on page 50(core) bpEX_MainFromTP on page 51(core) bpEX_MessageToTP on page 51(core) bpEX_MessageToTP_Correlation on page 51(protocol) bpEX_Report_EX_ERROR_<protocol> on page 54(core) bpEX_TimerInterruptBP on page 52(core) bpEX_TPInitiated_Dialog on page 52(core) bpEX_TrackBatchBP on page 52

Core BPs: SeeBeyond > eXchange > Core Components > BPs

bpEX_Batcher

Located in SeeBeyond > eXchange > Core Components > BPs, this B2B protocol process supplies the following activities:

batch—interrupt—marshal—send—BusinessProtocolBatchSelector—trackBatchAndGroup—trackBusinessBatchAck—trackBusinessTransaction—

bpEX_BatcherDriver


unmarshal—write—batch—



bpEX_DeliveryHandler


unmarshal—DeliveryChannelSelector—ErrorSelector—

bpEX_DialogFromTP


unmarshal—receiveAcknowledgment—receiveResponse—

bpEX_DialogToTP


unmarshal—receiveAcknowledgment—receiveResponse—receiveRequest—

bpEX_DupCheckAndDeliveryTracker


trackPackage—track—

This BP is also provided as a JCD: jcdEX_DupCheckAndDeliveryTracker. Also available is jcdEX_DeliveryPkgAssoc to associate two delivery messages.

bpEX_DupCheckAndMessageTracker


trackDialogOp—trackDialogue—trackDialogueAction—

This BP is also provided as a JCD: jcdEX_DupCheckAndMessageTracker.



bpEX_ErrorHandlerSelector


receive—unmarshal—send—ErrorSelector—

bpEX_HostInitiatedDialog


receiveRequest—receiveAcknowledgment—receiveResponse—

bpEX_MainFromInternal


receive—unmarshal—CustomBusinessTranslationSelector—BusinessProtocolValidationSelector—trackDialogOp—marshal—send—trackBusinessTransaction—trackBusinessError—



bpEX_MainFromTP


receive—unmarshal—DeliveryProtocolValidationSelector—trackPackage—BusinessTransactionTypeSelector—BusinessProtocolValidationSelector—trackDialogOp—CustomBusinessTranslationSelector—marshal—send—BusinessAckProcessorSelector—BusinessProtocolBatchSplitterSelector—

bpEX_MessageToTP


receive—unmarshal—DeliveryProtocolEnveloperSelector—correlateBatchAck—marshal—send—correlateBatch—

bpEX_MessageToTP_Correlation


correlateBatch—correlateBatchAck—convertMinutesToDuration—updateBusinessBatchSendCount—marshal—send—



bpEX_TimerInterruptBP


receive—unmarshal—getNextFireTime—interrupt—marshal—send—

bpEX_TPInitiated_Dialog


receiveAcknowledgment—receiveResponse—convertMinutesToDuration—marshal—send—

bpEX_TrackBatchBP


trackBatchAndGroup—trackBusinessBatch—trackBusinessBatchAck—trackBusinessGroup—

Protocol BPs: SeeBeyond > eXchange > Protocol Managers > BPs



bpEX_Batcher_<protocol>

Located in SeeBeyond > eXchange > Protocol Managers > BPs, this B2B protocol process supplies the following activities:

BatchHandler—execute—BusinessProtocolBatchSigningSelector—BusinessProtocolBatchEncryptionSelector—trackBatchAndGroup—trackBusinessBatchAck—trackBusinessTransaction—trackBusinessError—

bpEX_BusinessAckProcessor_<protocol>


BusinessAckProcessorHandler—marshal—send—trackBusinessBatchAck—execute—lookupBatchDetails—trackBusinessError—

bpEX_BusinessTransactionType_<protocol>


BusinessTransactionTypeHandler—execute—marshal—trackBusinessBatch—send—



bpEX_BusinessValidation_<protocol>


BusinessProtocolValidationHandler—execute—execute—BusinessMessageSyntaxValidationSelector—CustomBusinessProtocolValidationSelector—

bpEX_Report_EX_DEADLETTER_<protocol>


sendToDeadLetterQueue—marshal—send—

bpEX_Report_EX_ERROR_<protocol>


sendToErrorQueue—marshal—send—

User BPs: SeeBeyond > User Components

bpEX_JMSErrorHandler

Located in SeeBeyond > User Components > Common > Error > BPs, this B2B protocol process supplies the following activities:

ErrorHandler—marshal—send—

bpEX_DeliveryChannel_<transport>

Each of the following transport methods has its own B2B protocol process: File, FTP, HTTP, JMS, and SMTP.

Located in SeeBeyond > User Components > Delivery Channel > <transport>, each B2B protocol process supplies the following activities:


Chapter 3 Section 3.5eXchange Architecture and Components Default eXchange JMS Topics

DeliveryChannelHandler—unmarshal—put—

bpEX_ExternalUniqueID_<protocol>_<code>

Located in SeeBeyond > User Components > ExternalIDs > <protocol> > BPs, each B2B protocol process supplies the following activities:

3.5 Default eXchange JMS TopicsThis section provides detailed information on eXchange’s standard JMS topics (named “EX_<XYZ>”). The purpose of these JMS topics is to persist objects of type ExStdEvent as they undergo processing by the various BPs.

3.5.1 Summary of JMS TopicsEach topic holds outbound messages, inbound messages, or error information. Some BPs can write messages to outbound and inbound topics; this is true, for example, of a BP that processes acknowledgments or checks for duplicates via a request/response mechanism.

Eventually, many queues will have both asynchronous and synchronous versions; however, at this time, no topics named EX_<...>SYNCH are supported.

The JMS topics used in core eXchange and protocol manager composite applications are all named EX_<XYZ>, where the <XYZ> string provides a brief indication of the topic’s purpose, origination, or destination.

(out): EX_BATCH_MSG_RECVR and EX_BATCHER on page 56(error): EX_DEADLETTER on page 56(out): EX_TODELIVERY and EX_TODELIVERYSYNCH on page 56(in): EX_DIALOGFROMTP on page 56(out): EX_DIALOGTOTP on page 56(error): EX_ERROR on page 57(out): EX_FROMINTERNAL and EX_FROMINTERNALSYNCH on page 56(in): EX_FROMTP and EX_FROMTPSYNCH on page 56(out): EX_MESSAGETOTP on page 56(out): EX_TODELIVERY and EX_TODELIVERYSYNCH on page 56(in): EX_TOINTERNAL on page 56



3.5.2 Outbound TopicsEX_BATCH_MSG_RECVR and EX_BATCHER

The EX_BATCHER topic receives messages from bpEX_MainFromInternal and bpEX_BatchSplitter_<protocol>, and provides them to bpEX_BatcherDriver.

EX_DELIVERYBATCH_MSG_RCVR and EX_DELIVERYBATCHER

The EX_DELIVERYBATCHER topic receives messages from bpEX_MainFromInternal and bpEX_BatcherDriver, and provides them to bpEX_DeliveryBatcher.

EX_DIALOGTOTP

The EX_DIALOGTOTP topic receives messages from bpEX_MainFromInternal and bpEX_BusinessAckProcessor_<protocol>, and provides them to bpEX_DialogToTP.

EX_FROMINTERNAL and EX_FROMINTERNALSYNCH

The EX_FROMINTERNAL topic receives messages from inbound eGate and provides them to bpEX_MainFromInternal.

EX_MESSAGETOTP

The EX_MESSAGETOTP topic receives messages from bpEX_MainFromTP, bpEX_BatcherDriver, bpEX_DeliveryBatcher, and bpEX_BatchSplitter_<protocol> , and also from bpEX_MessageToTP* if re-sent after a timeout, and provides them to bpEX_MessageToTP or bpEX_MessageToTP_Correlation.

EX_TODELIVERY and EX_TODELIVERYSYNCH

The EX_DELIVERY topic receives messages from bpEX_MessageToTP or bpEX_MessageToTP_Correlation and provides them to bpEX_DeliveryHandler.

3.5.3 Inbound TopicsEX_DIALOGFROMTP

The EX_DIALOGFROMTP topic receives messages from bpEX_MainFromInternal and bpEX_BusinessAckProcessor_<protocol>, and provides them to bpEX_DialogFromTP.

EX_FROMTP and EX_FROMTPSYNCH

The EX_FROMTP topic receives messages inbound from external Channel Manager and provides them to bpEX_MainFromTP.

EX_TOINTERNAL

The EX_TOINTERNAL topic receives messages from bpEX_BatchSplitter_<protocol> and provides them to outbound eGate.

3.5.4 Error TopicsEX_DEADLETTER

The EX_DEADLETTER topic receives messages from bpEX_ErrorHandlerSelector in the event that the message cannot be parsed by the ExStdEvent OTD.



EX_ERROR

The EX_ERROR topic receives messages from any BP that throws them and provides them to bpEX_ErrorHandlerSelector.


Chapter 4

Custom Protocols

This chapter provides some hands-on guidance to creating custom protocols.


Custom Protocol Concepts on page 58

Creating Handlers for Custom Protocols on page 62

4.1 Custom Protocol ConceptseXchange provides a collection of custom-tailored Business Processes (BPs), Java Collaboration Definitions (JCDs), and Object Type Definitions (OTDs). Each B2B Host contains Business Protocol Attribute Definitions (BPADs, consisting of BADs and EADs), Delivery Protocol Attribute Definitions (DPADs, consisting of MADs and PADs), and Transports, associated with a Transport Attribute Definition (TAD).

When eXchange is installed, folders shown in Figure 19 appear in the project tree:

Figure 19 eXchange System Folders

The basic concept is that the eXchange Core provides the controllers for the flow of data through eXchange for documents that are either from a trading partner that will go to an internal system or from internal systems to a trading partner. These are primarily made up of business process flows called B2B Protocols.

Several BPs are supplied that control this flow; each of them call out to custom BPs that are specific to a particular B2B Protocol ( X12, HIPAA, RosettaNet, and so forth).


Chapter 4 Section 4.1Custom Protocols Custom Protocol Concepts

Customization for a specific protocol is accomplished by the concept of “Selectors” and “Handlers”.

eXchange also has the ePM GUI which stores Trading Partner information in LDAP and Message Tracker for the tracking of messages flowing through the system, this data is stored in a database. For each trading partner, you can configure core elements that always exist, extended attributes that were created in your B2B Host for a protocol, and you can choose which Handlers you wish to use for that trading partner from pull-down lists.

The controller for all of these selectors and handlers is an eXchange Service; this service is created by building your B2B Host. When a B2B Host is built, an eXchangeService is created in the Java CAPS environment and in the Partner Manager LDAP instance.

4.1.1 Creating a Generic Business ProtocolIn this section, you create and build a B2B Host with a business protocol named UBL that contains an attributed called internalKey. This variable will be used the store a unique identifier that can be used to look up a tradining partner that is part of a message; typically, this might be a “Bill To” ID, a DUNS number, or similar unique ID.

1 In Enterprise Designer, in your project, create a generic BPAD named UBL that contains an attributes definition named internalKey.

2 In the same project, create a B2B Host and drag the “UBL” business protocol into it. Also drag in any delivery protocols and transports you may need. (Transport Attribute Definitions are found under Sun > SeeBeyond > eXchange > Transport Attribute Definitions.)

3 Create a Connectivity Map, connect your B2B Host to LDAP and Oracle externals, create a Deployment Profile and build the host, creating an eXchangeService. This eXchangeService is the controller of all of the handlers and selectors.

4.1.2 Setting Up Handlers for SelectorsThis section focuses on the Connectivity Map where you connect the eXchange Service to the handlers.

The Connectivity Map in Figure 20 below shows an eXchangeService mapped to several handlers; some of those handlers also require mapping to JCDs that were used in the BP, JMS Topics, and possibly other externals.



Figure 20 eXchangeService Mapped to Handlers

When mapping, you do not need to double-click the eXchangeService to open it and then connect items from inside it (as you would normally do in eGate); instead, you simply connect to the input or output arrows on the eXchangeService.

When you double-click a B2B Protocol Handler in your Map, you will see either inboundeXchangeService or outboundeXchangeService. Inbound eXchange Services are mapped to the right side of the eXchangeService and outbound to the left side of the eXchangeService.

Another option is to place two eXchangeService on yourMap, one labeled for inbound and one for outbound. This sometimes makes the Map a little easier to view with less crossing lines as shown below in Figure 21:



Figure 21 Separate Inbound and Outbound eXchangeServices Mapped to Handlers

1 After you have an eXchangeService, you need to build and deploy your custom Handlers located in the eXchange > Deployment folder using the techniques discussed above. In the Connectivity Map, simply connect the eXchangeService to each handler (see Figure 20 and Figure 21 above), map any externals your handler BP requires,

2 Create a deployment profile and build it, and then deploy the .ear file to your Logical Host. This action registers all handlers with ePM so that they will become options for the appropriate selectors, as shown in Figure 22 below.


Chapter 4 Section 4.2Custom Protocols Creating Handlers for Custom Protocols

Figure 22 Handler BPs Displayed in an ePM Pull-Down List

As can be seen in Figure 22 above, the handlers that have been deployed show up in the appropriate pull-down list for the selector in the ePM GUI.

In a later section of this document you will see how to build a Handler. Each Handler is specific to a Selector: In Figure 22 above, you see configuration items such as Business Protocol Validation Handler.

In an eXchange Message Flow, a series of selectors are called. Each of these selectors can be thought of as the configuration points in Figure 22; the pull-down box list shows the handlers for that type of selector. When you build a custom handler and deploy it, it will show up in the drop down list. If the handler is configured to be used for a specific transaction for a trading partner, then when the message comes to that selector, it will choose the handler that is configured.

4.2 Creating Handlers for Custom ProtocolsThis section describes the handlers that need to be created for a custom protocol.

4.2.1 Inbound = FromTPThe following handlers can be created for the Inbound From Trading Partner flow. Some of these will be called from prebuilt core exchange business processes; some will be called from handlers that are custom=created. (To call a handler from another handler, the appropriate selector is dragged onto the canvas of the custom handler.)

bpEX_MAINFromTP (Core)



Delivery Protocol Validation Handlers (Custom)

Business Protocol Transaction Type Handler (Custom)

Batch Splitter Handler (UnBatcher) (Custom)

Business Ack Processor Handler

Business Protocol Validation Handler

Custom Business Translation Handler

External Unique ID Handler

The Batch Splitter Handler will call the following selectors so that the handlers listed above will get used:

Business Protocol Validation Selector

Custom Business Translation Selector

Business Ack Processor Selector

For example, see Figure 23.

Figure 23 BP Showing Handler Logic

Flow for Inbound = FromTP

Figure 24 below is an operational diagram of the inbound flow; Figure 25 provides another view in UML.



Figure 24 Flow Inbound (FromTP) - Operational View

Figure 25 Flow Inbound (FromTP) - UML View



A selector is a prebuilt core eXchange object with a predefined interface that allows custom handlers to be created. When a handler is created and deployed, it is available for use. For example: The “OTD Validation Selector” checks the LDAP configuration for a particular message and determine which handler it should call. When you build a handler and deploy it in the eXchange project, it then shows up in the pull-down list as an option for that particular selector.

To create a new handler

1 Right-click the project, point at New, and select B2B Protocol. This summons the eInsight Business Process editor with an empty canvas.

2 Drag the appropriate interface onto the canvas. The interface is a prebuilt receive/reply OTD BPEL activity that has been installed as part of the eXchange installation. These are found in the Sun SeeBeyond > eXchange > Core Services folder:



Figure 26 Core Services (in the Sun SeeBeyond > eXchange Folder)

3 In this folder are a collection of Selectors and Handlers; Selectors typically are represented by a plain yellow box and Handlers are typically represented by a yellow box with an envelope. Choose the appropriate Handler and drag it onto the eInsight canvas, creating a Receive and a Reply activity:



Figure 27 Handler, After Being Dragged Onto the eInsight Canvas

4 Typically, you now place your business logic between the receive and reply activities. This could be a single rule or a complex set of BPEL commands to process the data, which may also include JCDs for complex processing.

Figure 28 Handler With Business Rules and Connections


Glossary of Acronyms

Glossary


AS2Applicability Statement 2 (AS2) is an Internet Draft security standard defined by the IETF (Internet Engineering Task Force), designed to allow business transactions to move securely over the Internet.

BADIn eXchange, Business Attribute Definitions (BADs) define the metadata attributes of parameters used in business protocols such as X12, HIPAA, or EDIFACT.

B2BBusiness-to-business (B2B) interactions are those that occur between business partners in the context of e-commerce.

DCPIn eXchange, a Delivery Channel Profile (DCP) is an association between a particular messaging service and a particular transport attributes definition (TAD). Also see “IDC” and “XDC”.

EADIn eXchange, Enveloping Attribute Definitions (EADs) define the metadata attributes of parameters used in enveloping protocols such as X12, HIPAA, or EDIFACT.

ebXMLA well-recognized e-business XML (extensible markup language; see “XML”) whose implementation includes specifications for messaging, collaboration profiles, business processes, and metadata registry.

ePMeXchange Partner Manager (ePM) is a Web-based GUI for defining and managing Trading Partner (TP) information.

FTPFile Transport Protocol (FTP) is a transport protocol for sending and receiving files. Specifications for FTP include RFCs 959, 1635, 2228, and 2577.

HTTPHypertext Transport Protocol (HTTP) is a transport protocol for transmitting information referenced in a URL of the form http://<hostname>:<port>/.../.... Specifications for HTTP include RFCs 2068, 2616, 2617, 2660, and 3310.



ICANSeeBeyond’s Integrated Composite Application Network (ICAN) Suite includes eGate Integrator, eXchange Integrator, various eWay Intelligent Adapters, OTD Libraries, and Protocol Manager Composite Applications, as well as many other products.

IDCIn eXchange, an Internal Delivery Channel (IDC) is an association between a particular transport attributes definition (TAD) and a direction (either Sender or Receiver). Compare with “XDC”.

MADIn eXchange, Messaging Attribute Definitions (MADs) define the metadata attributes of parameters used in messaging protocols such as AS2 or ebXML.

MIMEMultipurpose Internet Mail Extensions (MIME) extends the format of basic Internet mail to allow non-textual messages, multipart message bodies, and so forth. Specifications for MIME include RFCs 2045–2049.

OTDIn ICAN, an Object Type Definition (OTD) contains the data structure and rules that define an object. OTDs are used in Java collaborations to transform data interface with external systems.

SMEIn ICAN, Secure Messaging Exchange (SME) uses advanced cryptographic techniques to ensure security, verifiability, and nonrepudiation of messages exchanged electronically.

S/MIMESecure/Multipurpose Internet Mail Extensions (S/MIME) provides a consistent way to send and receive secure MIME data, using digital signatures for authentication, message integrity and non-repudiation and encryption for privacy and data security. Specifications for S/MIME version 2 include RFCs 2311–2315.

SMTPSimple Mail Transfer Protocol (SMTP) is a transport protocol for transmitting e-mail messages between servers or from client to server. Specifications for SMTP include RFCs 1651, 2821, and 3461.

TADIn eXchange, Transport Attribute Definitions (TADs) define the metadata attributes of parameters used in transport protocols such as FTP or HTTP.

TP, TPPIn eXchange, a Trading Partner (TP) has one or more Trading Partner Profiles (TPPs) that contain information identifying the values of messaging, enveloping, and/or transport parameters to be used for sending and receiving B2B information.



URLA Uniform Resource Locator (URL) is a string that identifies information, such as a particular piece of information shared by a particular host.

XDCIn eXchange, an External Delivery Channel (XDC) is an association between three items: (1) either a messaging service (passthrough) or a business service (dialog); (2) a transport attributes definition (TAD) for the ToPartner (Sender) direction; and (3) a TAD for the FromPartner (Receiver) direction.

XMLAn Extensible Markup Language (XML) is a language whose syntax obeys an official schema, called “the XML schema”, but whose semantics (“vocabulary”) are open.


Index

Index

Aacknowledgments

business 22architectural layers, described 15architecture, illustrated 14

BB2B protocol pipelines. See BPs.BADs

(defined) 11batching 20batch-splitting 21bindings

(defined) 14combined into a transaction profile 11

BPs(defined) 11categorized 13

business action groups(defined) 12

business attribute definitions. See BADs.business processes. See BPs.business protocols

(defined) 11

CCommon, block in Configuration section 35Configuration section of ExStdEvent 33conventions, text 9core services

Business Protocol 45common 42Delivery Protocol 46Retry 43

custom protocolsconcepts 58creating handlers for 62

Ddelivery action groups

(defined) 12

delivery channels(defined) 12

delivery protocols(defined) 12

EEADs

(defined) 11enveloping attribute definitions. See EADs.ePM 14error handling 22Error section of ExStdEvent 39eXBusinessProtocolService 45ExceptionDetails 40eXchange database 13eXchange Partner Manager. See ePM.eXchangeService

(defined) 13eXCommonService 42eXDeliveryProtocolService 46ExStdEvent 23–40

getting 42looking up 42tracking 42

ExStdEvent sections(illustrated) 24Configuration 33Error 39Keys 26Metadata 24Payload 38SelectableBPs 29

Hhandlers

creating 62error 22

handlers and selectorsas displayed in ePM 62Connectivity Map for 59

IIBPS, block in Selectable BPs 31inbound (from TP) flow

(illustrated) 17described 16

InvocableBPSignature, block in Selectable BPs 31


Index

JJava Collaboration Definitions (JCDs)

jcdEX_DeliveryPkgAssoc 49jcdEX_DupCheckAndDeliveryTracker 49jcdEX_DupCheckAndMessageTracker 49

JMS topicsbatching 20error 22, 56inbound 18, 56outbound 56

KKeys section of ExStdEvent 26

MMADs

(defined) 12message flow, inbound (from TP)


message flow, outbound (to TP)(illustrated) 16described 15

message tracking 13messaging attributes definitions. See MADS.Metadata section of ExStdEvent 24

OOracle, for eXchange database 13outbound (to TP) flow


Ppackaging attributes definitions. See PADS.PADs

(defined) 12Payload section of ExStdEvent 38

RRetry Service

(example) 44(explained) 43inputs for 43

Sscreenshots 9

SelectableBPs section of ExStdEvent 29selectors and handlers

as displayed in ePM 62Connectivity Map for 59

supporting documents 9

TTADs

(defined) 12text conventions 9topics

batching 20error 22, 56inbound 18, 56outbound 56

transaction profile(defined) 11

transport attributes definitions. See TADS.
