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:
- WebSphere Partner Gateway provides a security service API that
you can use for decryption and signature verification.
- 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:
- Create a handler class that implements BusinesProcessHandlerInterface.
- 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.
- 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:
- BCGDocumentConstant.BCG_TOPackageCD
- BCGDocumentConstant.BCG_TOPackageVersion
- BCGDocumentConstant.BCG_TOProtocolCD
- BCGDocumentConstant.BCG_TOProtocolVersion
To obtain the metadata, use the BusinessDocumentInterface.getAttribute method.
Notes:
- 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.
- 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.
- 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:
- 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.
- 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. |
- 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.
- 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.
- Define the packaging implemented by this handler.
Figure 10. Defining a protocol packaging handler
- Create a deployment descriptor for this handler. See Development and deployment.
- Upload your handler by using the console as shown
in the following figure:
Figure 11. Uploading the protocol packaging handler
- 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
