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, 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, 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 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 handle the business
document. If a handler determines that it can handle the business document,
BPE invokes the handler to process the business document. If there
is no such handler, BPE fails the flow of this business document.
After the process method of the handler runs, BPE logs the events
generated by this process method. BPE then checks the status of
business document. 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 should implement all the
methods of BusinessProcessHandlerInterface. BusinessDocumentInterface
represents the business document processed by these handlers. BusinessDocumentInterface
consists of following components:
- Business data stored in a file object
- Transport headers associated with the business document
- Metadata specific to WebSphere Partner Gateway associated with
this business document flow
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 may be encrypted, signed,
or compressed. The protocol unpackaging handler should determine
whether it can handle the incoming business document. If
it can, then it should unpackage the business document so that following fixed
inbound workflow steps and BPE workflows can process it. Additionally,
this handler should extract package-level meta-information from
the incoming business document.
Depending on business protocol requirements, the protocol unpackaging
handler may perform one or more of the following steps:
- Decryption
- Decrypts the message if it is encrypted
- Decompression
- Decompresses the message if it is compressed
- Signature verification
- Verifies the signature if the message is signed
- Routing information extraction
- Extracts package-level business IDs for sending to and receiving
from a trading partner, if the packaging provides them
- Form packaging and versions
- Uses a packaging code and version to identify the packaging;
for example, RNIF v02.00
- Business document parts extraction
- Extracts the location of various message parts such as payload
and attachments, if the packaging specifies them
These steps are not exhaustive and may not apply to all business
protocols.
Important:
- WebSphere Partner Gateway provides a security service API that
you can leveraged to decrypt messages and verify signatures.
- The packaging and version associated with this handler should
be defined from the WebSphere Partner Gateway console in the Manage
Document Flow Definitions view.
To implement a protocol unpackaging handler:
- Create a handler class that implements BusinesProcessHandlerInterface.
- Implement a BusinessProcessHandlerInterface.init method. In this method, initialize your handler. The handler
can have configuration properties that can be configured through
the console.
- Implement a BusinessProcessHandlerInterface.applies method. In this method, the handler should determine 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 should return true; otherwise it should return false.
- Implement a BusinessProcessHandler.process method. The business document is passed as an argument of
type BusinessDocumentInterface to this method. This method should perform following tasks:
- Unpackage the business document so that other steps and workflows
can process it. If the handler is changing the contents of the business
document, BusinessDocumentInterface should be updated by calling the setDocument method.
- Set the metadata required by WebSphere Partner Gateway on the BusinessDocumentInterface object by calling the setAttribute method. These constants, defined in the BCGDocumentConstants class, are described in the following table:
Attribute name |
Description |
BCGDocumentConstants.BCG_PKG_FRBUSINESSID |
The "From" business ID at the package level.
For example, for AS2 the "From" business ID is available in
the AS2-From HTTP header. |
BCGDocumentConstants.BCG_PKG_TOBUSINESSID |
The "To" Business ID at the package level.
For example, for AS2 the "To" business ID is available in the AS2-To HTTP header. |
BCGDocumentConstants.BCG_PKG_INITBUSINESSID |
The initiating business ID at the package level. This should be set the same as that of BCG_PKG_FRBUSINESSID or as the business ID that belongs to the same partner as BCG_PKG_FRBUSINESSID. |
BCGDocumentConstants.BCG_FRPACKAGINGCD |
The attribute to which the code of the received
packaging is set when WebSphere Partner Gateway receives a document.
You should use the WebSphere Partner Gateway console to define this
code for the packaging document flow. |
BCGDocumentConstants.BCG_FRPACKAGINGVER |
The version to which the received packaging is
set when WebSphere Partner Gateway receives a document. You should
use the WebSphere Partner Gateway console to define this version for
the packaging document flow. |
- Add events to the BusinessDocumentInterface object. You can add events to this 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 this object as failed
by calling the setDocumentState method with the BCGDocumentConstants.BCG_DOCSTATE_FAILED argument.
- Define the packaging implemented by this handler,
as shown in the following figure:
Figure 2. Defining a package for a protocol unpackaging handler
- Create a deployment descriptor for this handler. See the section Development and deployment.
- Upload your handler by using the console, as shown
in the following figure:
Figure 3. Uploading the protocol unpackaging handler
- Configure your handler. Specify the sequence in which
your handler should be called as shown in the following figure:
Figure 4. 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 may
be able to provide one or more of following items:
- Routing information
- Business IDs of the sending and receiving trading partner
- "From" protocol and version
- The protocol code and version that WebSphere Partner Gateway
uses to identify the protocol; for example RosettaNet, 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:
- The protocol and version associated with this handler should
be defined from the WebSphere Partner Gateway console in the Manage
Document Flow Definitions view.
- The document flow and version associated with this handler should
be defined through the WebSphere Partner Gateway console in the
Manage Document Flow Definitions view.
To implement a protocol processing handler:
- Create a handler class that implements BusinesProcessHandlerInterface.
- Implement a BusinessProcessHandlerInterface.init method. In this method initialize your handler. The handler
can have configuration properties that can be configured through
the console.
- Implement a BusinessProcessHandlerInterface.applies method. In this method the handler should determine 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 should return true; otherwise it should return false.
- Implement a BusinessProcessHandler.process method. The business document is passed to this method as
an argument of type BusinessDocumentInterface. This method should perform the following actions:
- Set metadata required by WebSphere Partner Gateway on the BusinessDocumentInterface object by calling the setAttribute method. These constants, defined in the BCGDocumentConstant class, are described in the following table:
Protocol attribute name |
Description |
BCGDocumentConstants.BCG_FRBUSINESSID |
The "From" business ID obtained from the protocol. |
BCGDocumentConstants.BCG_TOBUSINESSID |
The "To" business ID obtained from the protocol. |
BCGDocumentConstants.BCG_INITBUSINESSID |
The initiating business ID obtained from the protocol. |
BCGDocumentConstants.BCG_FRPROTOCOLCD |
The protocol code associated with the incoming
business document. This should be a valid process name as defined
in the console, for example, RosettaNet. |
BCGDocumentConstants.BCG_FRPROTOCOLVER |
The protocol version associated with the incoming
business document. This should be a valid process version as defined
in the console, for example, V02.00. |
BCGDocumentConstants.BCG_FRPROCESSCD |
The process code associated with the incoming
business document. This should be a valid code as defined in the
console, for example, 3A4. |
BCGDocumentConstants.BCG_FRPROCESSVER |
The process version associated with the incoming
business document. This should be a valid process version as defined
in the console, for example, V02.00. |
- 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 a BCGDocumentConstants.BCG_DOCSTATE_FAILED argument.
- Define the protocol implemented by this handler.
Figure 5. Defining the protocol for a protocol processing handler
- Create a deployment descriptor for this handler. For information
on how to deploy your handler, see Development and deployment.
- Upload your handler by using the console.
Figure 6. Uploading a protocol processing handler
- Configure your handler. Specify the sequence in which
you handler should be called.
Figure 7. Configuring a protocol processing handler
