DYNAMIC ROUTING OF ENDPOINTS USING ORACLE ENTERPRISE SERVICE BUS (ESB) A White Paper prepared by Raastech Author Ahmed Aboulnaga Copyright Raastech 2010
INTRODUCTION This white paper provides a working example on how to configure an ESB service to dynamically route to multiple endpoints with a single SOAP service adapter using Oracle Enterprise Service Bus (ESB) 10g. The purpose is to allow the ESB service to parse the incoming message, and based on the input, route to the appropriate endpoint, which may not be defined during design time and which may also be updated dynamically as needed. Why is dynamic routing needed? No modifications to the ESB service is needed if a new SOAP service is added which has the same WSDL but a different endpoint. This allows for you to dynamically add multiple endpoints without having to re-update and redeploy your service. What are the disadvantages of this approach? It is not possible through the ESB Control console to show how the request was routed (i.e., which endpoint was invoked). One has to edit the XSL to add the variables during the design time, though this is a one time process. AN OVERVIEW OF IMPLEMENTING DYNAMIC ROUTING This section provides a brief overview of the steps involved in using ESB to dynamically route. 1. Create a Domain Value Map (DVM) within ESB Control that contains the endpoints. For example, there may be 3 copies of the same service, each one designed to create a customer record based on different continents. System EBS-US EBS-EU EBS-AS Endpoint http://cpllc.info:7777/createcustomer http://eu.cpllc.info:80/createcustomer https://as.cpllc.info/createcustomer Raastech White Paper 2 / 8
For example, if a U.S. customer payload is encountered, the expectation is that it is routed to the EBS-US service to be created within that environment. 2. Create the mapper file (i.e., XSL transformation) within your ESB service, and map/transform the fields as necessary. This takes place during design time. 3. View the source of the XSL file, and add the following (which is an example) immediately before the <xsl:template match="/"> tag to update the outbound header: <xsl:variable name="locationin" select="orcl:lookup-dvm('endpoints', 'System', /imp1:datas/imp1:data/imp1:application, 'Endpoint','')"/> <xsl:variable name="locationout" select="ehdr:setoutboundheader('/shdr:esbheader/shdr:location', $LocationIn, 'shdr=http://xmlns.oracle.com/esb;')"/> EXPLANATION Here, we explain the steps above in more detail. The following statement performs the DVM lookup, and places the lookup result in a variable called $LocationIn: <xsl:variable name="locationin" select="orcl:lookup-dvm('endpoints', 'System', /imp1:datas/imp1:data/imp1:application, 'Endpoint','')"/> The lookup-dvm function accepts 5 parameters and takes the form: Parameter Example Explanation dvmname Endpoints Name of the DVM sourcecolumn System The column that will be looked up in the DVM sourcevalue /imp1:datas/imp1:data/imp1:application The value to look up within this column targetcolumn Endpoint The name of the target column to get value defaultvalue Default value Raastech White Paper 3 / 8
The setoutboundheader function is one of four key header transformation extension functions, as shown in the example below: <xsl:variable name="locationout" select="ehdr:setoutboundheader('/shdr:esbheader/shdr:location', $LocationIn, 'shdr=http://xmlns.oracle.com/esb;')"/> The setoutboundheader function accepts 3 parameters and takes the form: Parameter Example Explanation xpathexpression /shdr:esbheader/shdr:location There are several in and out header properties for JMS, File, AQ, and SOAP that can be manipulated Value System Value namespacedecl shdr:http://xmlns.oracle.com/esb Takes the form prefix=namespace; DEVELOPMENT WALK-THROUGH The following steps walk through the development process using JDeveloper and ESB Control. 1. Create the DVM Create an XML file (e.g., endpoints_dvm.xml) with the following content: <?xml version = '1.0' encoding = 'UTF-8'?> <dvm name="endpoints" isnew="null"> <description>dynamic endpoints for all systems</description> <columns> <column name="system"/> <column name="endpoint"/> </columns> <rows> <row> <cell>ebs-us</cell> <cell>http://cpllc.info:7777/createcustomer</cell> </row> <row> <cell>ebs-eu</cell> <cell>http://eu.cpllc.info:80/createcustomer</cell> </row> Raastech White Paper 4 / 8
<row> <cell>ebs-as</cell> <cell>https://as.cpllc.info/createcustomer</cell> </row> </dvm> This DVM represents the mapping between the target systems and their actual endpoints, and can be updated dynamically in the future and/or as needed. In the example above, the DVM has two columns; the first column System denotes the system name you want to route to, and the second column Endpoint is the actual endpoint. 2. Import the DVM Using the ESB Control console, create the DVM by importing the XML file above. 3. Create the ESB Service Using JDeveloper, create a simple ESB consisting of: Inbound file adapter Routing service Outbound SOAP service Only one outbound SOAP service is required, even though there are 3 endpoints. The WSDL of this SOAP service may have a hardcoded SOAP address location similar to the following, but can be ignored. For example, it may look like the following: <soap:address location="http://192.168.1.50/cust/customerregservicesoaphttp"/> 4. Create the Mapper File Raastech White Paper 5 / 8
Create a new mapper file (i.e., XSL transformation) between the routing service and the SOAP service. 5. Transform the Outbound Header Utilize the header transformation extension function setoutboundheader to update the outbound header and override the SOAP address location that is hardcoded in the WSDL. Click on Source to view the source of your XSL file just created, and immediately before the statement <xsl:template match="/">, add the following: <xsl:variable name="locationin" select="orcl:lookup-dvm('endpoints', 'System', /imp1:datas/imp1:data/imp1:application, 'Endpoint','')"/> <xsl:variable name="locationout" select="ehdr:setoutboundheader('/shdr:esbheader/shdr:location', $LocationIn, 'shdr=http://xmlns.oracle.com/esb;')"/> The design will look similar to the following. As seen from the screenshot below, in addition to the mapping, two variables are created; LocationIn and LocationOut: 6. Test the ESB Service This example uses the message input variables (/imp1:datas/imp1:data/imp1:application) to perform a DVM lookup and identify the target endpoint to invoke. ADDITIONAL INFORMATION Other header functions that can be utilized include: String getrequestheader (String xpathexpression, String namespacedecl) void setoutboundheader (String xpathexpression, String value, String namespacedecl) Raastech White Paper 6 / 8
String getinboundresponseheader (String xpathexpression, String namespacedecl) void setresponseheader (String xpathexpression, String value, String namespacedecl) The table below lists additional header properties for various adapters: References for Oracle ESB Header Support: http://www.oracle.com/technology/products/integration/esb/files/esb-presentationheaders.pdf About Raastech: Raastech specializes in information technology development and systems integration. Founded in 2009, Raastech provides management consulting, systems development, and integration to both federal agencies and commercial organizations. We provide value to our clients by being innovative and dependable partners in achieving their objectives. For more information, please visit http://www.raastech.com. About the Author: Ahmed Aboulnaga is a Technical Director at Raastech and has extensive experience in Oracle Fusion Middleware. He has been involved in the architecting and implementation of large scale systems involving middleware technologies such as Oracle SOA Suite, Oracle Application Integration Architecture, Oracle Data Integrator, Oracle Integration B2B, Oracle Identity Management, and numerous other Oracle middleware technologies. Raastech White Paper 7 / 8
Raastech White Paper: Overview of the Oracle AIA Foundation Pack PIP Auditor September 2010 Raastech Headquarters: 2201 Cooperative Way, Suite 600 Herndon, VA 20171 www.raastech.com Copyright 2010 Raastech, Inc. All rights reserved. Raastech White Paper 8 / 8