| 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 |
| 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 includes the following sections:
Section 19.1, "Introduction to Developing and Implementing Outbound B2B Integration Flows"
Section 19.2, "Step 1: Identifying the B2B Document and Analyzing Requirements"
Section 19.3, "Step 2: Developing a New Provider B2B Connector Service"
Section 19.4, "Step 3: Developing or Extending an Existing Enterprise Business Service"
Section 19.5, "Step 4: Developing or Extending an Existing Requester ABCS"
Section 19.6, "Step 5: Configuring Oracle B2B and Defining Trading Partner Agreements"
Section 19.7, "Step 6: Deploying and Configuring AIA Services"
Figure 19-1 shows the high-level steps involved in developing a simple outbound business-to-business (B2B) flow from an application to trading partners using Oracle Application Integration Architecture (AIA).
Each of the steps listed in this diagram are described in detail in the following sections.
This section includes the following topics:
Section 19.2.2, "How to Identify the B2B Document Type and Definition"
Section 19.2.5, "How to Identify the EBO, EBS, and EBM to Be Used"
Section 19.2.6, "How to Design Mappings for the B2B Document"
Section 19.2.7, "How to Publish Mapping to Trading Partners"
The first step in building an outbound B2B flow is to identify the B2B document that needs to be generated by the flow. As a part of this step, as shown in Figure 19-2, you must also analyze the requirements for the AIA services that need to be built or extended to support the flow.
As a part of this step, the integration development team performs the following tasks:
Identify the B2B document protocol to be used.
Identify the B2B document type to be used.
Define the B2B document in Oracle B2B.
Define the B2B document in AIA.
Identify the AIA Enterprise Business Object (EBO), Enterprise Business Message (EBM), and Enterprise Business Service (EBS) to be used.
Identify the message exchange pattern.
Map the EBM, B2B document, and Application Business Message (ABM).
Document and publish the mapping.
To develop a B2B flow, you first identify the B2B document to be used. Often, the choice of B2B document is influenced by the capabilities of the trading partners or e-commerce hub that needs to be integrated with your applications.
However, if you have the choice to choose a B2B document definition to be used for a particular integration use case, several industry-standard e-commerce standards exist today that vary in popularity in different geographies and industries.
Examples of B2B document protocols are Open Applications Group Integration Specification (OAGIS), Electronic Data Interchange (EDI) X12, Electronic Data Interchange For Administration, Commerce and Transport (EDIFACT), Health Insurance Portability and Accountability Act (HIPAA), EANCOM, RosettaNet, Universal Business Language (UBL), Health Level 7 (HL7), and 1SYNC.
Consider the following questions when choosing a B2B document protocol to integrate with your trading partners:
Does the document protocol have the list of documents to support your integration needs?
Does the document protocol have adequate support for your industry?
Is the document protocol supported by your key trading partners?
Is the document protocol popular in your geography?
Is the document protocol based on open standards such as XML and XML Schema?
Is the protocol support by your vendor, for example, Oracle?
Along with the B2B document protocol, the version of the B2B document must also be determined. Similar considerations as listed previously can be used to determine the B2B document protocol version.
Once you have selected the B2B document protocol, the next task is to identify the B2B document that meets the specific B2B integration need. Each document protocol supports a list of B2B documents or document types. Refer to the protocol documentation and document usage guidelines to identify the specific document that is best-suited to support your specific business flow. Document usage can vary by industry and geography.
For example, assume that you need to implement a B2B flow to send purchase orders electronically to your supplier as part of your procurement business flow. Assume that the EDI X12 is chosen as the B2B document protocol based on your integration needs. The EDI X12 document protocol recommends that the 850 (Order) document be used for this integration requirement.
After the B2B protocol, document, and version are identified, you must obtain official versions of the following artifacts related to the document:
Documentation and usage guidelines, which describe the B2B document in detail, including individual elements.
Sample XML instances, which illustrate the usage of the B2B document.
XML Schema definition of the B2B document.
For XML-based B2B document protocols, internet resources pertaining to the standard can be used as the source for downloads of the official user documentation, XML schemas, and sample document instances. For example, the OAGIS website (www.oagi.org) provides all of this information for every major release of the OAG document standards.
You can also obtain the official artifacts listed previously as a part of the B2B Document Editor software, which is part of Oracle Fusion Middleware.
For more information about creating guideline files, see "Creating Guideline Files" in Oracle Fusion Middleware User's Guide for Oracle B2B.
For non-XML protocols such as EDI and flat-file, Oracle B2B provides translation capabilities to convert the documents from non-XML formats to XML. However, this XML is an intermediate XML definition of the B2B document, which still needs to be transformed to the AIA EBM. You can export the B2B document in Oracle B2B Integration format using the B2B Document Editor to obtain the XML schema representation of this intermediate XML for use with the AIA B2B Connector Service (B2BCS).
Supporting Document Variations
As an integration best practice, we recommend that the standard B2B document definition be used as-is for B2B integration. Frequently, however, the B2B document definition must be modified to accommodate additional elements to meet custom integration requirements.
If such variations to the published standard are required, then the B2B document guideline and schemas obtained in the previous step must be modified to include these additional details.
Once you have identified the B2B document type and definition, you must define the document in Oracle B2B. This is a prerequisite to using these documents in trading partner agreements.
For more information about creating document definitions, see "Creating Document Definitions" in Oracle Fusion Middleware User's Guide for Oracle B2B.
Per AIA integration best-practice recommendations, all reusable SOA artifacts, such as XML Schema and WSDL files, are hosted centrally in the SOA metadata store. Centrally hosting reusable artifacts and referencing them from the AIA services helps improve the performance and ease-of-maintenance of AIA services. The SOA metadata store provides caching and clustering capabilities that are also leveraged when we use it as the central store.
The XML schema definitions of B2B documents that are used by the B2B connector services are also hosted in the metadata store.
To deploy the B2B documents to the metadata store:
Create a directory that corresponds to the B2B standard in the B2BObjectLibrary.
Copy the XML schema files and directories that define the B2B document types to this location.
The B2BObjectLibrary directory is a child directory of $AIA_HOME/MetaData/AIAMetaData/AIAComponents.
For example, as shown in Figure 19-3, create directory OAGIS to which to copy OAG business object definitions.
Copy the XML schema files that correspond to the B2B document type under this folder.
For example, as shown in Figure 19-4, copy the OAGIS ProcessPurchaseOrder.xsd file and all of its supporting schemas to this folder location, while also preserving the relative directory structure.
Deploy the new contents of the B2B Object Library to the SOA metadata store. To do this:
Edit the $AIA_HOME/config/UpdateMetaDataDeploymentPlan.xml file, as shown in Figure 19-5, to specify that the directory B2BObjectLibrary has to be updated in Oracle Metadata Services (MDS).
Source the file aiaenv.sh located under $AIA_HOME/bin. For example: $source /slot/ems5813/oracle/AIA3_HOME/bin/aiaenv.sh
Change the directory to $AIA_HOME/Infrastructure/Install/config. For example: $cd $AIA_HOME/Infrastructure/Install/config.
Issue the AIA command to deploy the metadata. For example: $ant -f UpdateMetadata.xml.
Verify that the command was successful and that no errors occurred.
To be able to integrate the B2B documents using AIA, the next step is to identify the AIA EBO, EBM, and EBS to be used. Select the AIA EBO and EBM for which the description most closely matches the B2B document to which you need to integrate.
For example, to develop an outbound B2B integration flow in which EDI 850 (Order) documents need to be communicated to a supplier by a procurement application, you can use the following EBO, EBM, and EBS:
EBO: PurchaseOrderEBO
EBM: CreatePurchaseOrderEBM
EBS operation: CreatePurchaseOrder
The next step is to analyze your business requirements and map the ABM to the EBM and the EBM to the B2B document.
Consider the following guidelines while developing mappings for B2B documents:
Identify and clearly list the subset of target B2B document elements to which you need to map based on your integration needs.
Document and publish the list of B2B elements being mapped. For each element being mapped, document the following information:
Data type
Cardinality
Example value
Description
DVM name and columns used
Mandatory indicator
Consider the following guidelines while mapping identification and reference components in the B2B documents:
Map universal identifiers if available and supported by your application. For example, map UPC codes for identifying Items and UDEX codes for identifying Item Categories.
Map all available external identifiers used by your trading partners. For example, map the Vendor Part Number in outbound B2B documents that need to be sent to your vendors.
Map free-form attributes such as Description, Notes, Attachments, and so forth to enable users to communicate and provide more information to trading partners.
While mapping reference components, map content from the referenced entity and not just the identification. For example, if a Ship To Location has to be mapped in an outbound Purchase Order document being sent to a supplier, in addition to the location identifiers, map the actual postal address and contact details of the Ship To Location.
While mapping Identification type components, you can directly map the actual application IDs to the B2B document. This is unlike the application-to-application (A2A) use case in which an XREF is used to store the mapping between the participating application identifiers and the AIA identifiers.
For example, assume that you are working with a SyncItem from an Inventory system to a trading partner. Assume that ITEM_001 is the item identifier in the source ABM. This value can be directly mapped as-is to the Identification element. Using an XREF has little additional value because the ID generated in the trading partner application as a result of the sync flow will not be captured in the XREF. A direct mapping is preferable instead.
Map ahead of current requirements. Even if your current integration use case may require that only a few elements be mapped, a best-practice recommendation is to map all the available fields that can be processed by your application. This allows the connectors to be reused for multiple use cases.
Extend EBOs, if required. If the target B2B document contains attributes that need to be mapped, but that are not available in the EBO, extend the EBO to include the target elements and map them.
Capture the mapping in an easy-to-understand spreadsheet and keep it current when any changes need to be made.
The next step is to share the mapping document with trading partners. This enables your trading partners to make any changes needed in their internal system to process outbound B2B documents received from you. Also, any feedback received from your trading partners can be used to revise the mapping design.
This section includes the following topics:
Section 19.3.1, "Introduction to a Provider B2B Connector Service"
Section 19.3.2, "How to Identify the Message Exchange Pattern"
Section 19.3.4, "How to Store a WSDL in the Oracle Metadata Repository"
Section 19.3.8, "How to Support Trading Partner-Specific Variants"
The next step, as shown in Figure 19-6, is to develop the provider B2BCS to support the outbound B2B integration flow.
The provider B2BCS is very similar to a provider 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 ABCS (requester and provider) as well.
The key functionality provided by a provider B2BCS is to enable outbound B2B document integration by performing the following tasks:
Transforming AIA EBMs into B2B documents.
Invoking Oracle B2B to send these B2B documents to trading partners.
Figure 19-7 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.
Most B2B document flows can be modeled as asynchronous one-way calls.
For example, consider a use case in which a purchase order created in a Procurement application needs to be sent to a supplier using an outbound B2B document flow. Upon receipt of this Purchase Order document, the supplier processes it and sends back a Purchase Order Acknowledgement B2B document.
In this use case, even if a response is expected from the supplier in the form of the Purchase Order Acknowledgement document, the Procurement application can continue with its processing, which involves the purchase order being communicated to and processed by the vendor.
The Procurement application also generally can correlate the Purchase Order Acknowledgement document to the original purchase order because the Vendor is expected to provide the same purchase order identification used in the request in the Acknowledgement message. In this way, the request and response can be modeled as two asynchronous one-way flows.
However, a similar analysis must be performed for each B2B document flow being designed.
For more information about identifying message exchange patterns, see Section 13.3, "Identifying the MEP."
First, define the service contract (WSDL) of the provider B2BCS. The service contract of the provider B2BCS specifies how it is invoked by an AIA flow. The service contract specifies the EBS operation being implemented, the input request type, and the message exchange pattern supported by the B2BCS.
For more information about creating WSDLs for ABCSs, see Section 13.2, "Defining the ABCS Contract."
Here are the recommended naming conventions for use in B2BCS WSDL definitions.
WSDL File Name:
Naming guideline: <B2BStandard><Verb><EBO>ProvB2BCSImpl.wsdl
Example: X12UpdateSalesOrderProvB2BCSImpl.wsdl
Service Namespace:
Naming guideline: http://xmlns.oracle.com/B2BCSImpl/{Core|Industry/<IndustryName>}/<B2BStandard><Verb><EBO>ProvB2BCSImpl/<ABCSVersion>
Example: http://xmlns.oracle.com/B2BCSImpl/Core/X12UpdateSalesOrderProvB2BCSImpl/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>ProvB2BCSImpl
Example: X12UpdateSalesOrderProvB2BCSImpl
Port Type Name:
Naming guidelines: <B2BStandard><Verb><EBO>ProvB2BCSImplService
Example: X12UpdateSalesOrderProvB2BCSImplService
Operation Name:
Naming guideline: <Verb><EBO>
Example: UpdateSalesOrder
Request Message Name:
Naming guideline: <Verb><EBO>ReqMsg
Example: UpdateSalesOrderReqMsg
Request Message WSDL part element:
Naming guideline: <EBM>
Example: <wsdl:part name="UpdateSalesOrderEBMelement=" salesordebo: UpdateSalesOrderEBM"/>
Imported Schemas:
Naming guideline:
oramds:/apps/AIAMetaData/AIAComponents/EnterpriseObjectLibrary/ Core/Common/V2/Meta.xsd
oramds:/apps/AIAMetaData/AIAComponents /B2BObjectLibrary/ <B2BMessageSchema>
oramds:/apps/AIAMetaData/AIAComponents /EnterpriseObjectLibrary/ <EBM Schema>
Example:
oramds:/apps/AIAMetaData/AIAComponents/EnterpriseObjectLibrary/ Core/Common/V2/Meta.xsd
oramds:/apps/AIAMetaData/AIAComponents/EnterpriseObjectLibrary/ Core/EBO/SalesOrder/V2/SalesOrderEBM.xsd
oramds:/apps/AIAMetaData /AIAComponents/B2BObjectLibrary/ X12/4010/Oracle/855_4010.xsd
Imported WSDLs:
Naming guideline: oramds:/apps/AIAMetaData/AIAComponents/ UtilityArtifacts/RuntimeFault.wsdl
Example: oramds:/apps/AIAMetaData/AIAComponents/UtilityArtifacts/ RuntimeFault.wsdl
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 Oracle Metadata Services (MDS). Storage of shared artifacts in 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 in the following location in MDS: /apps/AIAMetaData/AIAComponents/B2BServiceLibrary/Connectors/wsdls/ <B2B_STANDARD> /ProviderB2BCS/ <VERSION> / <B2B_STANADRD> <VERB> <OBJECT> ReqB2BCSImpl.wsdl
To store a WSDL in MDS:
Copy the handcrafted WSDL to the following location under AIA_HOME: $AIA_HOME/aia_instances/$INSTANCE_NAME/AIAMetaData/AIAComponents/B2BServiceLibrary/Connectors/wsdls/ <B2B_STANDARD> /ProviderB2BCS/ <VERSION> / <wsdl file> .wsdl
Run the UpdateMetaDataDP.xml present at $AIA_HOME/aia_instances/$INSTANCE_NAME/config/UpdateMetaDataDP.xml.
Using a SOA-MDS server connection to the MDS, verify that the AIAMetadata has been populated, as shown in Figure 19-8.
You can now access the WSDL using a URL similar to the following: oramds:/apps/AIAMetaData/AIAComponents/B2BServiceLibrary/Connectors/wsdls/EDI_X12/ProviderB2BCS/V1/ X12UpdateSalesOrderProvB2BCSImpl.wsdl
The next step in the process is to develop the B2BCS. The provider B2BCS WSDL created in the previous step is used as the interface while you are developing the concrete B2BCS.
Because the 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 B2BCS:
Define variable <EBM>_Var.
This is the input variable to the BPEL process and is used in the receive activity.
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 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 variable <B2BDoc>B2BM_Var of type corecom:B2BM.
This variable is used as input to the AIAB2BInterface to send the outbound B2B document to Oracle B2B.
Define variable <B2BDoc>_Var using the external B2BDocument definition.
This is used as the target of the transformation from EBM. This variable is then assigned to the <B2BDoc>B2BM_Var/Payload.
Define the partner link to the AIAB2BInterface.
This service is invoked to send the B2B document to trading partners via Oracle B2B. The abstract WSDL to the AIAB2BInterface can be referenced from oramds:/apps/AIAMetaData/AIAComponents/B2BServiceLibrary/Infrastructure/wsdls/V1/B2BInterfaceV1.wsdl.
Assign the EBM_HEADER variable.
Assign values of the EBM_HEADER local variable by copying all the values from the <input>EBM/EBMHeader element.
Assign the B2BM_HEADER variable.
Assign the values as shown in Table 19-1.
Table 19-1 B2BM_HEADER Variable Assignment Values
| Element | Value | Example |
|---|---|---|
|
B2BMHeader/B2BMID |
Map value from the EBMHeader/EBMID to the field. |
111A1CD2121 |
|
B2BMHeader/B2BDocumentType/TypeCode |
Populate with the B2B document type as defined in Oracle B2B. |
X12_850 |
|
B2BMHeader/B2BDocumentType/Version |
Populate with the B2B document revision configured in Oracle B2B. |
4010 |
|
B2BMHeader/SenderTradingPartner/TradingPartnerID |
Populate with value from the input EBM. / <XXX> EBM/EBMHeader/B2BProfile/SenderTradingPartner/TradingPartnerID |
Acme |
|
B2BMHeader/ReceiverTradingPartner/TradingPartnerID |
Populate with value from input EBM. / <XXX> EBM/EBMHeader/B2BProfile/ReceiverTradingPartner/TradingPartnerID |
GlobalChips |
Transform the EBM into the B2B document.
Use a transform activity to transform the EBM into the B2B Document format. Invoke an XSLT developed per the mapping created in the previous step.
Assign <B2BDoc>B2BM_Var.
Assign values to the <B2BDoc>B2BM_Var as shown in Table 19-2.
Invoke AIAB2BInterface.
Invoke the AIAB2BInterface to send the document to trading partners. Use the <B2BDoc>B2BM_Var assigned in the previous step as input to the AIAB2BInterface.
Invoke activity parameters as shown in Table 19-3.
Compile the BPEL process and ensure that no errors occur. You can use JDeveloper to deploy the BPEL process to a development server that is installed with AIA Foundation Pack.
Test the service by using sample EBM payloads as input.
As described previously in this document, the AIA B2B Interface is a reusable composite that can be used to integrate the B2B Connector Services with Oracle B2B. The AIA B2B Interface uses JMS-based internal delivery channels to integrate with Oracle B2B.
The AIA B2B Interface is a unified interface between the AIA and Oracle B2B layers for all B2BCSs. It supports operations to send B2B documents to Oracle B2B and receive B2B documents from Oracle B2B. The benefits of using the AIA B2B Interface to integrate with Oracle B2B are as follows.
If the choice of internal delivery channel to be used for communication between B2B and AIA/SOA has to be changed at a later stage in the implementation, the B2BCS code need not be modified.
If you are using legacy or third-party B2B software, the AIA B2B Interface can be customized to add routing rules to send B2B documents to this legacy software. The B2BM_Var//B2BMHeader/GatewayID can be used as a filter expression to choose between Oracle B2B and third-party B2B software as the target for outbound documents. This allows the B2BCS to be shielded from change irrespective of the choice of B2B software.
Because this service is invoked by all outbound B2B document flows, you can customize this composite to support any common outbound functionality, such as audit logging, Oracle Business Activity Monitoring (BAM) instrumentation, and so forth.
Figure 19-9 illustrates the use of the AIA B2B Interface to support custom internal delivery channels (file) and legacy B2B connectivity.
Figure 19-9 AIA B2B Interface Support for Custom Internal Delivery Channels and Legacy B2B Connectivity
For example, you might have outbound Order documents being routed to a Fusion Middleware Oracle B2B component, and outbound Invoice documents being routed to an older B2B instance. To support this use case, define two routing rules: one for JMS invocation of Oracle B2B and another for Oracle Advanced Queuing invocation of the older B2B instance.
Note that a given B2B document instance is likely to be routed to B2B using one of the multiple routing rules in the ProcessB2BDocument.mplan. In the highly unlikely event that a B2B document generated by the AIA layer needs to be routed to multiple B2B software instances, the routing rules in the ProcessB2BDocument.mplan mediator should be configured for sequential invocation.
To make customizations to the AIA B2B Interface:
Open the SOA application, $AIA_HOME/Infrastructure/B2B/src/AIAB2BInterfaceApp, using Oracle JDeveloper.
Edit the AIAB2BInterface/composite.xml file using the Composite Editor, as shown in Figure 19-10.
Add a new adapter or web-service call required to interface to the third-party B2B software, as shown in Figure 19-11.
Modify the AIAB2BInterface/ProcessB2BDocument.mplan file to add custom routing rules to route outbound B2B documents to third-party B2B software, as shown in Figure 19-12 and Figure 19-13.
Use a condition expression, as shown in Example 19-1, on the GatewayID element to identify which B2B documents need to be routed to the third-party B2B software.
Use a transformation step, assign step, or both, as required to provide input to the B2B software based on the input B2BM variable, ($in), as shown in Figure 19-14. Note that support for Oracle B2B is prebuilt and does not require any modifications.
The input B2BM variable is received from the provider B2BCSs. Table 19-4 provides the information from the B2BM variable that can be used to provide input to the B2B software.
Table 19-4 B2BM Variable Information That Can Be Used to Provide Input to B2B Software
| Input Element | Description | Usage While Integrating with Oracle B2B |
|---|---|---|
|
$in.B2BM/B2BMHeader/SenderTradingPartner/ TradingPartnerID |
Sending trading partner in outbound flow. |
Map to: JMSProperty.FROM_PARTY |
|
$in.B2BM/B2BMHeader/ReceiverTradingPartner/ TradingPartnerID |
Receiving trading partner in outbound flow. |
Map to: JMSProperty.TO_PARTY |
|
$in.B2BM/B2BMHeader/B2BDocumentType/TypeCode |
B2B Document Type used in the outbound flow. For example, 850. |
Map to: JMSProperty. DOCTYPE_NAME |
|
$in.B2BM/B2BMHeader/B2BDocumentType/Version |
B2B Document Type version used in the outbound flow. For example, 4010. |
Map to: JMSProperty. DOCTYPE_REVISION |
|
$in.B2BM/B2BMHeader/B2BDocumentType/TypeCode/ listAgencyID |
B2B standard used in the outbound flow. For example, X12. |
Not used. |
|
$in.B2BM/B2BMHeader/B2BMID |
Unique B2B document identifier. Unique across all trading partners. |
Map to: JMSProperty.MSG_ID |
|
$in.B2BM/B2BMHeader/Payload |
Actual payload being sent to trading partners. |
JMS text payload |
The B2BCS is responsible for supplying the value of the GatewayID element to ensure that the desired value of the GatewayID is supplied before the AIAB2B Interface is invoked.
Save changes. Compile, test, and redeploy the AIA B2B Interface.
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 B2B Connector Services:
Table 19-5 lists the annotation elements that must be added to the service element composite.xml, as described subsequently.
Table 19-5 Service Annotation Elements in composite.xml
| Annotation Element | Description | Example |
|---|---|---|
|
AIA/Service/InterfaceDetails/ServiceName |
Name of EBS implemented by this provider B2BCS Impl |
SalesOrderEBS |
|
AIA/Service/InterfaceDetails/Namespace |
Namespace of EBS implemented by this provider B2BCS Impl |
http://xmlns.oracle.com/EnterpriseServices/Core/ SalesOrder/V2 |
|
AIA/Service/InterfaceDetails/ArtifactType |
EnterpriseBusinessService |
EnterpriseBusinessService |
|
AIA/Service/InterfaceDetails/Service Operation |
<Verb><EBOName> |
UpdateSalesOrder |
|
AIA/Service/ImplementationDetails/ArtifactType |
ProviderB2BCSImplementation |
ProviderB2BCSImplementation |
|
AIA/Service/ImplementationDetails/ServiceOperation/Name |
<Verb><EBOName> |
UpdateSalesOrder |
|
AIA/Service/ImplementationDetails/B2BDocument |
Target B2B Document Type of this B2BCS |
855 |
|
AIA/Service/ImplementationDetails/B2BDocumentVersion |
Target B2B Document Version of this B2BCS |
4010 |
|
AIA/Service/ImplementationDetails/B2BStandard |
Target B2B Standard of this B2BCS |
X12 |
|
AIA/Service/ImplementationDetails/B2BStandardVersion |
Target B2B Standard Version of this B2BCS |
4010 |
The following XML snippet, as shown in Figure 19-15, is an example of an annotated B2BCS called X12ProcessSalesOrderReqB2BCSImpl composite.xml.
Table 19-6 lists AIA B2B interface utility service annotation elements in composite.xml.
Table 19-6 AIA B2B Interface Utility Service Annotation Elements in composite.xml
| Annotation Element | Description |
|---|---|
|
|
Enter value |
|
|
Enter value |
The reference to the AIA B2B Interface utility service should be annotated in the composite.xml, as shown in Figure 19-16.
The $AIA_HOME/Infrastructure/B2B/src/B2BConnectors/EDIX12B2BCSApp/X12Update SalesOrder ProvB2BCSImpl/composite.xml file has sample provider B2BCS Impl annotations for your reference.
This section includes the following topics:
Section 19.3.8.1, "Supporting Trading Partner-Specific Custom Extensions"
Section 19.3.8.2, "Supporting Trading Partner-Specific XSLTs"
Section 19.3.8.3, "Supporting Trading Partner-Specific Document Types and Versions"
Frequently, in B2B implementations different trading partners need to support different versions or mapping guidelines for the same B2B document. If a given B2B document needs to be sent to multiple trading partners, based on the version and mapping guideline determined for that trading partner, the B2BCS of the document can be built to support this trading partner-specific transformation logic. Multiple ways are available by which this can be achieved, as described in the following section.
If the trading partner-specific mappings are an addition to a common core mapping that remains unchanged, explore the possibility of using the custom XSLT template calls to have partner-specific mappings.
For more information about support for XSLT extension using callouts to custom XSLT templates, see Section 15.1, "Developing Extensible ABCS."
In short, at the end of every business component mapped in the XSLT file, an invocation to a custom XSLT template is made from the shipped B2BCSs, as shown in Figure 19-17.
Figure 19-17 Business Component Mapped in the XSLT, including an invocation from the Shipped B2BCS to a Custom XSLT template
The custom XSLT templates are defined in a custom XSLT file, as shown in Figure 19-18, which is included in the main XSLT.
During implementation, you can add additional mappings to this custom XSLT file. The trading partner ID can be passed as an input to the custom XSLT template call and can be used to conditionally map to target B2B elements, as shown in Figure 19-19.
If the trading partner-specific mappings conflict with each other or if the partner-specific mappings need to be added at arbitrary locations in the XML document and not just at the end of each mapping template, the previous approach of using the custom XSLT templates to define partner-specific mappings will not meet requirements.
To meet such requirements, you can decide to develop one XSLT file for each trading partner that needs custom mappings. You can make a copy of a shipped XSLT file, edit it to include partner-specific mapping logic, and save it by using a partner prefix in the filename, as shown in Figure 19-20.
Figure 19-20 Copies of Shipped XSLT Files Edited to Include Partner-Specific Mapping Logic and Saved Using a Partner Prefix in the Filename
Next, you can define a configuration file that contains information about which XSLT file has to be used for each trading partner. For example, you can use a domain value mapping (DVM) file to store this configuration information, as shown in Figure 19-21.
In the provider B2BCS Impl BPEL process, as shown in Figure 19-22, you can do a lookup on this DVM file, as shown in Figure 19-23, to obtain the XSLT filename, as shown in Figure 19-24.
Along with the need for trading partner-specific XSLTs, a different Document Type may possibly need to be used in Oracle B2B for defining the trading partner agreements for the same external B2B document.
For example, trading partner Global might need the 5010 version of the X12 855 B2B document and trading partner ABC Corp might need the 4010 version of the same document.
Using the approach described in the previous section, you can use the same provider B2BCS Implementation to generate B2B documents for both the trading partners.
However, while the AIA B2B Interface is being invoked based on the trading partner involved for the specific instance of the service, the corresponding B2B document version must be specified, 4010 for Global and 5010 for ABC Corp, for example.
To support these requirements, use a DVM file similar to the one used in the previous approach to store the B2B Document Type and Document Revision information for each trading partner, as shown in Figure 19-25. This information can be looked up by the BPEL process to populate the /B2BMHeader/B2BDocumentType/TypeCode and /B2BMHeader/B2BDocumentType/Version attributes.
While the configuration files described previously can be created and stored locally within the Oracle JDeveloper project, a best-practice recommendation is to externalize these files, store them in MDS, and refer to them from your B2BCS Implementation BPEL project using oramds lookup.
Note that though this approach of using DVM files to store the B2B document preference and trading partner-specific transformation information works, the Trading Partner information between the application and these DVM files must be kept synchronized.
Each time a new trading partner is defined in the application, a corresponding record should be created in this DVM to store the B2B document preference of the trading partner. A well-established administrative process to manage these changes should be available.
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 19-26 and Figure 19-27.
While invoking the AIAAsyncErrorHandlingBPELProcess, the following B2B-specific elements in the fault schema can be populated as described in Table 19-7.
Table 19-7 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 generated by the provider B2BCS |
855 |
|
Fault/B2BMReference/B2BDocumentType/Version |
Document version of the B2B document being generated by the provider B2BCS |
4010 |
|
Fault/B2BMReference/B2BDocumentType/TypeCode/@listAgencyID |
Standard of the B2B document being generated by the provider B2BCS |
X12 |
|
Fault/B2BMReference/GatewayID |
Name of the B2B software being used |
Oracle B2B |
|
Fault/B2BMReference/SenderTradingPartner/TradingPartnerID |
Sender trading partner, mapped from the EBMHeader |
MyCompany |
|
Fault/B2BMReference/ReceiverTradingPartner/TradingPartnerID |
Receiver trading partner, mapped from the EBMHeader |
Global |
Figure 19-28 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 19-29, is to develop a new EBS or extend an existing EBS to invoke the provider B2BCS developed in the previous step. For example, the UpdateSalesOrderEBS has to be developed or modified to invoke the X12UpdateSalesOrderProvB2BCSImpl process.
For more information about creating a new EBS, see Chapter 12, "Designing and Developing Enterprise Business Services."
A B2B implementation may possibly exist in which different trading partners may require that the same EBM information be sent using different B2B document protocols.
For example, suppliers XLS Inc., New Networks, and Office Systems may require that new purchase orders be sent using the OAG Process Purchase Order document format, while suppliers ABC Inc. and Global may require that new purchase orders be sent using the X12 850 document format.
To support the needs of this implementation, two B2BCSs must be developed, as shown in Figure 19-30:
OAGCreatePurchaseOrderB2BCSImpl, which transforms the CreatePurchaseOrderEBM into an OAG Process Purchase Order B2B document.
X12CreatePurchaseOrderB2BCSImpl, which transforms the CreatePurchaseOrderEBM into an X12 850 B2B document.
The CreatePurchaseOrderEBM implementation must include routing rules to invoke both of these B2BCSs.
Figure 19-30 B2B Implementation in which Trading Partners Need the Same EBM Data Sent Using Different B2B Document Protocols
If a small number of trading partners are involved, the filter expression in the EBS routing rules to each of the B2BCSs can be used to route the EBM based on the trading partner involved, as shown in Figure 19-31.
Figure 19-31 Filter Expression in the EBS Routing Rule to Each B2BCS Used to Route the EBM Based on the Trading Partner
However, if a large number of trading partners are involved, the trading partner's B2B preferences can be stored in an external configuration file, for example, in a DVM file, as shown in Figure 19-32.
This configuration can be looked up during run time by the EBS implementation to determine the target provider B2BCS to be invoked, as shown in Figure 19-33.
Note that though this approach works, a need exists to keep the trading partner information between the application and these DVM files synchronized.
Each time a new trading partner is defined in the application, a corresponding record should be created in this DVM to store the B2B document preference of the trading partner. A well-established administrative process to manage these changes should exist.
This section includes the following topics:
Section 19.5.1, "What You Need to Know About Message Exchange Patterns"
Section 19.5.2, "What You Need to Know About Transformations"
The next step, as shown in Figure 19-34, is to develop a new requester ABCS or extend an existing requester ABCS.
The requester ABCS is the AIA service that is triggered from an application UI action or business event and is the first step in the outbound B2B flow. The requester ABCS acts on behalf of the triggering application in the AIA layer and invokes the AIA EBS.
For more information about how to design and construct a requester ABCS, see Chapter 13, "Designing Application Business Connector Services" and Chapter 14, "Constructing the ABCS."
The requester ABCS always invokes an EBS implementation and hence can be used in both A2A and B2B integration scenarios. It is a best-practice recommendation to anticipate that the requester ABCSs can be potentially used both in A2A and B2B integration scenarios.
Consider the following information when developing requester ABCSs to be used in B2B integration flows.
B2B integration flows are primarily processed asynchronously. Thus, while evaluating the message exchange pattern for developing new requester ABCSs, you should consider the possibility of their being used in B2B flows.
One of the key tasks of the requester ABCS is to transform the ABM into the canonical EBM and use the EBM as input to invoke the AIA EBS.
While developing this transformation from ABM to EBM, remember that the transformation should support the generation of an EBM payload that can be routed to and used by a B2BCS. The B2B mapping guidelines described in Step 1: Identifying the B2B Document and Analyzing Requirements should be considered to identify the fields in the EBM that are required by the B2BCS to create the B2B documents.
A few other considerations include the following points:
Follow the AIA recommendation to always map all available fields, instead of just a subset of fields required for a specific integration scenario.
External global identifiers such as UPC Product Codes and DUNS should be mapped along with application internal identifiers.
Reference components in the EBM should be fully mapped. For example, you should map not just a Location Identifier, but also the actual address details, because a remote trading partner may not be able to resolve the location identifier to an actual location.
Table 19-8 provides the fields in the EBM header must be mapped so that they can be used to perform trading partner-specific routing in the EBS layer, as described in the previous section.
Table 19-8 EBM Header Elements that Must be Mapped to Enable Trading Partner-Specific Routing in the EBS Layer
| EBM Header Element | Description | Example Value |
|---|---|---|
|
/EBMHeader/B2BProfile/SenderTradingPartner/TradingPartnerID |
ID of the sending trading partner as defined in Oracle B2B. For outbound flows, this is the host" trading partner. |
MyCompany |
|
/EBMHeader/B2BProfile/ReceiverTradingPartner/TradingPartnerID |
ID of the receiving trading partner as defined in Oracle B2B. For outbound flows, this is the remote trading partner. |
Globe Inc |
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 19-35, 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 batching outbound documents. Parameters such as the batch size and time-out can be configured in Oracle B2B without any changes to the AIA layer.
The values used for naming trading partners in Oracle B2B should match the values that are sent from the requester ABCS using the following fields:
/EBMHeader/B2BProfile/SenderTradingPartner/TradingPartnerID (for Host Trading Partner Name)
/EBMHeader/B2BProfile/ReceiverTradingPartner/TradingPartnerID (for Remote Trading Partner Name)
If the values provided by the source application for these fields and the trading partner names in Oracle B2B do not match, you can maintain a DVM file that contains the mapping between the source application's trading partner IDs and trading partner names of Oracle B2B.
This DVM can be looked up during the transform from the ABM to the EBM in the requester ABCS to populate the SenderTradingPartner/TradingPartnerID and ReceiverTradingPartner/TradingPartnerID fields.
The next step, as shown in Figure 19-36, is to deploy the AIA services. You can deploy the services to a target Oracle SOA server using Oracle JDeveloper.
If any 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.
This section includes the following topics:
The next step, as shown in Figure 19-37, is to test your newly developed or deployed AIA services that make up the B2B integration flow.
Before you go live with your B2B integration flows with your trading partners, we recommend that you complete the following sequence of tests.
If your AIA services are Composite Application Validation System (CAVS)-enabled, you can test your AIA services using a test simulator.
Using a CAVS simulator, you can simulate the behavior of your trading partners by sending messages to and receiving messages from a test harness, instead of your actual trading partners. This testing can take place without any knowledge of your trading partners.
The objective of this testing, as shown in Figure 19-38, is to verify that the AIA services are properly developed, deployed, and configured.
This section includes the following topics:
Another common approach to testing is to create dummy delivery channels in your trading partner setup, as shown in Figure 19-39. For example, instead of configuring your trading partner agreement to send outbound documents to the remote trading partner's server, you can configure the agreement to create the outbound B2B files in a temporary B2B file location on the server.
In this case, if you test an outbound B2B flow, all of the components involved in the flow are invoked, but the generated B2B document is copied to a temporary file directory. You can review the B2B document for completeness and correctness and also share it for review with your trading partners.
The objective of this testing is to verify the integration between AIA services, the application, and B2B and to verify that the configuration across these layers is consistent.
This testing can also take place without any knowledge of your trading partners.
Certain B2B document protocols support a protocol envelope-level flag that can be used to specify whether the B2B document is being sent in test or production mode. The trading partner agreements in Oracle B2B can be configured to set this indicator to Test mode.
Now when you trigger an outbound B2B flow, the document is sent across to your trading partners, but the trading partner system recognizes the inbound document as a test instance and does not pass it on to the backend application, as shown in Figure 19-40.
The objective of this testing is to verify the handshake between your B2B server and the trading partner's B2B server. Setup of transport and messaging features such as acknowledgement, encryption, packaging, partner and document identification, and so forth are verified.
This approach requires that this test mechanism be discussed and agreed upon with each of your trading partners.
Finally, you can test integration from your production systems to your remote trading partner's production systems by using dummy business data in the B2B documents being exchanged. For example, if you need to test end-to-end outbound Purchase Order integration from your (buyer) system to your trading partner's (vendor) system, which are integrated by an outbound EDI X12 850 B2B flow, you can place orders either using an EDI test item created for the trading partner or using a price of one cent for the items being ordered.
The order request is received and processed successfully by the trading partner's business application, as shown in Figure 19-41, however, the trading partner's business users or rules discard the order request.
This approach also requires that the test mechanism be discussed and agreed upon with each of your trading partners.
This section includes the following topics:
The final step, as shown in Figure 19-42, 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.
Oracle B2B's built-in reporting allows for the creation of the reports listed in Table 19-9. These reports query the run-time transactions in Oracle B2B and can be used to monitor individual transactions with trading partners.
Oracle B2B allows reports to be created and saved as report definitions, which can be used to generate reports for specific criteria, such as View Purchase Orders exchanged with trading partner Global, for example. You can also create ad hoc reports.
Table 19-9 Oracle B2B Report Types
| Report Type | Description | Example Report |
|---|---|---|
|
Business Message Report |
These reports provide business messages based on specified search criteria. |
View all Purchase Order documents received from trading partner "Global" |
|
Wire Message Status Report |
These reports enable you to query for wire messages in the native data formats sent to and received from trading partners. Wire message reports contain transport and protocol-related information in addition to the business data. |
View all messages sent to trading partner ABC Corp including the HTTP headers. |
|
Collaboration Status Reports |
These reports help you group related individual transactions that together perform a business task. This report is supported only for the RosettaNet document protocol. |
View all RosettaNet 3A4 collaborations. |
|
Error Reports |
These reports help you monitor all failed transactions in Oracle B2B |
View all messages received from trading partner Global that failed in Oracle B2B due to any error. |
For more information about how to use the reporting functionality in B2B, see "Creating Reports" in Oracle Fusion Middleware User's Guide for Oracle B2B.
Oracle Enterprise Manager Console can be used to monitor the AIA flows. To monitor the outbound B2B integration flows, you can log in to the Oracle Enterprise Manager Console and look for instances of the requester ABCS that triggered the B2B flows.
The status of the ABCS instance, payload, and child processes can all be monitored from the Oracle Enterprise Manager Console.
By looking up the instances of the composite AIAB2BInterface[1.0], for example, you can view the JMS payload being passed to Oracle B2B, including the various B2B header parameters.
In the case of failures in either the AIA layer or Oracle B2B, the AIA Error Handler gets triggered. The AIA Fault Message contains the error text and description. In addition, B2B information pertaining to the failed transaction, such as Sender, Receiver Trading Partner, Document Type, and so forth, are also supplied in the AIA Fault.
For more information about error notifications, see "Using Error Notifications" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.
|
 Copyright © 2001, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
