Integration,

Oracle Fusion DOO - Integrating External Systems using EIL

September 9, 2014 | 7 minute read

Ashish Singh

Text Size 100%:

－＋

Update Feb 2018 : Please note that this blog was written in 2014 with the On-Prem Fusion R8 in mind. The current SCM SaaS version is R13.
Although most of this blog is still applicable, please refer to the SCM Order Management documentation or whitepapers for the latest information.

Introduction

One of the core features of the Oracle Fusion Distributed Order Orchestration (DOO) is its ability to integrate with external applications for routine orchestration tasks such as invoicing, shipping, etc.

In this blog I’ll explain how to achieve this, using an example of invoicing. Such an integration would be required if, for example, the invoice generation is performed by an external application.

It is assumed that the basic DOO functional setup has already been done. For the purposes of this post, I used the default ShipOrderGenericProcess for orchestration. If you are new to DOO and its setup, then the Oracle Cloud documentation of Product Value Chain and Order Orchestration are a great starting point. They do a very good job of simplifying what needs to be done and why; from a functional angle.

Concepts

In order to understand how the Fusion DOO talks to external applications, we need to know about the Enterprise Integration Layer (EIL) and Task Layers:

EIL: It is the layer where concrete details of the external to-be-invoked service are recorded, like Endpoint URL, security requirements etc.
Task Layer: Think of it as a façade that represents routine tasks in the life of an order. There’s a shipping task layer, Invoice task layer, etc.

Functional Setup

To configure the external invoice system, the following are the necessary (but not complete) functional steps, the complete set of function steps can be found here, Product Value Chain and Order Orchestration:

1. 1) Define the external AR/financial application as a source system, INTEG_FINANCIAL_SYSTEM for example. Go to FA Home Page->Setup and Maintenance -> Search for 'Manage Trading Community Source Systems' and go to the task.
2. Make sure the source system is enabled for Items, Trading Community Members, and Order Orchestration and Planning

1. 2) Create items that are cross-referenced between the Capture System (Order source) and the Financial System. Go to FA Home Page->Items->Items tab -> Search for the required item and click on it.

1. 3) You can create customer cross-references similarly, but if that’s not possible (customer being new), then there’s a trick down below.

1. 4) For more static cross-reference entities such as currencies, Units of Measures etc., the SOA Domain Value Maps (DVMs) are used to map source-specific entities. These DVMs are deployed as part of the MscCollConfigurationXReferenceComposite, and can be modified using the SOA Composer.

The whitepaper here describes DOO Cross-referencing in further detail.

At a high level, DOO has a cross-referencing engine that maintains cross-references for functional entities such as currencies, Units of Measure etc across various source systems. It’s called the Order Orchestration and Planning Repository (OOPR).
Also, Items and Customer cross-reference data are ‘referenced’ from the Customer Data Management and Product Hub modules, and are not maintained by OOPR.

1. 5) Once the new cross-ref entries are added and committed, start the collections server. Go to the 'Manage Orchestration Data Collection Processes' task.

6) Collect the newly created entries into the OOPR by clicking ‘Perform Data Collection'

Technical Setup

Now we are ready for the technical part. Some of the details in this section are inspired from another DOO whitepaper here.

1. 1) Create a SOA Composite that will serve as the External Connector. Base the endpoint off the following WSDL published in the SCM SOA MDS. (You’d have to make a JDev MDS connection to the SCM_FUSION_MDS_SOA schema)

1. 2) Use the CreateInvoice operation in the BPEL receive activity.

1. 3) The XSD used by the InvoiceEBSV2.wsdl service is also stored in the same MDS, at

DOO extensively uses the oracle AIA Foundation Pack objects for integrating with external systems. The WSDL used in the step 1 above is an AIA Enterprise Business Service, Also, the XSD used by the WSDL operation is an Oracle AIA EBM, specifically the CreateInvoiceEBM.

1. An EBO represents a business concept such as customer, invoice etc. EBOs leverage widely adopted international standards for modeling and naming the business object. EBMs represent the concrete usage of an EBO, for example CreateInvoiceEBM is the usable EBM derived from the Invoice EBO.For more information, please refer the AIA Concepts and Technologies Guide

1. For the purpose of this blog I created a basic SOA composite called CustomDOOInvoiceComposite, which takes in the CreateInvoiceEBM and returns back a sample CreateInvoiceResponseEBM. I deployed my process on a non-SCM domain. I also secured the end-point using the oracle/ oracle/wss11_username_token_with_message_protection_service_policy.
3. We’ll now connect this service to DOO engine.

1. 4) On the FA Home Page go to the ‘Manage External Interface Web Service Details’, and define the end-point of the newly created composite.
2. The target system must be our newly defined INTEG_FINANCIAL_SYSTEM
  Connector Name must be a unique string
  Connector URL must be the concrete end-point of the service we just created (CustomDOOInvoiceComposite)
  User Credential Key is the CSF key for sending authentication token
  Keystore recipient alias is used for message protection, per OWSM security policy requirements.

5) Go to the ‘Manage External Interface Routing Rules’ task , open the Invoice Task Routing business rule, and add two new assertions as shown below
The SERVICE_NAME should be same as the ‘Connector Name’ defined in step#2 above.The RESOLVE_XREF_FOR_CUSTOMERINFO ensures that customer cross-reference validation is skipped (This is the trick we spoke about earlier).Don’t forget to hit the ‘Release’ button after making changes.

Callback setup

So far we have configured DOO to call out the external Invoice connector. But the invocation is an asynchronous one, and now we’ll discuss how the callback happens.

The composite that invokes the custom connector is DOOTaskInvoiceExternalRequestComposite, whose callback port is configured with oracle/wss11_username_token_with_message_protection_policy. This implies that the connector callback must be configured with the csf keys and certificates as needed.

A Few caveats here :

a) If you decide to remove/detach this security policy, a global policy-set might kick in.
b) Double check the callback URL protocol, as in most cases it is HTTPS ending at the FA Load Balancer. In that case you’d have to configure the SSL certificates as well.

Once the callback path is correctly configured; upon receiving a message the DOOTaskInvoiceExternalRequestComposite process updates the invoice state of the order to AWAIT_BILLING, as shown in the screen shot below:

Further updates to the Invoice status are done when the Invoice Application invokes the service DOOTaskInvoiceExternalResponseComposite (this service is also OWSM secured using the same service policy as above). For example, the following payload invocation changes the status from AWAIT_BILLING to COMPLETE.

Payload :

<v2:ProcessInvoiceNotificationEBM xmlns:v2="http://xmlns.oracle.com/EnterpriseObjects/Core/EBO/Invoice/V2" xmlns:v21="http://xmlns.oracle.com/EnterpriseObjects/Core/Common/V2" xmlns:ebo="http://xmlns.oracle.com/EnterpriseObjects/Core/EBO/Invoice/V2" xmlns:add="http://schemas.xmlsoap.org/ws/2003/03/addressing" xmlns:urn="urn:oasis:names:tc:xacml:2.0:context:schema:cd:04" versionID="?" languageCode="en-US">   <corecom:EBMHeader xmlns:corecom="http://xmlns.oracle.com/EnterpriseObjects/Core/Common/V2">   HEADER DETAILS       </corecom:EBMHeader>   <v2:DataArea>     <v21:Process/>     <v2:ProcessInvoiceNotification>       <corecom:Identification xmlns:corecom="http://xmlns.oracle.com/EnterpriseObjects/Core/Common/V2">         <corecom:ID schemeID="InvoiceNumber" schemeAgencyID="OPS2">GENERATED INVOICE NUMBER</corecom:ID>       </corecom:Identification>       <v2:InvoiceDateTime>INVOICE GENERATION DATE TIME</v2:InvoiceDateTime>       <ebo:InvoiceLine>              INVOICE LINE DETAILS       </ebo:InvoiceLine>     </v2:ProcessInvoiceNotification>   </v2:DataArea> </v2:ProcessInvoiceNotificationEBM>

After successful invocation, the Orchestration state changes to the following:

Conclusion

In this blog I have demonstrated how flexible DOO is and how it can be tailor-made to fit to your organization’s order orchestration requirements. We learnt about the EIL and the Task Layer, and how they help extend DOO in a seamless manner.