Oracle® Fusion Middleware Developer's Guide for Oracle Application Integration Architecture Foundation Pack 11g Release 1 (11.1.1.4.0) E17364-02 |
|
![]() Previous |
![]() Next |
This chapter discusses the following topics:
Section 20.1, "Introduction to Developing and Implementing Inbound B2B Integration Flows"
Section 20.2, "Step 1: Identifying the B2B Document and Analyzing Requirements"
Section 20.3, "Step 2: Adding Inbound Routing Rules to an AIA B2B Interface"
Section 20.4, "Step 3: Developing a New Requester B2B Connector Service"
Section 20.5, "Step 4: Developing or Extending an Existing Enterprise Business Service"
Section 20.6, "Step 5: Developing or Extending an Existing Provider ABCS"
Section 20.7, "Step 6: Configuring Oracle B2B and Defining Trading Partner Agreements"
Section 20.8, "Step 7: Deploying and Configuring AIA Services"
Figure 20-1 shows the high-level steps involved in developing a simple inbound business-to-business (B2B) flow from an application to trading partners using Oracle Application Integration Architecture (AIA).
Most of the preceding steps are already described inChapter 19, "Developing and Implementing Outbound B2B Integration Flows." This chapter will be referred to whenever applicable.
The first step in building an inbound B2B flow, as shown in Figure 20-2, is to identify the B2B document that needs to be generated by the flow. As a part of this step, you must also analyze the requirements for the AIA services that need to be built or extended to support the flow.
The only differences in this step for the outbound B2B document flows and the steps for the inbound B2B document flows are as follows:
The source and targets in the mapping are reversed. The B2B document received from trading partners is the source of the mapping. The AIA Enterprise Business Message (EBM) is the target of the mapping.
At the end of this step:
The B2B document is defined in Oracle B2B.
The XML schema of the B2B document is uploaded in the AIA Metadata Repository.
The Enterprise Business Object (EBO) and the EBM to be used in the integration are identified.
Functional mapping between the B2B document and the AIA EBM is complete.
For more information about identifying the B2B document and analyzing requirements, see Section 19.2, "Step 1: Identifying the B2B Document and Analyzing Requirements."
The next step in building an inbound B2B flow, as shown in Figure 20-3, is to add routing rules to the AIAB2BInterface Infrastructure service.
In inbound B2B document flows, the AIAB2BInterface service listens for new B2B documents received by Oracle B2B and routes them to the requester B2B services, as shown in Figure 20-4.
The AIA B2B Interface composite has a JMS adapter to listen for new inbound B2B documents processed by Oracle B2B. The trading partner agreement in Oracle B2B is configured to route inbound B2B documents to the AIA_B2B_IN_QUEUE JMS queue.
The AIA B2B Interface identifies the B2B document type of the inbound B2B document and routes the document to the requester B2B Connector Service (B2BCS) Implementation that is responsible for processing the B2B document.
For example, if the B2B document type is OAG_Process Invoice, then the AIA B2B Interface will route the document to the OAGProcessInvoiceRequesterB2BCSImpl service.
The input to the requester B2BCS Implementation is the B2BM element. The B2BM element is defined in the AIAComponents/EnterpriseObjectLibrary/Infrastructure/V1/Meta.xsd file.
The AIA B2B Interface constructs the B2BM element from the B2B document received from Oracle B2B as described here:
/corecom:B2BM /corecom:B2BMHeader /corecom:B2BMID
Mapped from: B2B document JMS header property MSG_ID
Description: The unique identifier generated by Oracle B2B for the inbound B2B document.
This field is to correlate the AIA flow with the corresponding transaction in Oracle B2B.
Example: 5602359000000
/corecom:B2BM /corecom:B2BMHeader /corecom:B2BDocumentType /corecom:TypeCode
Mapped from: DOCTYPE_NAME
Description: The document type of the inbound document as identified by Oracle B2B.
Example: OAG_PROCESS_INVOICE
/corecom:B2BM /corecom:B2BMHeader /corecom:B2BDocumentType /corecom:Version
Mapped from: DOCTYPE_REVISION
Description: The document revision of the inbound document as identified by Oracle B2B.
Example: 9.0
/corecom:B2BM /corecom:B2BMHeader /corecom:SenderTradingPartner /corecom:TradingPartnerID
Mapped from: FROM_PARTY
Description: The source (from) trading partner of the B2B document.
The value is the trading partner name as defined in Oracle B2B.
Example: GlobalChips
/corecom:B2BM /corecom:B2BMHeader /corecom:ReceiverTradingPartner /corecom:TradingPartnerID
Mapped from: TO_PARTY
Description: The destination (to) trading partner to whom the inbound B2B document was sent.
The value is the trading partner name as defined in Oracle B2B.
Example: Acme
/corecom:B2BM /corecom:Payload
Mapped from: JMS payload
Description: The actual JMS text payload that contains the B2B document sent by the trading partner.
Example: <?xml version="1.0"?> <PROCESS_INVOICE_002> <CONTROLAREA>…
To add a new routing rule to the AIA B2B Interface:
Open the $AIA_HOME/Infrastructure/B2B/AIAB2BInterfaceApp/AIAB2BInterfaceApp.jws application using Oracle JDeveloper.
Open the composite.xml file using Oracle JDeveloper, as shown in Figure 20-5.
Add a new service reference to the requester B2BCS that processes the new inbound B2B document type as shown in Figure 20-6. The next section of this document explains how to develop requester B2BCSs.
Add a wiring to the newly added service from the Receive B2BM Mediator component in the composite as shown in Figure 20-7.
Choose the Mediator operation ReceiveB2BMessage as the source of the wiring and the target as the operation exposed by the target requester B2BCS. Save your changes.
Open the file ProcessInbound.mplan as shown in Figure 20-8.
Add a new routing rule to invoke the requester B2BCS using the service reference added to the file composite.xml, as shown in Figure 20-9.
Add a new routing rule to the ReceiveB2BMessage operation.
Edit the filter operation for the newly added routing rule. Define the filter based on the B2B document type. For example, the routing filter in Figure 20-10 ensures that the EDI X12 Process Sales Order documents are routed to the X12 ProcessSalesOrder B2BCS Implementation.
Save your changes.
Deploy the modified SOA composite application.
This section includes the following topics:
Section 20.4.1, "Introduction to Requester B2B Connector Services"
Section 20.4.2, "How to Identify the Message Exchange Pattern"
Section 20.4.4, "How to Store a WSDL in Oracle Metadata Services Repository"
Section 20.4.7, "How to Support Trading Partner-Specific Variants"
The next step, as shown in Figure 20-11, is to develop the requester B2BCS to support the outbound B2B integration flow.
The requester B2BCS is very similar to a requester Application Business Connector Service (ABCS), with the only difference being that it integrates with trading partners via Oracle B2B instead of integrating with an application. Hence, we recommend that you familiarize yourself with the design and development of ABCSs (requester and provider).
For more information about developing ABCSs, see Chapter 14, "Constructing the ABCS."
The key function provided by a requester B2BCS is to enable inbound B2B document integration by performing the following tasks:
Receive B2B documents sent by trading partners from Oracle B2B.
Transform B2B documents into AIA EBMs.
Use EBMs as request payloads to invoke AIA Enterprise Business Services (EBSs).
Figure 20-12 illustrates the processing that takes place in a simple fire-and-forget message exchange pattern-based provider B2BCS.
Step-by-step instructions for developing B2BCSs are provided in the following sections.
Similar to outbound B2B flows, most inbound B2B flows can be modeled using the fire-and-forget message exchange pattern.
Responses to be sent to trading partners can be modeled using separate outbound fire-and-forget flows.
Also, depending on the protocol involved, Oracle B2B can be configured to automatically send a confirmation or acknowledgement message to trading partners.
For more information, see Section 19.3.2, "How to Identify the Message Exchange Pattern."
For more information about identifying message exchange patterns, see Section 13.3, "Identifying the MEP."
First, define the service contract (WSDL) of the requester B2BCS. The service contract of the provider B2BCS specifies how it is invoked by an AIA flow. The service contract specifies the B2B operation being implemented and the B2B document type that it is capable of processing as the input request message.
For more information about creating WSDLs for ABCSs, see Section 13.2, "Defining the ABCS Contract."
Following are the naming conventions recommended for use in the B2BCS WSDL definitions:
WSDL File Name:
Naming guideline: <B2BStandard><Verb><EBO>ReqB2BCSImpl.wsdl
Example: X12ProcessSalesOrderReqB2BCSImpl.wsdl
Service Namespace:
http://xmlns.oracle.com/B2BCSImpl/{Core|Industry/<IndustryName> }/<B2BStandard><Verb><EBO>ReqB2BCSImpl/<ABCSVersion>
Example: http://xmlns.oracle.com/B2BCSImpl/Core/X12ProcessSalesOrderProvB2BCSImpl/V1
Please note that the ABCS Service version is independent of the B2B document/standard version.
For more information about recommendations on versioning AIA services, see Section 15.8, "Versioning ABCS."
Service Name:
Naming guideline: <B2BStandard><Verb><EBO>ReqB2BCSImpl
Example: X12ProcessSalesOrderProvB2BCSImpl
Port Type Name:
Naming guideline: <B2BStandard><Verb><EBO> ReqB2BCSImplService
Example: X12ProcessSalesOrderProvB2BCSImplService
Operation Name:
<Verb><EBO>
ProcessSalesOrder
Request Message Name:
<Verb><EBO>ReqMsg
ProcessSalesOrderReqMsg
As a SOA best practice, we recommend that all shared service artifacts, such as WSDL and XSD files, be stored in a central location that can be accessed by multiple services.
All of the AIA-shared artifacts are stored in the Oracle Metadata Services (MDS) repository. Storage of shared artifacts in the MDS not only makes them globally accessible, but also enables AIA to leverage features in MDS that support caching and clustering.
Provider B2BCS WSDLs are stored at the following location in the MDS: /apps/AIAMetaData/AIAComponents/B2BServiceLibrary/Connectors/wsdls/ <B2B_STANDARD> /ProviderB2BCS/ <VERSION> / <B2B_STANDARD> <VERB> <OBJECT> ReqB2BCSImpl.wsdl
To store a WSDL in MDS:
Copy the handcrafted WSDL to the following location: $AIA_HOME/aia_instances/$INSTANCE_NAME/AIAMetaData/AIAComponents/B2BServiceLibrary/Connectors/wsdls/<B2B_STANDARD>/RequesterB2BCS/<VERSION>/<wsdl file>.wsdl
Run the UpdateMetaDataDP.xml file present in $AIA_HOME/aia_instances/$INSTANCE_NAME/config/.
Using a SOA-MDS server connection to MDS, verify that AIA Metadata has been supplied, as shown in Figure 20-13.
The WSDL can now be accessed using a URL similar to the following: oramds:/apps/AIAMetaData/AIAComponents/B2BServiceLibrary/ Connectors/wsdls/EDI_X12/RequesterB2BCS/V1/ X12ProcessSalesOrderProvB2BCSImpl.wsdl
The next step in the process is to develop the B2BCS. The requester B2BCS WSDL created in the previous step is used as the interface while you are developing the concrete B2BCS.
Because Service Constructor does not support the autogeneration of B2B services, use Oracle JDeveloper to develop the B2BCS. Develop a composite with a BPEL process based on the abstract WSDL created in the previous step.
Following are the key activities that need to be developed in the B2BCS implementation BPEL.
To develop a B2B connector service:
Create a SOA Composite application containing a SOA project with a BPEL component.
Choose the WSDL created in the previous step as the interface for the SOA composite.
The values to be used for creating the SOA application and project are listed in Table 20-1.
Table 20-1 Values Used to Create the SOA Application and Project
Activity | Value |
---|---|
Application Name |
|
Project Name |
|
Project Namespace |
(Same as B2BCS WSDL namespace) |
Composite Name |
|
Composite Template |
Composite with BPEL |
BPEL Process Name |
|
Namespace |
(Same as B2BCS WSDL namespace) |
Template |
Base on WSDL |
WSDL URL |
URL of B2BCS service WSDL referred from MDS |
Define variable <B2BM>_Var.
This is the input variable to the BPEL process and is used in the receive activity.
Define the variable based on the corecom:B2BM global element defined in the Meta.xsd.
Define variable EBM_HEADER of type corecom:EBMHeader.
This variable is used to store the AIA process context information and is used by the fault-handling mechanism.
Define the variable based on the corecom:B2BM global element defined in the Meta.xsd.
Define variable B2BM_HEADER of type corecom:B2BMHeader.
This variable is used to store the B2B-specific AIA process context information and is used by the fault-handling mechanism.
Define the variable based on the corecom:B2BMHeader global element defined in the Meta.xsd.
Define variable <B2BDoc>_Var using the external B2BDocument definition.
This is used as the source of the transformation from EBM. This variable is then assigned to the <B2BDoc>B2BM_Var/Payload.
Define a partner link to the EBS.
This is the AIA EBS that is invoked by the requester B2BCS.
The abstract EBS WSDL can be referenced from: oramds:/apps/AIAMetaData/AIAComponents/EnterpriseBusinessServiceLibrary/Core/<EBO>/V<x>/<EBOName>.wsdl.
Transform the EBM to the B2B Document.
Use a transform activity to transform the EBM to the B2B Document format. Invoke an XSLT developed per the mapping created in the previous step.
Assign B2B-specific EBMHeader variables as shown here:
Element: corecom:EBMHeader/corecom:B2BProfile/corecom:SenderTradingPartner/corecom:TradingPartnerID
Source B2BM XPATH: corecom:B2BM/corecom:B2BMHeader/corecom:SenderTradingPartner/corecom:TradingPartnerID
Element: corecom:EBMHeader/corecom:B2BProfile/corecom:ReceiverTradingPartner/corecom:TradingPartnerID
Source B2BM XPATH: corecom:B2BM/corecom:B2BMHeader/corecom:ReceiverTradingPartner/corecom:TradingPartnerID
This way, the sender and receiver trading-partner information identified by Oracle B2B is passed on to the EBM.
Invoke the EBS.
Invoke the AIA EBS to process the EBM.
Compile the BPEL process and ensure that no errors occurred. You can use Oracle JDeveloper to deploy the BPEL process to a development server that has AIA Foundation Pack installed.
To make key metadata about the B2BCS available to the Project Lifecycle Workbench and Oracle Enterprise Repository, the composite.xml file of the B2BCS Implementation SOA composite must be annotated in a specific manner.
For more information about the Project Lifecycle Workbench, see Chapter 3, "Working with Project Lifecycle Workbench."
For more information about annotating B2B services, see Chapter 11, "Annotating Composites."
To annotate requester B2B Connector Services:
Table 20-2 lists the annotation elements that must be added to the service element composite.xml, as described subsequently.
Table 20-2 Service Annotation Elements in composite.xml
Annotation Element | Description | Example |
---|---|---|
AIA/Service/InterfaceDetails/Service Operation |
<Verb><EBOName> |
ProcessSalesOrder |
AIA/Service/ImplementationDetails/ArtifactType |
RequesterB2BCSImplementation |
RequesterB2BCSImplementation |
AIA/Service/ImplementationDetails/ServiceOperation/Name |
<Verb><EBOName> |
ProcessSalesOrder |
AIA/Service/ImplementationDetails/B2BDocument |
B2B Document Type processed by this B2BCS |
850 |
AIA/Service/ImplementationDetails/B2BDocumentVersion |
B2B Document Version processed by this B2BCS |
4010 |
AIA/Service/ImplementationDetails/B2BStandard |
B2B Standard processed by this B2BCS |
X12 |
AIA/Service/ImplementationDetails/B2BStandardVersion |
B2B Standard Version processed by this B2BCS |
4010 |
The following XML snippet, as shown in Figure 20-14, is an example of an annotated B2BCS called X12ProcessSalesOrderReqB2BCSImpl composite.xml.
The reference to the AIA EBS invoked by this B2BCS should also be annotated in the composite.xml. Annotation elements are listed in Table 20-3.
Table 20-3 composite.xml Annotations Used to Reference the AIA EBS Invoked by the B2BCS
Annotation Element | Description | Example |
---|---|---|
AIA/Reference/ArtifactType |
Enter value "EnterpriseBusinessService" |
EnterpriseBusinessService |
AIA/Reference/ServiceOperation/Name |
EBS operation name |
ProcessSalesOrder |
Annotations as they appear in composite.xml are shown in Figure 20-15.
For your reference, the $AIA_HOME/Infrastructure/B2B/src/B2BConnectors/EDIX12B2BCSApp/X12Process SalesOrder ReqB2BCSImpl/composite.xml file contains sample Requester B2BCS Impl annotations.
Support for Trading Partner-specific processing can be built into the requester B2BCS in a manner similar to the way they are built into the provider B2BCS.
For more information about how to build trading partner-specific support in B2BCSs, see Section 19.3.8, "How to Support Trading Partner-Specific Variants."
For more information about how to enable AIA services for error handling and recovery, see "Setting Up Error Handling" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.
In short, the following steps must be taken:
Associate a fault-policy.xml with the B2BCS composite.
Invoke the AIAAsyncErrorHandlingBPELProcess for business faults, as shown in Figure 20-16 and Figure 20-17.
While invoking the AIAAsyncErrorHandlingBPELProcess, the B2B-specific elements in the fault schema can be populated as shown in Table 20-4.
Table 20-4 B2B-Specific Elements in the Fault Schema That Can Be Populated by AIAAsyncErrorHandlingBPELProcess
Fault Element Schema | Description | Example |
---|---|---|
Fault/B2BMReference/B2BMID |
Unique identifier of the B2B document |
13232325 |
Fault/B2BMReference/B2BDocumentType/TypeCode |
Document type of the B2B document being processed by the requester B2BCS |
855 |
Fault/B2BMReference/B2BDocumentType/Version |
Document version of the B2B document being processed by the Requester B2BCS |
4010 |
Fault/B2BMReference/B2BDocumentType/TypeCode/@listAgencyID |
Standard of the B2B document being processed by the Requester B2BCS |
X12 |
Fault/B2BMReference/GatewayID |
Name of the B2B software being used. |
Oracle B2B |
Fault/B2BMReference/SenderTradingPartner/TradingPartnerID |
Sender trading partner, mapped from the B2BM |
MyCompany |
Fault/B2BMReference/ReceiverTradingPartner/TradingPartnerID |
Receiver trading partner, mapped from the B2BM |
Global |
Figure 20-18 provides the B2B-specific elements in the corecom:Fault.
The B2B details of the failed AIA service now available in the fault instance will be logged and available for debugging the failed flow.
The next step, as shown in Figure 20-19, is to develop a new EBS or use an existing EBS that is invoked by the requester B2BCS.
For more information about creating a new EBS, see Chapter 12, "Designing and Developing Enterprise Business Services."
The next step, as shown in Figure 20-20, is to develop a new or extend an existing provider ABCS. The provider ABCS processes the AIA EBM by invoking application APIs or web-services.
For more information about how to design and construct a provider ABCS, see Chapter 13, "Designing Application Business Connector Services" and Chapter 14, "Constructing the ABCS."
While you are developing this transformation from EBM to ABM, the Sender and Receiver Trading Partner information can be mapped to appropriate fields in the ABM to capture the source and target of the B2B message, as shown in Table 20-5.
Table 20-5 Sender and Receiver Trading Partner Fields in the EBM
EBM Header Element | Description | Example Value |
---|---|---|
/EBMHeader/B2BProfile/SenderTradingPartner/TradingPartnerID |
ID of the sending trading partner as defined in Oracle B2B. For inbound flows, this is the remote trading partner. |
GlobalChips |
/EBMHeader/B2BProfile/ReceiverTradingPartner/TradingPartnerID |
ID of the receiving trading partner as defined in Oracle B2B. For inbound flows, this is the host trading partner. |
Acme |
At the end of this step, all of the required AIA services for developing an outbound B2B integration flow are ready.
The next step, as shown in Figure 20-21, is to create trading partner agreements in Oracle B2B.
For more information about how to define trading partners and associate B2B capabilities with them, see "Configuring Trading Partners" in Oracle Fusion Middleware User's Guide for Oracle B2B.
In addition, for EDI-based outbound B2B flows, Oracle B2B can be configured for batch processing of outbound documents. Parameters such as the batch size and time-out can be configured in Oracle B2B without having to make any changes to the AIA layer.
The next step, as shown in Figure 20-22, is to deploy the AIA services. You can deploy the services to a target Oracle SOA server using Oracle JDeveloper.
If any domain value mapping (DVM) and configuration files are used by the AIA services required for the outbound integration, you must enter data corresponding to your B2B configuration.
You can also use the Project Lifecycle Workbench application to create a bill of material XML file for the AIA project, which can be used to autogenerate a deployment plan. This deployment plan can be used to deploy all of the AIA services and resources that make up the integration project in multiple development, test, and production environments.
For more information about generating bills of material, see Chapter 3, "Working with Project Lifecycle Workbench."
For more information about generating deployment plans, see Chapter 8, "Generating Deployment Plans and Deploying Artifacts."
In addition, configure the AIA Error Handling framework and set up appropriate roles to be notified of errors in AIA flows.
For more information about error handling, see "Setting Up Error Handling" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.
The next step, as shown in Figure 20-23, is to test and verify. Before you go live with your B2B integration flows with your trading partners, we recommend that you complete a sequence of tests for your newly developed or deployed AIA services, which make up the B2B integration flow.
For more information, see Section 19.8, "Step 7: Testing and Verifying."
The final step, as shown in Figure 20-24, is to go live with your trading partner for the outbound B2B document flow. The AIA and Oracle B2B deployments are duplicated in the product servers and rolled out to the end users.
For more information, see Section 19.9, "Step 8: Going Live and Monitoring."