Using an XQuery transformation to map between the different data models of the services

Due to the fact that on the proxy service we use a different WSDL than the external service offered, we need to adapt the data models between these two interfaces when sending the request message as well as on the way back when returning the response message. There are different ways to achieve that, probably the most common one in OSB being the use of an XQuery script.

Getting ready

Make sure that you have the current state of the basic-osb-service project available in Eclipse OEPE. We will start this recipe from there. If necessary, it can be imported from here: \chapter-1\getting-ready\operational-branch-proxy-service-created.

How to do it...

First we will need to create the transformation for the request message to be passed to the external service, which has not many data elements to transform.

1. Create a new XQuery script by right-clicking on the transformation folder in the Project folder and then select New | XQuery Transformation.

2. Enter TransformFindCustomerRequest into the File name field and then click on Next.

3. In the Available Source Types tree, select the source type for the transformation: FindCustomer from the CustomerManagement.wsdl.

4. Click on the Add button to add it to the Selected Source Types, as shown in the following screenshot:

   

5. Click on the Next button.

6. In the Available Target Types tree, select the target type for the transformation: RetrieveCustomerByCriteria from the CustomerService.wsdl.

7. Click on the Add button to move it to the Selected Target Types.

8. Click on the Finish button.

9. Click on Yes to confirm switching to the XQuery Transformation perspective.

   The graphical XQuery transformation editor opens, with the source on the left and the target structure on the right. We can now start mapping source to target values. In the case of the FindCustomer request, the target side is a generic query operation with a list of criteria elements. In this recipe, we will only map the ID, assuming that at the moment only the ID value needs to be supported. To map it, follow the ensuing steps:

10. Right-click on the criteriaField node on the right side (target) and select Create Constant.

11. Enter id into the Constant Value field of the pop-up window.

12. Click on the OK button.

13. The criteriaField is annotated with a little c, indicating that a constant is specified.

14. Select the criteriaValue on the right side and click on the Target Expression tab (make sure that the XQuery Transformation perspective is active, otherwise the Target Expression tab will not be available).

15. From the available XQuery Functions on the left, drag the string Type Conversion Functions to the expression editor. The expression will read xs:string($item*-var).

16. Drag the ID element from the Source type and replace the $item*-var parameter value within the parentheses:

    

17. Click on Apply on the left of the Target Expression tab window to accept the expression and a line for the mapping should be displayed. The small f on the criteriaValue node indicates the usage of an XQuery function:

    

18. Save the XQuery script

    The transformation for the request of the findCustomer operation is now ready to be used. Before we will apply it in the Messagse Flow, let's create the transformation for the response message. Perform the following steps:

19. Repeat steps 1-10 with the following differences:

    • Name the XQuery TransformFindCustomerResponse

    • Select the RetrieveCustomerByCriteriaResponse element of the CustomerService WSDL as the source type of the transformation

    • Select the FindCustomerResponse element of the CustomerManagement WSDL as the target type of the transformation

20. Map the source to the target values in the XQuery Transformation editor as shown in the following screenshot. The ID value cannot be directly mapped, a type conversion using the xs:long function is needed:

    

21. Now with the two XQuery transformations in place, let's use them in the message flow.

22. Switch to the Oracle Service Bus perspective.

23. Open the CustomerManagement proxy service and click on the Message Flow tab.

24. Drag a Replace action from the Message Processing section of the Design palette into the Request Action of the Routing for the FindCustomer operatin:

    

25. Select the Replace action and click on the Properties tab to show the properties of the Replace.

26. Enter body into the In Variable field.

27. Click on the <Expression> link.

28. In the Expression Editor pop-up, click on the XQuery Resources tab.

29. Click on Browse and select TransformFindCustomerRequest.xq from the transformation folder.

30. Click on the OK button.

31. Drag the FindCustomer node on the right side and drop it onto the Binding Variables field. The value of the binding should read $body/cus:FindCustomer.

    

32. Click on the OK button.

33. Select the radio button Replace node contents.

34. Save the changes.

    We have added the transformation of the request message. Let's repeat the same steps for the response message:

35. Drag a Replace action from the Message Processing section of the Design Palette into the Response Action of the Routing for the FindCustomer operation.

36. Select the Replace action and click on the Properties tab to show the properties of the Replace.

37. Enter body into the In Variable field.

38. Click on the Expression link.

39. In the Expression Editor pop-up click on the XQuery Resources tab.

40. Click on Browse and select TransformFindCustomerResponse.xq from the transformation folder.

41. Click on OK.

42. Enter $body/ext:RetrieveCustomerByCriteriaResponse into the Binding Variables field. An error is shown because the namespace alias ext is not defined. Click on OK.

43. Select the radio button Replace node conents.

    

44. Click on the Namespaces tab on the left of the Properties window.

45. Click on Add.

46. Enter ext into the Prefix field and http://www.crm.org/CustomerService/ into the URI field.

47. Click on OK.

48. Save the proxy service and close it.

49. Deploy the project to the OSB server by right-clicking on the server and select Publish.

50. Use soapUI to test the behavior of the service. The following screenshot shows the result of successfully executing a test containing the find result of the external service:

    

The request as well as the response message in the soapUI test window represents the format defined in the Customer Managemen WSDL.

How it works...

We have used two standalone XQuery scripts to define and execute the transformation of the request as well as the response message. XQuery is a very efficient way of executing such transformations.

We have used a Replace action to do each of the two transformations. This allows doing the transformation and assignment to the body variable in one single action. The setting Replace node contents is important because it takes care of the wrapping of the information returned by the transformation inside a <soap-env:Body> element.

The transformation could also be done with an Assign action. But in that case two Assign actions are necessary, the first one doing the transformation into a temporary variable and a second one to wrap the result of the transformation within the <soap-env:Body> element and assign it to the body variable.

Using the Replace action is not only the most efficient way of doing a transformation, it's also the easiest one to use. Therefore, we highly recommend using it if all you need is a transformation from one value to another.