Overview for creating handlers in fixed inbound workflow
Business documents received by WebSphere Business Integration
Connect are packaged according to the packaging requirements of
the business protocol. Business Integration Connect 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 Business Integration Connect 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
Business Integration Connect 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, Business
Integration Connect delivers handlers for these steps. With the
user exit support and APIs available in WebSphere Business Integration
Connect 4.2.2, 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 Business Integration Connect associated
with this business document flow
Protocol unpackaging handlers
Business Integration Connect provides RNIF,
AS2, backend integration,
and NONE packaging. If you are required to support packaging not
currently supported by Business Integration Connect, 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 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:
- Business Integration Connect 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 Business Integration Connect 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 Business Integration Connect 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 Business Integration Connect receives a document. You
should use the Business Integration Connect console to define this
code for the packaging document flow. |
BCGDocumentConstants.BCG_FRPACKAGINGVER |
The version to which the received packaging is
set when Business Integration Connect receives a document. You should
use the Business Integration Connect 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
Business Integration Connect provides processing
for the XML, RosettaNet, and EDI protocols. If you are required
to support a protocol not currently supported by Business Integration
Connect, you can develop a protocol processing handler.
A protocol processing handler is responsible for
parsing the business document to determine meta-information required
by Business Integration Connect. 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 Business Integration Connect
uses to identify the protocol; for example RosettaNet, V02.02
- Document flow and version
- The document flow code and version that Business Integration
Connect 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 Business Integration Connect console in the
Manage Document Flow Definitions view.
- The document flow and version associated with this handler should
be defined through the Business Integration Connect 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 Business Integration Connect 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
