3 Integration with Third-Party Application Services

Oracle Retail application landscape of the customer has a variety of applications servicing different business functions. There is a legitimate need to integrate these applications. Customers may have one or more of these applications from vendors other than Oracle. Both Oracle and non-Oracle applications should be able to integrate as long as the interface requirements are met.

In this document we are describing the process and instructions to integrate a third-party application to an Oracle Retail application using RSB. We will be providing instructions and example to show how to integrate using RSB. For this purpose, we are assuming Order Management System (OMS) as the third-party application. OMS is only a representational application that implements retail order management functionality. Actual applications that will be used instead can be any third-party applications like Yantra, and so on.

Any third-party applications that can consume or provide SOAP based web-services can be integrated with Oracle Retail application through RSB. While there can be complex integration scenarios, this document describes only those where the services can be integrated by adapting the interfaces of the consumer and provider. This adaptation is done by modifying message in OSB layer.

Types of Customization

The web services you want to integrate to RSB is likely to be different from what the corresponding provided decorators expect. These differences can be broadly classified into two categories:

• Payload is different

• Service and operation names are different

How to Import WSDL into RSB Decorator Project

In order to integrate with third-party application services, first step is to import the WSDL file of third-party application service into the decorator project. Following are the steps:

1. Right-click WSDL >BusinessService and select Import >Oracle Service Bus - Resources from the URL.

   
   

2. Select Resource Type as WSDL. Also provide the URL of the WSDL. Alternatively, if you have the WSDL downloaded to the local machine, you can browse to that location and select the WSDL file. Here open the WSDL and verify the WSDL can be successfully accessed.

   
   

3. Click Next button. It will show the WSDL and all related XSD files:

   
   

4. Select the WSDL file and click Finish. As you can see, the new WSDL file is added to the project:

   
   

5. The next step is to modify the business service to use new WSDL. In order to do so, open the business service file and go to General tab:

   
   

6. Click Browse for WSDL Web Service field.

   
   

7. Select the new WSDL (for example, CustomerOrderPort(port)) and click OK.

   
   

8. Click Yes. And the new business service should be displayed.

   
   

How to Map Namespaces and Operation Names

When the business service is changed to use a new WSDL, then the SOAP request of proxy service will not work as-is with the new business service because the business service WSDL may have different namespaces and names for operations and services. So now the proxy service message flow will need to be modified to transform the incoming message to the expected format of business service. In order to do these transformations XQuery files can be used. A sample for making these changes in proxy service message flow is shown below.

1. The first step is to add a new stage in request pipeline of local proxy service message flow. To add a new stage, right-click the assignMessageEcid stage, and select Insert After > Stage.

   
   

2. Enter the name of stage as setOutboundNamespaceAndOperation.

   
   

3. To create a new xquery file, you can create a folder xquery where all the xquery files will be saved. To create the folder, right-click the project name and select New>Folder. For Enter or select the parent folder, verify the AppServiceDecorator is selected For e.g. oms-CustomerOrder-AppServiceDecorator. Enter xquery as the folder name.

   
   

4. Now right-click the xquery folder and select New>XQuery Transformation. Enter the name setOutboundNamespaceAndOperationInBody.

   
   

5. Click Next. Now we need to select Source type for transformation. Since this is not based on any xsd, select anyType, and then click Add. Verify anyType is displayed under the Selected Source Types.

   
   

6. Click Next and select anyType for target Types as well. Click Add, and verify anyType is listed under the Selected Target Type.

   
   

7. Click Finish. In the source view of the file, enter the code as shown in the screenshot below. In this code, the variable $namespace contains the namespace of the incoming request xml and $operation contains the operation name in the incoming request. Further, we check for each incoming operation name and assign the corresponding outbound operation name in $destOperation variable.

   For example, when the incoming operation name is queryCustomerOrder, the outbound operation name needs to be queryMyCustomerOrder. The namespace is at service level, so we find the service namespace from the new business service WSDL and assign it to $destNamespace variable. The sample xquery shown in the screenshot is listed in Appendix A. You can copy the code and make changes appropriate to your requirements.

   
   

8. Return to the stage in message flow and add an Assign action. Steps to add Assign action are:

   Right click the stage, that is, setOutboundNamespaceAndOperation.

   Select Insert Into > Message Processing > Assign.

   
   

9. In the Expression field of Assign action, click the <Expression> link and go to XQuery Resources tab:

   
   

10. Click Browse and select the new xquery file.

    
    

11. Click OK and in the Binding field, enter the value as $body.

    
    

12. Click OK. In the Variable field of Assign action, enter the value as body.

    
    

13. Perform similar transformation of namespaces and operation names in the response pipeline but in the reverse order. This is because the response returned from business service must be converted to the response message format which conforms to the proxy service WSDL. To do this, add a new stage in response pipeline.

    
    

14. Enter the stage name as setInboundNamespaceAndOperation

    
    

15. Now we need to create an xquery file to do the mapping. Right click the xquery folder and select New > XQuery Transformation.

    
    

16. Enter file name as setInboundNamespaceAndOperationInBody.

    
    

17. Click Next. Select anyType for Source Types field:

    
    

18. Click Next and in Target Types select anyType

    
    

19. Click Finish. Goto the Source tab of xquery file:

    
    

20. Enter the code as shown below. In this code, the variable $namespace contains the namespace of the response xml and $operation contains the operation name in the response. Further, we check for each operation name and assign the corresponding proxy service operation name in $destOperation variable. For example, when response operation name is queryMyCustomerOrderResponse then the new operation name needs to be queryCustomerOrderResponse. The namespace is at service level, so we find the service namespace from the proxy service WSDL and assign it to $destNamespace variable. The sample xquery shown in the screenshot is listed in Appendix A. You can copy the code and make changes appropriate to your needs.

    
    

21. In the message flow, in the setInboundNamespaceAndOperation stage add an Assign action by right-clicking on setInboundNamespaceAndOperation stage and select Insert Into > Message Processing > Assign.

    
    

22. In the Properties window of Assign action, click the Expression link to open the Expression dialog box and switch to XQuery Resources tab.

    
    

23. Click Browse and select the xquery file.

    
    

24. Click OK. In the Binding column, enter the value $body.

    
    

25. Click OK and in the Variable field, type body.

    
    

The above completes the steps for namespace and operation mapping.

How to do Payload Transformation

The proxy service request message payload types may be different from the payload types that are required by the new business service WSDL. Therefore we need to transform the incoming request payload to the format expected by the business service. For payload transformation, follow the steps as shown below:

1. In our example, the proxy service payload is of type CustOrderDesc and the business service payload is of type MyCustOrderDesc. So first we need to create xquery files which transform the payload from CustOrderDesc to MyCustOrderDesc type. Right-click the xquery folder and select New > XQuery Transformation.

   
   

2. Enter file name as CustOrderDescToMyCustOrderDescMapping.

   
   

3. Click Next. Select CustOrderDesc element from the proxy service WSDL which is CustomerOrderService.wsdl and click Add. Verify that it gets added in the Selected Source Types window.

   
   

4. Click Next. For Target Types, select MyCustOrderDesc from the new business service WSDL which is MyCustomerOrderService.wsdl. Click Add. Verify that it gets added in the selected Target Type window.

   
   

5. Click Finish and go to the Design tab of xquery file. In the Design view of the xquery file, you can drag and map the elements from source to target type. So drag from CustOrderDesc and connect to MyCustOrderDesc:

   
   

6. Right-click the link between the source and target types and select Induce Map. It will auto map all the fields which can be mapped automatically.

   
   

7. After mapping it looks like below:

   
   

8. For the fields which are not auto-mapped, we need to map them manually. Drag and connect those fields one by one. You may have to write xquery functions for complex mapping. This document will not go into the details of mapping using XQuery. Please refer to XQuery documentation for more details. Following is the screenshot after mapping fields:

   
   

9. Once the mapping in xquery file is complete, go to the Routing node and in the Request pipeline, right-click Request Action and select Insert Into > Flow Control > If Then to add an If Then flow:

   
   

10. Go to the Properties window of first If Condition.

    
    

11. Click the <Condition> link and go to Condition Builder tab. Here we need to build the condition for payload mapping. We will check for operation name to build the condition. Enter local-name($body/*[1]) in the Operand field, which gives the operation name in request xml. Select = in the Operator field. In the Value field, we need to enter operation name which we want to look for, enter 'createMyCustomerOrder'.

    
    

12. Click OK to add condition to Condition Expression.

    
    

13. Click OK.

    
    

14. Add a Replace action for the first condition

    
    

15. Click the <XPath> link of Replace action. Here we need to provide xpath of the variable which we need to transform.

    
    

16. Enter the xpath expression.

    
    

17. Click OK to return to the main window. Then click the <Expression> link. Here we need to provide the xquery which will return the transformed payload.

    
    

18. Click Browse and select the xquery file.

    
    

19. Click OK.

    
    

20. In the Binding field, we need to provide path of the input payload which needs to be transformed. Select CustOrderDesc for this example.

    
    

21. Click OK

    
    

22. More Replace actions can be added in other if conditions to transform payload for each operation type. You will need to write xquery files for each input payload to output payload transformation.

    
    

23. We need to do similar transformation in reverse order in Response pipeline as well which will transform MyCustOrderDesc to CustOrderDesc. So first we need to write an xquery file which transforms MyCustOrderDesc to CustOrderDesc. The steps for creating xquery file will be exactly similar to the steps for creating CustOrderDescToMyCustOrderDescMapping file. The only difference will be that the source and target types will be reversed in this case. Now the source type will be MyCustOrderDesc and target type will be CustOrderDesc. Save the new file as MyCustOrderDescToCustOrderDescMapping.

    After creating the xquery file, add an If Then flow in Response Action as shown below:

    
    

24. Click <Condition> link for first If condition and go to the Condition Builder tab.

    
    

25. Enter the values in Operand, Operator and Value fields as show below:

    
    

26. Click OK to add condition to Condition Expression window.

    
    

27. Click OK to go back to properties window.

    
    

28. Add a Replace action in first if condition flow:

    
    

29. Click the <xpath> link. Here we need to enter the xpath of the element which needs to be transformed. Enter as shown below:

    
    

30. Click OK.

    
    

31. Click the <Expression> and go to XQuery Explorer window to select the xquery file. Select MyCustOrderDescToCustOrderDescMapping xquery file.

    
    

32. Click OK. In the binding field enter path to MyCustOrderDesc as that is the source payload for transformation:

    
    

33. Click OK. In Variable field enter body.

    
    

34. Add more replace actions for other if conditions in the if then flow:

    
    

This completes the steps for payload transformation in a message flow.