Chapter 3 eXchange Integrator Features

This chapter provides brief descriptions of components packaged with eXchange Integrator and the B2B Suite.

What’s in This Chapter

• Project Tree Organization

• Transport Attribute Definitions

• Channel Manager

• Message Tracker

• B2B Protocols for X12, HIPAA, EDIFACT, AS2, and ebXML

• Handling Errors

Project Tree Organization

Initial installation of eXchange Integrator populates the project tree with the following folders:

• eXchange ⇒ Deployment — a preconfigured project containing connectivity maps, containers for standard servers (BatchFTP, BatchLocalFile, ExConfigSvc, HTTP, and eXchangeService itself), and eXchange-specific JMS topics.

• Sun SeeBeyond ⇒ CompApps⇒ Core Services — contains JCDs and OTDs for batch services and reliable messaging, as well as associated SQL scripts and JAR files.

• Sun SeeBeyond ⇒eXchange — contains all of the other components used by eXchange Integrator, including: Channel Manager; core components (BPs, collaborations, OTDs, and the ePM application), core Web services (selectors and handlers), scripts for LDAP and Oracle, the message-tracker application, templates of the as-shipped versions of customizable components, transport attribute definitions, and additional “user” components for error handling and delivery channels.

Transport Attribute Definitions

Transport attribute definitions provide the metadata required at the transport layer. (In this context, “metadata” means the categories of information, not any actual values.) Once a transport attributes definition has been included in a B2B host, it is exposed to ePM so that specific values can be supplied for specific trading partner configurations.

The Sun SeeBeyond ⇒ eXchange ⇒ Transport Attribute Definitions foldercontains presupplied transport attribute definitions (TADs) and corresponding OTDs. See Figure 3–1. For more information, see Creating and Configuring TADs.

Figure 3–1 Sun SeeBeyond ⇒ eXchange⇒Transport Attribute Definitions Folder

Overview

Different transport protocols require different types of attributes; for example, HTTP requires little more than a URL, but FTP requires a username, password, hostname, port, path, and file pattern, and possibly other attributes as well. For this reason, the metadata for HTTP-based and FTP-based TADs are quite different. When a TAD is referenced by a delivery channel, its attributes govern the appearance and behavior of ePM for users who supply values for that channel.

At run time, a TAD’s metadata is made available to the application through the two methods of its associated OTD: unmarshal parses an inbound stream into an internal data structure, and marshal serializes the internal data into a linear outbound stream.

All TADs define their metadata using the format shown in Table 3–1.

Table 3–1 Metadata for All Transport Attribute Definitions

Field Name	Explanation
Name	The (internal) parameter name. Used programmatically; never seen in ePM.
Display	The parameter label as seen by the ePM user.
Type	Data type. Used programmatically; never seen in ePM.
Required	Checkbox governing whether a value must be supplied in ePM. If yes, ePM displays an red asterisk to signal the user that this is a required value.
Direction	FromPartner, ToPartner, or Both. Used programmatically.
Default	The value supplied before the ePM user takes action, or takes no action.
List of Values	Items to display in a drop-down list for the ePM user to choose from
Fixed	(not used in any of presupplied TADs)
Format String	(not used in any of presupplied TADs)

BatchFTP

The Batch eWay uses the BatchFTP transport attributes definition to read from a remote file or write to a remote file. When designating a pattern of files to be read, the * (asterisk) is a wildcard meaning “zero or more characters.”

Table 3–2 lists the attributes of the BatchFTP TAD.

Table 3–2 Attributes for the BatchFTP Transport Attributes Definition

Name	Display	Type	Req?	Direction	Default	List
Append	Append	Boolean	No	Both
HostName	HostName	String	Yes	Both
ServerPort	ServerPort	Integer	No	Both
CommandConnectionTimeout	(same as Name)	Integer	No	Both
DataConnectionTimeout	(same as Name)	Integer	No	Both
DirectoryListingStyle	[...]	String	No	Both
ClientClassName		String	No	Both
ProviderClassName		String	No	Both
Mode		String	No	Both
UsePASV		Boolean	No	Both
UserName		String	No	Both
Password		Password	No	Both
UserPropertyFile		String	No	Both
TargetDirectoryName		String	Yes	Both
TargetDirectoryNameIsPattern		Boolean	No	Both
TargetFileName		String	Yes	Both
TargetFileNameIsPattern		Boolean	No	Both
MaxSequenceNumber		Integer	No	Both
StartingSequenceNumber		Integer	No	Both
PreDirectoryName		String	No	Both
PreDirectoryNameIsPattern		Boolean	No	Both
PreFileName		String	No	Both
PreFileNameIsPattern		Boolean	No	Both
PreTransferCommand		String	No	Both
PreTransferRawCommands		String	No	Both
PostDirectoryName		String	No	Both
PostDirectoryNameIsPattern		Boolean	No	Both
PostFileName		String	No	Both
PostFileNameIsPattern		Boolean	No	Both
PostTransferCommand		String	No	Both
PostTransferRawCommands		String	No	Both
ActionOnMalformedCommand		String	No	Both
IncludeOrderRecordInErrorRecord		Boolean	No	Both
IncludePayloadInErrorRecord		Boolean	No	Both
PublishStatusRecordOnError		Boolean	No	Both
PublishStatusRecordOnSuccess		Boolean	No	Both
SocksEnabled		Boolean	No	Both
SocksHostName		String	No	Both
SocksServerPort		Integer	No	Both
SocksVersion		Integer	No	Both
SocksUserName		String	No	Both
SocksPassword		Password	No	Both
SshTunnelingEnabled		Boolean	No	Both
SshListenHost	[...]	String	No	Both
SshListenPort	(same as Name)	Integer	No	Both
SshCommandLine	(same as Name)	String	No	Both
SshUserName	SshUserName	String	No	Both
SshPassword	SshPassword	Password	No	Both

BatchLocalFile

The Batch eWay uses the BatchLocalFile transport attributes definition to read from a local file or write to a local file. When designating a pattern of files to be read, the * (asterisk) is a wildcard meaning “zero or more characters.”

Table 3–3 lists the attributes of the BatchLocalFile TAD.

Table 3–3 Attributes for the BatchLocalFile Transport Attributes Definition

Name	Display	Type	Req?	Direction	Default	List
Append	Append	Boolean	No	Both
TargetDirectoryName	(same as Name)	String	Yes	Both
TargetDirectoryNameIsPattern	(same as Name)	Boolean	No	Both
TargetFileName	[...]	String	Yes	Both
TargetFileNameIsPattern		Boolean	No	Both
MaxSequenceNumber		Integer	No	Both
StartingSequenceNumber		Integer	No	Both
PreDirectoryName		String	No	Both
PreDirectoryNameIsPattern		Boolean	No	Both
PreFileName		String	No	Both
PreFileNameIsPattern		Boolean	No	Both
PreTransferCommand		String	No	Both
PostDirectoryName		String	No	Both
PostDirectoryNameIsPattern		Boolean	No	Both
PostFileName		String	No	Both
PostFileNameIsPattern		Boolean	No	Both
PostTransferCommand		String	No	Both
ResumeReadingEnabled		Boolean	No	Both
ActionOnMalformedCommand		String	No	Both
IncludeOrderRecordInErrorRecord		Boolean	No	Both
IncludePayloadInErrorRecord	[...]	Boolean	No	Both
PublishStatusRecordOnError	(same as Name)	Boolean	No	Both
PublishStatusRecordOnSuccess	(same as Name)	Boolean	No	Both

FILE

The File eWay uses the FILE transport attributes definition to read from a file or write to a file. When designating a pattern of files to be read, the * (asterisk) is a wildcard meaning “zero or more characters.”

Table 3–4 lists the attributes of the FILE TAD.

Table 3–4 Attributes for the FILE Transport Attributes Definition

Name	Display	Type	Req?	Direction	Default	List
FilePattern	FilePattern	String	Yes	Both
Directory	Directory	String	Yes	Both

FTP

For File Transfer Protocol, the BatchFTP eWay uses the FTP transport attributes definition to read from a file or write to a file in a remote location. When designating a pattern of files to be read, the * (asterisk) is a wildcard meaning “zero or more characters.”

Table 3–5 lists the attributes of the FTP TAD.

Table 3–5 Attributes for the FTP Transport Attributes Definition

Name	Display	Type	Req?	Direction	Default	List
FilePattern	FilePattern	String	Yes	Both
Directory	Directory	String	Yes	Both
UserName	UserName	String	Yes	Both
Password	Password	Password	Yes	Both
HostName	HostName	String	Yes	Both
PortNumber	PortNumber	Integer	No	Both
SocksEnabled	SocksEnabled	Boolean	No	Both	false
SocksHostName	SocksHostName	String	No	Both
SocksUserName	SocksUserName	String	No	Both
SocksPassword	SocksPassword	Password	No	Both
SocksServerPort	SocksServerPort	String	No	Both

HTTP

For Hypertext Transfer Protocol, the HTTPS eWay can use the URL attribute in the HTTP TAD to access Web pages. The HTTP TAD has the corresponding OTD: HTTPOTD_HTTP.

HTTPS

For Hypertext Transfer Protocol over SSL (Secure Sockets Layer), the HTTPS eWay uses the HTTPS transport attributes definition to access secure Web pages.

Table 3–6 lists the attributes of the HTTPS TAD.

Table 3–6 Attributes for the HTTPS Transport Attributes Definition

Name	Display	Type	Req?	Direction	Default	List
ClientCertAlias	ClientCertAlias	String	Yes	Both
UserName	UserName	String	Yes	Both
Password	Password	Password	Yes	Both

---

Note –

To use HTTPS, two environment components require non-default settings: in the Integration Server, the Web server configuration must have its “Enable SSL” parameter set to “True”, and in the HTTPS external, the SSL configuration must supply a value for its “TrustStore” parameter.

---

JMS

The JMS transport attributes definition is used to transport data into and out of JMS topics and queues.

SMTP

For Simple Mail Transfer Protocol, the email eWay uses the SMTP transport protocol to send and receive email.

Table 3–7 lists the attributes of the SMTP TAD.

Table 3–7 Attributes for the SMTP Transport Attributes Definition

Name	Display	Type	Req?	Direction	Default	List
SenderAddress	SenderAddress	String	Yes	ToPartner
Host	Host	String	Yes	ToPartner
PortNumber	PortNumber	String	Yes	ToPartner
UserName	UserName	String	No	Both
Password	Password	Password	No	Both

Channel Manager

The Channel Manager facility provides several services to access or write information in the eXchange Integrator database. It tracks messages and packages, associates responses to requests and tracks them, and retrieves trading partner information.

The Sun SeeBeyond⇒ eXchange⇒ChannelManager folder contains the ChannelManagerClient OTD. See Figure 3–2.

Figure 3–2 Sun SeeBeyond⇒eXchange⇒ ChannelManager Folder

In this section

• associate

• associateActions

• duplicatecheck

• track

• trackDialogue

• trackDialogueAction

associate

ChannelManagerClient.associate is used to associate a response to a request. This operation can only be used for message level documents — in other words envelopes, as opposed to business documents.

The service associates the response to the request using a message identifier to tie the two messages to each other.

Table 3–8 Input Containers for ChannelManagerClient.associate

Name	Description
OrigPkgHdrId	Database ID of the original message
AckPkgHeaderId	Database ID of the acknowledgement message
PkgType	Name of the messaging or packaging envelope used for the message, such as ISA or GS.
TPId	The database’s unique ID for the trading partner; in other words, the foreign key to ex_trading_partner.
MsgUniqId	Unique ID for the message.
ErrorFlag	A value of Y signifies that the message contains a “business” type of error: could not decrypt, could not verify signature, and so forth.
ErrorNo	(reserved)
ErrorStr	A description of the error.

Table 3–9 Output Container for ChannelManagerClient.associate

Name	Description
PkgAssocId	Association ID used to associate the response package to the request package.

associateActions

ChannelManagerClient.associateActions is similar to the associate operation, in that it associates a document response to a document request (for example, in X12, a 997 or 855 response to an original 850 request).

Table 3–10 Input Containers for ChannelManagerClient.associateActions

Name	Description
OrigPkgHdrId	Database ID of the original message
AckPkgHeaderId	Database ID of the acknowledgment message
PkgType	Name of the messaging or packaging envelope used for the message, such as ISA or GS.
TPId	The database’s unique ID for the trading partner; in other words, the foreign key to ex_trading_partner.
MsgUniqId	Unique ID for the message.
ErrorFlag	A value of Y signifies that the message contains a “business” type of error: could not decrypt, could not verify signature, and so forth.
ErrorNo	(reserved)
ErrorStr	A description of the error.

Table 3–11 Output Container for ChannelManagerClient.associateActions

Name	Description
isAssociated	A value of Y signifies that an associated action exists.

duplicatecheck

ChannelManagerClient.duplicatecheck is used to check for duplicates of a generic inbound or outbound message.

track

ChannelManagerClient.track performs a track operation to store the message to the eXchange Integrator database

Table 3–12 Input Containers for ChannelManagerClient.track

Name	Description
Protocol	Name of the protocol being used to handle the message.
ReceiveFlag	A value of Y signifies that the request message was inbound.
BufferId	ebXML only. Conversation ID.
OrderNumInBuffer	ebXML only. Reserved for use in message ordering.
MsgUniqId	Unique ID for the message.
TPId	The database’s unique ID for the trading partner; in other words, the foreign key to ex_trading_partner.
OrdMsgId	(not currently used)
Multiple Content	(not currently used)
PkgType	Name of the messaging or packaging envelope used for the message, such as ISA or GS.
ErrorFlag	A value of Y signifies that the message contains a “business” type of error: could not decrypt, could not verify signature, and so forth.
RespRequired	A value of Y signifies that a response to this message is required.
MsgBlob	Container for the message payload.
SignedFlag	A value of Y signifies that the message is signed.
CompressedFlag	A value of Y signifies that the message is compressed.
EncryptedFlag	A value of Y signifies that the message is encrypted.
MessageType	Message type for the message, such as Message or Ack.
Resendable	A value of Y signifies that the message can be re-sent.
Service	Service name for the request message for which the response is received.
Action	Action name for the request message for which the response is received.

Table 3–13 Output Container for ChannelManagerClient.track

Name	Description
MsgHdrId	Message header ID, used for message association.

trackDialogue

ChannelManagerClient.trackDialogue is used to write the initial message — that is, the first business document in a conversation — to message tracking. To write subsequent messages in the same conversation, the trackDialogueAction operation is used.

Table 3–14 Input Containers for ChannelManagerClient.trackDialogue

Name	Description
tpNetworkId	eXchange-generated unique ID identifying the trading partner.
dialogueID	Database-assigned unique ID identifying the business conversation.
dialogueIdentifier	Dialog ID in the message.
serviceName	Name of the messaging service or business service being used to handle the message.
activeFlag	A value of Y signifies that the business conversation is active.
Status	Status of the business conversation.
startDate	Timestamp recording when the business conversation initiated.
endDate	Timestamp recording when the business conversation terminated.
protocol	Name of the protocol being used to handle the message.
hostNetworkId	eXchange-generated unique ID identifying the B2B host.
isResponse	A value of true signifies that the message is a response to a previous message.

Table 3–15 Output Containers for ChannelManagerClient.trackDialogue

Name	Description
tpNetworkId	eXchange-generated unique ID identifying the trading partner.
dialogueID	Database-assigned unique ID identifying the business conversation.
dialogueIdentifier	Dialog ID in the message.
serviceName	Name of the messaging service or business service being used to handle the message.

trackDialogueAction

ChannelManagerClient.trackDialogueAction also writes to message tracking, but it writes subsequent messages in a business conversation (after the initial message was written by trackDialogue operation).

Table 3–16 Input Containers for ChannelManagerClient.trackDialogueAction

Name	Description
messageId	(deprecated) Duplicate of actionMessageId
actionName	Name of the messaging action that is processing the message.
receiveFlag	A value of Y signifies that it is an inbound message.
resendFlag	A value of Y signifies that this is a re-send of the message
sendCount	A value of Y signifies that the business conversation is active.
sequenceNum	Status of the business conversation.
referToType	(not used)
actStatus	(not used)
pkgMsgHdrId	Database-assigned unique ID for the message packaging.
msgType	Message type for the message, such as Message or Ack.
msgEncoding	Encoding to which the message conforms.
compressedFlag	A value of Y signifies that the message is compressed.
encryptedFlag	A value of Y signifies that the message is encrypted.
envelopedFlag	A value of Y signifies that the message is enveloped.
signedFlag	A value of Y signifies that the message is signed.
msgContent	The payload of the message.
attributeMap	Extended attributes for the message.
isStoreOriginal	(not used) A value of Y signifies that the original (raw) message is to be stored in the database.
errorFlag	A value of Y signifies that the message has an error associated with it.
respRequiredFlag	A value of Y signifies that a response is required for the message.
actionMessageId	Message ID.
messageType	A value of msg signifies a message; ack signifies an acknowledgment.

Table 3–17 Output Containers for ChannelManagerClient.trackDialogueAction

Name	Description
ActionId	ID of the service action (business transaction)

Message Tracker

The tracker application is used to record processing, packaging, and error information about messages and acknowledgments as they flow through the eXchange Integrator system.

The Sun SeeBeyond⇒ eXchange⇒Message Tracker folder contains only one item: the tracker application itself. See Figure 3–3.

Figure 3–3 eXchange⇒Message Tracker Folder

The application is entirely self-contained. All you need to do is connect an instance of the application to the B2B host you want to track and to a well-configured eXchange database. Activating this project generates an eXchange service that can be used in any other project contained in the same Repository.

For information on creating and activating a connectivity map containing a tracker application, see Connecting the B2B Host to Oracle and LDAP Externals. For information on using the Message Tracker web client to view tracking information that has been written to the database, see Message Tracker.

B2B Protocols for X12, HIPAA, EDIFACT, AS2, and ebXML

If you have licensed and installed any of the protocol manager composite applications, your Sun SeeBeyond⇒eXchange⇒ Protocol Managers folder contains additional folders. Each additional protocol folder includes a library of collaborations, OTDs, and B2B protocols that are custom-tailored for the specific protocol. The contents of each Sun SeeBeyond⇒ eXchange⇒ B2B Protocols protocol are extensive, and vary according to version. See the corresponding Protocol Manager user’s guides.

To gain a sense of how the protocol processes and collaborations/OTDs can be used, it is strongly recommended that you download and run the sample implementations. See the user’s guide corresponding to the Protocol Manager(s) you have installed.

Handling Errors

This section describes the behavior of the standard error-handling BP. If you want, you can create a custom error-handling BP and can sort and redirect errors in any way you prefer. Custom error-handlers are outside the scope of this document, and are discussed in the eXchange Integrator Developer’s Guide.

Message Tracker

Errors that occur at the business protocol level, such as an error within the payload of a single message resulting in a negative acknowledgment (such as an X12 997), or errors within the enveloping layer that can be reported at the messaging level (such as an X12 TA1), are a normal part of B2B conversation, and are not considered faults. For information on linking the B2B host to a tracker application, see Connecting the B2B Host to Oracle and LDAP Externals.

eXchange Integrator Standard Error-Handling Topics

System-level errors, and business errors that cannot be handled by message tracking, are considered faults; eXchange Integrator catches such faults and publishes the ExStdEvent — with the error information now contained inside the ExStdEvent — to a standard eXchange Integrator topic, EX_ERROR. If further processing is possible, the messages are finally published to the EX_PROCESSEDERRORS topic; otherwise, they are finally published to the EX_DEADLETTER topic.

EX_PROCESSEDERRORS

When EX_ERROR contains a marshallable ExStdEvent message, the message is presumed to contain all necessary troubleshooting details, specified in a clear enough way to allow the fault to be diagnosed. In this case, the ExStdEvent is published to the EX_PROCESSEDERRORS topic.

EX_DEADLETTER

When EX_ERROR contains an ExStdEvent message that cannot be unmarshaled, there is no way to determine the cause of the fault. In this case, the ExStdEvent is published to the EX_DEADLETTER topic.

Error Logs

For help in tracking down subtle or persistent errors, the integration server provides extensive log files whose reporting sensitivity can be tuned to various levels (ERROR, INFO, DEBUG). For more information, see the “Monitoring Logs” chapter in the eGate Integrator System Administration Guide.

Creating a Nondefault Error Handler

Within each of the standard BPs that provides for error handling, at the lower right margin of the main scope is a Catch Named Exception activity, connecting it to a scope containing an instance of a B2B protocol process: ErrorHandlerSelector. See Figure 3–4.

Figure 3–4 Template B2B Protocol Process “ErrorHandlerSelector“

If you open the ErrorHandlerSelector BP, you find that by default, it uses JMS for handling errors, mapping fields under the ErrorHandlerSelectorRequest’s errorEvent container to the handleError.Input’s ErrorHandler container. See Figure 3–5.

Figure 3–5 Mapping from ErrorHandlerSelector to ErrorHandler

The purpose of the JMSErrorHandler B2B protocol process is to send error messages to JMS, using the ErrorEvent_ErrorEventType OTD. However, in place of JMS, you could substitute SMTP to e-mail the text of the error message or FTP to write it to a file on a remote server. To create an SMTP-based error handler, for example, you would follow these steps:

To create an SMTP-based error handler

1. Export the sbyn-exchange-error.wsdl file.

2. In the Error Management folder, create a new B2B protocol process and name it; for example, SMTPErrorHandler.

3. Open the properties of SMTPErrorHandler and do the following:

   1. Use the WSDL tab to load the .wsdl file you exported.

   2. Use the Partners tab to add a new partner named ErrorSelector.

   3. Use the Business Process Attributes tab to create a new attribute named ErrorEvent (namespace urn:sbyn-exchange-err).

4. Drag activities onto the Protocol Designer canvas for SMTPErrorHandler and connect them.

5. Configure business rules in the same way as for JMSErrorHandler.

   After you have created a new error handler, you can go back to ErrorHandlerSelector and replace JMSErrorHandler with the new error handler, for example, if you wanted AS2OutboundChannelManager to deliver error messages via SMTP instead of JMS.

   In the same way, you can add or modify other components in the B2B Templates folder, making them part of the toolset used by eeXchange Integrator projects in this Repository.