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:
- 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 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:
- WebSphere Partner Gateway provides a security service API that
you can leverage to decrypt messages and verify signatures.
- Define the packaging and version associated with this handler
in the WebSphere Partner Gateway Community Console on the Manage
Document Flow Definitions page.
To implement a protocol unpackaging handler:
- Create a handler class that implements BusinesProcessHandlerInterface.
- 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.
- 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.
- 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:
- Unpackage the business document so that other steps and workflows
can process it. If the handler is changing the contents of the business
document, update BusinessDocumentInterface 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. Set it the same as BCG_PKG_FRBUSINESSID or set it 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. Use the
WebSphere Partner Gateway Community 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. Use the
WebSphere Partner Gateway Community 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 Community 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 Figure 2.
Figure 2. Defining a package for a protocol unpackaging handler
- Create a deployment descriptor for this handler. See the section Development and deployment.
- Use the Community Console to upload your handler,
as shown in Figure 3.
Figure 3. Uploading the protocol unpackaging handler
- Configure your handler. Specify the sequence in which
to call your handler as shown in Figure 4.
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:
- Define the protocol and version associated with this handler
in the WebSphere Partner Gateway Community Console on the Manage
Document Flow Definitions page.
- 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:
- 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 in the
Community Console.
- 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.
- 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:
- 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 must be a valid process name as defined in
the Community Console, for example, RosettaNet. |
BCGDocumentConstants.BCG_FRPROTOCOLVER |
The protocol version associated with the incoming business
document. This must be a valid process version as defined in the
Community Console, for example, V02.00. |
BCGDocumentConstants.BCG_FRPROCESSCD |
The process code associated with the incoming
business document. This must be a valid code as defined in the Community
Console, for example, 3A4. |
BCGDocumentConstants.BCG_FRPROCESSVER |
The process version associated with the incoming business
document. This must be a valid process version as defined in the
Community Console, for example, V02.00. |
- Add events to the BusinessDocumentInterface object by calling the addEvent method. These events will be visible in the Community 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 as shown in Figure 5.
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.
- Use the Community Console to upload your handler
as shown in Figure 6.
Figure 6. Uploading a protocol processing handler
- Configure your handler. Specify the sequence in which
your handler is called as shown in Figure 7.
