Overview for creating handlers in fixed inbound workflow

Business documents received by WebSphere Partner Gateway are packaged according to the packaging requirements of the business protocol. WebSphere Partner Gateway uses the following terminology:

Packaging
A type of document packaging such as RNIF, AS2, or Backend Integration.
Protocol
The business protocol that the contents of the document follow; for example, RosettaNet, XML, or EDI.
Document flow
A particular document type such as RosettaNet 3A4.

To process the business document, the BPE determines the packaging, protocol, and document flow associated with the incoming business document. The protocol unpackaging and protocol processing steps of fixed inbound workflow provide this information. When running fixed inbound workflow, the BPE first runs the protocol unpackaging step followed by the protocol processing step. These steps generate meta-information defined by WebSphere Partner Gateway that is used by fixed inbound workflow to determine the participant connection that can be used to route this business document. Note that the participant connection determines which variable workflow will run for this business document.

Each step invokes a series of handlers, the sequence of which is configured in the WebSphere Partner Gateway Community Console. While running the steps, the BPE runs these handlers one after the other, until one of the handlers determines that it can handle the business document. If a handler determines that it can handle the business document, the BPE invokes the handler to process the business document. If there is no such handler, the BPE fails the flow of this business document. After the process method of the handler runs, the BPE logs the events generated by this process method. The BPE checks the status of business document. The BPE fails the flow of a business document if its status is marked as failed.

For the business protocols that it supports, WebSphere Partner Gateway delivers handlers for these steps. With the user exit support and APIs available in WebSphere Partner Gateway, you can develop handlers for these steps. The handlers implement all the methods of BusinessProcessHandlerInterface. BusinessDocumentInterface represents the business document processed by these handlers. BusinessDocumentInterface consists of following components:

Protocol unpackaging handlers

WebSphere Partner Gateway provides RNIF, AS2, backend integration, and NONE packaging. If you are required to support packaging not currently supported by WebSphere Partner Gateway, you can develop a new protocol unpackaging handler.

The protocol unpackaging handler is expected to unpackage business documents. Depending on business protocol requirements and the TPA (trading partner agreement) between the sending and receiving business partners, the incoming business document might be encrypted, signed, or compressed. The protocol unpackaging handler determines whether it can handle the incoming business document. If it can, it unpackages the business document so that the following fixed inbound workflow steps, and the BPE workflows can process it. Additionally, this handler extracts package-level meta-information from the incoming business document.

Depending on the business protocol requirements, the protocol unpackaging handler might perform one or more of the following steps:

Decryption
Decrypt the message if it is encrypted
Decompression
Decompress the message if it is compressed
Signature verification
Verify the signature if the message is signed
Routing information extraction
Extract package-level business IDs for sending to and receiving from a trading partner, if the packaging provides them
Form packaging and versions
Use a packaging code and version to identify the packaging; for example, RNIF v02.00
Business document parts extraction
Extract the location of various message parts such as payload and attachments, if the packaging specifies them

These steps are not exhaustive and might not apply to all business protocols.

Important:

To implement a protocol unpackaging handler:

  1. Create a handler class that implements BusinesProcessHandlerInterface.
  2. Implement a BusinessProcessHandlerInterface.init method. Use this method to initialize your handler. The handler can have configuration properties that can be configured in the Community Console.
  3. Implement a BusinessProcessHandlerInterface.applies method. In this method, the handler determines whether it can process the business document. (The business document is passed as an argument of type BusinessDocumentInterface to this method.) You can make the handler determine this by making the handler look at transport-level headers, quickly scan the business document, or take any other protocol-specific approach. If the handler can handle this document, the applies method returns true; otherwise, it returns false.
  4. Implement a BusinessProcessHandler.process method. The business document is passed as an argument of type BusinessDocumentInterface to this method. This method performs the following tasks:
  5. Define the packaging implemented by this handler, as shown in Figure 2.
    Figure 2. Defining a package for a protocol unpackaging handler
    Defining a package for a protocol unpackaging handlerDD
  6. Create a deployment descriptor for this handler. See the section Development and deployment.
  7. Use the Community Console to upload your handler, as shown in Figure 3.
    Figure 3. Uploading the protocol unpackaging handler
    Uploading the protocol unpackaging handler
  8. Configure your handler. Specify the sequence in which to call your handler as shown in Figure 4.
    Figure 4. Configuring the protocol unpackaging handler
    Configuring the protocol unpackaging handler

Protocol processing handlers

WebSphere Partner Gateway provides processing for the XML, RosettaNet, and EDI protocols. If you are required to support a protocol not currently supported by WebSphere Partner Gateway, you can develop a protocol processing handler.

A protocol processing handler is responsible for parsing the business document to determine meta-information required by WebSphere Partner Gateway. Depending on business protocol, this handler can provide one or more of following items:

Routing information
Business IDs of the sending and receiving trading partners
"From" protocol and version
The protocol code and version that WebSphere Partner Gateway uses to identify the protocol; for example RosettaNet PIP V02.02
Document flow and version
The document flow code and version that WebSphere Partner Gateway uses to identify the document flow, for example, 3A4, V02.00 (for RosettaNet)
Important:
  1. Define the protocol and version associated with this handler in the WebSphere Partner Gateway Community Console on the Manage Document Flow Definitions page.
  2. Define the document flow and version associated with this handler in the WebSphere Partner Gateway Community Console on the Manage Document Flow Definitions page.

To implement a protocol processing handler:

  1. Create a handler class that implements BusinesProcessHandlerInterface.
  2. Implement a BusinessProcessHandlerInterface.init method. In this method initialize your handler. The handler can have configuration properties that can be configured in the Community Console.
  3. Implement a BusinessProcessHandlerInterface.applies method. In this method the handler determines whether it can process the business document, whose name is passed to the method as an argument of type BusinessDocumentInterface. You can determine this by looking at transport-level headers, quickly scanning the business document, or by using any other protocol-specific approach. If the handler can handle this document, the applies method returns true; otherwise, it returns false.
  4. Implement a BusinessProcessHandler.process method. The business document is passed to this method as an argument of type BusinessDocumentInterface. This method s performs the following actions:
  5. Define the protocol implemented by this handler as shown in Figure 5.
    Figure 5. Defining the protocol for a protocol processing handler
    Defining the protocol for a protocol processing handler
  6. Create a deployment descriptor for this handler. For information on how to deploy your handler, see Development and deployment.
  7. Use the Community Console to upload your handler as shown in Figure 6.
    Figure 6. Uploading a protocol processing handler
    Uploading a protocol processing handler
  8. Configure your handler. Specify the sequence in which your handler is called as shown in Figure 7.
    Figure 7. Configuring a protocol processing handler
    Configuring a protocol processing handler

Copyright IBM Corp. 2003, 2005