Custom URLs for WSO2 ESB Proxy Services

  • By Supun Kamburugamuva
  • |
  • 18 Jan, 2011
Applies To:  WSO2 ESB 3.0.0/3.0.1


It is often required to have custom URLs for WSO2 ESB proxy services. A proxy service is a virtual service deployed in the WSO2 ESB.

In the default setup a proxy service is given a URL of the following format.

https://{host}:{port}/services/{Proxy Service Name}

Various parts of this URL can be customized to have a user defined URL.


Now let's say users want to change the URL of the {host}:{port}. This can be done using the HTTP transport receiver configuration in the axis2.xml configuration file found in the repository/conf folder.

<parameter name="WSDLEPRPrefix" locked="false">https://myCustomDomain/</parameter>

Here is the complete configuration of the Transport Receiver.

<transportReceiver name="http" class="org.apache.synapse.transport.nhttp.HttpCoreNIOListener">
    <parameter name="port" locked="false">8280</parameter>
    <parameter name="non-blocking" locked="false">true</parameter>
    <!--parameter name="bind-address" locked="false">hostname or IP address</parameter-->
    <parameter name="WSDLEPRPrefix" locked="false">https://myCustomDomain/</parameter>
    <!-- parameter name="priorityConfigFile" locked="false">location of priority configuration file<parameter-->

This only changes the HTTP listener. Users can do the same for the HTTPS listener as well.

/services/{Proxy Service Name}

To change the /services/{Proxy Service Name} part users have to edit the axis2.xml configuration file found in the repository/conf folder to insert a custom dispatcher. The dispatches should be inserted in to the dispatch phase of the In-Flow of the ESB.

Here is the configuration for the dispatcher.

<handler name="CustomURIBasedDispatcher"

The dispatcher should be inserted in to the In-Flow of the ESB engine at the Dispatch phase. It should be the first handler in the Dispatch phase.

Here is the complete Dispatch phase with the handlers.

<phase name="Dispatch" class="org.apache.axis2.engine.DispatchPhase">
    <handler name="CustomURIBasedDispatcher"
    <handler name="RequestURIBasedDispatcher"
    <handler name="SOAPActionBasedDispatcher"
    <handler name="RequestURIOperationDispatcher"
    <handler name="SOAPMessageBodyBasedDispatcher"
    <handler name="HTTPLocationBasedDispatcher"

Now we are all set for creating custom URLs of the proxy service.

In the proxy service insert the following parameter with the custom URL. The parameter can be inserted from the source view as well as UI.

Source View

<parameter name="ServiceURI">/CustomURL/Part1/Part2</parameter>


Proxy Service Configuration

Now if you go to the service dashboard of the proxy service you can see that the proxy service endpoint has changed.



Supun Kamburugamuva

Technical Lead and Product Manager - Enterprise Service Bus, WSO2, Inc.


About Author

  • Supun Kamburugamuva
  • Technical Lead
  • WSO2 Inc