Overview for creating handlers in fixed outbound workflow

The last step of fixed inbound workflow determines the connection. The connection gives the variable workflow to run on this business document and the "To" packaging and protocol to be used to send the business document to the destination trading partner.

After running the variable workflow, BPE runs the fixed outbound workflow. The protocol packaging step in the fixed outbound workflow packages the business document in the "To" packaging as determined by the connection.

The protocol packaging step consists of a series of handlers, the sequence of which is configured through the WebSphere Partner Gateway console. While running the steps, BPE runs these handlers one after the other until one of the handlers determines that it can process the business document. BPE then invokes this handler to process the business document. After the process method runs, BPE logs the events generated by this process method and then checks the status of the business document. If its status is marked as failed, BPE fails the flow of business document.

After running the fixed outbound workflow, BPE gives the packaged business document to the delivery manager. The delivery manager sends the business document to the partner as configured in the "To" gateway of the connection.

Protocol packaging handlers

A protocol packaging handler packages a business document. Depending on business protocol requirements and the trading partner agreement (TPA) between the sending and receiving trading partners, the outgoing business document may have to be assembled, encrypted, signed, or compressed. The protocol packaging handler should determine whether it can handle the business document. If it can, it should package the business document as expected by the business protocol for which it is designed. Additionally, if the business protocol requires transport headers, it may also specify them in metadata defined by WebSphere Partner Gateway.

WebSphere Partner Gateway provides handlers for this step for RNIF, backend integration, AS, and NONE packaging. If a requirement exists to support a packaging protocol not currently supported by WebSphere Partner Gateway, you can develop a protocol packaging handler.

Depending on business protocol requirements, the protocol packaging handler may perform one or more of the steps:

Assembling
If the business protocol requires the message to be packaged as different parts, such as payload, attachments, and so forth
Encrypting
If the packaging type requires encryption
Signing
If the packaging type requires signatures
Compressing
If the packaging type requires compression

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

Important:
  1. WebSphere Partner Gateway provides a security service API that you can use for decryption and signature verification.
  2. The packaging and version associated with this handler should be defined through the WebSphere Partner Gateway console in the Manage Document Flow Definitions view.

Implementing protocol packaging handlers

To implement a protocol packaging handler:

  1. Create a handler class that implements BusinesProcessHandlerInterface.
  2. Implement the BusinessProcessHandlerInterface.init method. In this method, initialize your handler. Note that the handler may have configuration properties that can be configured through the console.
  3. Implement the BusinessProcessHandlerInterface.applies method. The business document is passed as an argument of type BusinessDocumentInterface to this method. In this method, the handler should determine whether it can process the business document. To determine this, look at the following metadata defined by WebSphere Partner Gateway: To obtain the metadata, use the BusinessDocumentInterface.getAttribute method.
    Notes:
    1. The handler can use various mechanisms to determine whether it can handle this business document. For example, it can do a quick scan of business document.
    2. The packaging and protocol being processed by this handler should be defined in the console in the Manage Document Flow Definitions view.
    If the handler can process this document, the applies method should return true; otherwise it should return false.
  4. Implement the BusinessProcessHandler.process method. The business document is passed as an argument of type BusinessDocumentInterface to this method. This method should perform the following actions:
    1. Package the business document so that other steps and workflows can process it. If the handler is changing the contents of business document, the BusinessDocumentInterface class should be updated by calling the setDocument method.
    2. Set metadata required by WebSphere Partner Gateway on the BusinessDocumentInterface object by calling the setAttribute method. The following constants are defined in the BCGDocumentConstant class:
      Protocol attribute name Description
      BCGDocumentConstants.BCG_OUTBOUNDTRANSPORTHEADERS Outbound transport headers that are used by the sender, when it transfers the document over a specified transport. The value for this attribute is a HashMap object that contains the list of transport headers. For example, HTTP Sender uses this attribute to set the HTTP headers.
    3. Add events to the BusinessDocumentInterface object by calling the addEvent method. These events will be visible in the console with this business document. For a list of events that you can add in this step, see Events.
    4. Update the status of the BusinessDocumentInterface object. If there were any errors, mark BusinessDocumentInterface as failed by calling the setDocumentState method with BCGDocumentConstants.BCG_DOCSTATE_FAILED.
  5. Define the packaging implemented by this handler.
    Figure 10. Defining a protocol packaging handler
    Defining a protocol packaging handler
  6. Create a deployment descriptor for this handler. See Development and deployment.
  7. Upload your handler by using the console as shown in the following figure:
    Figure 11. Uploading the protocol packaging handler
    Uploading the protocol packaging handler
  8. Configure your handler. Specify the sequence in which your handler should be called, as shown in the following figure:
    Figure 12. Configuring the protocol packaging handler
    Configuring the protocol packaging handler

Copyright IBM Corp. 2003, 2005