The Administrator Guide describes how to configure the WSO2 ESB using the Web based management console, which is a smart engine for managing, monitoring, routing, and transforming interactions on your services network. The guide describes how to manage the Synapse configuration elements and the integrated registry, which define the console. It also provides a section on how to interpret the statistics generated by the system.
The WSO2 Management Console has been tested on Web browsers, Mozilla Firefox and Internet Explorer 6 and 7.
Please refer to the Installation Guide for details on how to install and run the WSO2 ESB.
Once WSO2 ESB has been successfully installed and started, launch a Web browser instance and point it to the URL https://localhost:9443/. This will take you to the Sign In page of the WSO2 ESB Management Console.
If a JDK version below 1.5 is used, the existing <transportReceiver> and <transportSender> elements of the conf/axis2.xml must be replaced as specified. This will allow the admin console to run over the HTTPS transport, although the services are accessible only over HTTP.
The ESB UI currently does not perform a check on references before the elements are removed. Thus there is a possibility of defining references to non-existent endpoints, sequences, etc. as well as removing them while live references still exist.
Enter your user name and password to log on to the ESB Management Console.
The default username/ password : admin / admin
You can change your password using the instructions given below.
If you do not remember your password, click Forgot Password to get help on retrieving your password. If you get any errors when trying to sign in, click Sign-in Help. A list of possible errors, their descriptions and solutions will be displayed.
To change the username and password, modify the server.xml file in the WSO2ESB_HOME/conf folder
<DefaultAdmin>
<Username>admin</Username>
<Password>admin</Password>
<Description>Default
Administrator</Description>
</DefaultAdmin>
Icon | Description |
![]() |
Add - Click this icon to add an item. Most often clicking on this icon gives a submenu from which you can select an element. |
![]() |
Edit - Click this icon to modify an existing item. |
![]() |
Delete - Click this icon to permanently delete an item. A message will appear prompting you to confirm the deletion. |
![]() |
Update - Click this icon to save your current changes, modifications, etc. |
![]() |
Registry Browser - Click this icon to view the registry browser. You can select elements from the local registry as well as the integrated registry, as both registries are displayed in the browser. |
![]() |
Add Mediator - Click this icon to add a mediator. When you click this icon, the available mediators will be displayed in a context menu. Most often this icon represents adding a child mediator. |
![]() |
Namespace Editor - Click this icon to open the Namespace Editor dialog box. |
![]() |
Disable Statistics - This icon indicates that statistics generation is in progress. Click this icon to stop statistics generation for the respective element. |
![]() |
Enable Statistics - This icon indicates that statics are not been generated at present. Click this icon to start statistics generation for the respective element. |
![]() |
Disable Tracing - This icon indicates that message tracing is in progress. Click this icon to stop tracing for the respective element. |
![]() |
Enable Tracing - This icon indicates that messages are not been traced at present. Click this icon to start tracing messages for the respective element. |
Registry Browser - This dialog box is invoked from the Pick from Registry option. The Registry Browser contains elements from the integrated registry and the local registry.
Sequence Editor - This dialog box is invoked from the Specify as Anonymous option, where a sequence has to be specified. This dialog box facilitates adding anonymous mediators. Clicking on the Add Mediator icon will give you the mediators as a context menu. You can also define a sequence that will be run in case an error occurs in the sequence you create.
Add Namespace - This dialog box is invoked by clicking New from the Namespace Editor dialog box. XML namespaces provide a simple method for qualifying an element and attribute names used in Extensible Markup Language documents by associating them with namespaces identified by URI references. Enter a prefix and the URI which it identifies.
The Synapse configuration language consists of endpoints, sequences, registry entries, and proxy services. Messages coming into Synapse is processed based on the mediators and delivered to a specified endpoint.
Proxy services define virtual services hosted on the ESB that can accept requests, mediate them, and deliver them to the actual service. Proxy services perform transport switching and expose different semantics than the actual service, i.e., WSDL, policies, and QoS aspects like WS-RM, WS-Security, etc.
This function allows you to add a proxy service using a basic configuration or an advanced configuration. The basic configuration consists of the target sequences (incoming messages, outgoing messages, and fault flow) and the target endpoint. The advanced configuration specifies the HTTP transports and QoS configurations.
Notes: You can either specify the incoming message sequence or the target endpoint. It is not necessary to specify both.
It is mandatory to specify the outgoing message sequence.
It is optional to specify the fault flow sequence.
Specifying the Target Sequences
You have three methods of specifying a target sequence. Each method is described below.
- Declared Sequence - Specifies an existing sequences for the target.
- Click the Add icon, and point to Declared Sequences. The sequences will be displayed as a submenu.
- Select the sequence you want to add. The selected sequence name will be displayed next to the target sequence.
- Specify as Anonymous - Creates a new sequence for the targets. This sequence will not be given a name.
- Click the Add icon, and click Specify as Anonymous. The WSO2 ESB Sequence Editor dialog box opens.
- Click the Add Mediator icon and create your sequence as required.
- Click Save. The label Anonymous Sequence will be displayed next to the target sequence.
- Pick from Registry - Specifies a sequence from the ESB registry.
- Click the Add icon, and click Pick from Registry. The WSO2 ESB Registry Browser dialog box opens.
- Select a sequence from either the integrated registry (click a Folder to select a value) or the local registry (click the Key list to select a value.) and click Select. The selected sequence name will be displayed next to the target sequence.
Specifying the Target Endpoint
You have three methods of specifying a target endpoint. Each method is described below.
- Declared Endpoints - Specifies existing endpoints for the target.
- Click the Add icon, and point to Declared Endpoints. The available endpoints will be displayed as a submenu.
- Select the endpoint you want to add. The selected endpoint name will be displayed next to the target sequence.
- Specify as Anonymous - Creates a new endpoint. This endpoint will not be given a name.
- Click the Add icon and point to Specify as Anonymous. The endpoint options will be displayed as a submenu.
- Select the endpoint you want to configure. Please refer to Adding Endpoints for more details. Note that there will be no field to enter a name for the sequence.
- Pick from Registry - Specifies an endpoint from the ESB registry.
- Click the Add icon, and click Pick from Registry. The WSO2 ESB Registry Browser dialog box opens.
- Select an endpoint from either the integrated registry (click a Folder to select a value) or the local registry (click the Key list to select a value) and click Select. The selected endpoint name will be displayed next to the target sequence.
Adding Advanced Proxy Configurations
The Transport Configuration page will be displayed.
Click the Delete icon to remove any service parameters that you do not require.
The QoS Configuration page will be displayed.
The Miscellaneous Configuration page will be displayed.
A Source URL field will appear when you select this option. Specify the location of the WSDL in this field.
A Reference Key field will appear when you select this option. Click the Registry Browser icon. The WSO2 ESB Registry Browser dialog box opens.
Select a WSDL from either the integrated registry (click a Folder to select a value) or the local registry (click the Key list to select a value.) and click Select.
The In-Lined WSDL Editor will appear when you select this option. Enter your WSDL and click Save.
You can edit, delete, enable statistics, start and stop the proxy service, and enable tracing for the proxy service as described below. All existing proxy services will be displayed in the Proxy Services table along with their current status. The proxy service actions are initiated by clicking on the respective icons in the table.
Edit Proxy Service
Use this function to modify existing proxy services.
- In the Actions column of the Proxy Services table, click the corresponding Edit icon of the proxy service you want to edit. The proxy service page will be displayed.
- Make the necessary changes and click Save.
Delete Proxy Service
Use this function to remove any proxy services that have been entered previously.
- In the Actions column of the Registry table, click the corresponding Delete icon of the entry you want to delete.
A message appears requesting you to confirm the deletion.
- Click Yes to confirm.
Start Proxy Service
Use this function to manually start or stop a proxy service.
- In the Actions column of the Proxy Services table, click the Start icon of the corresponding proxy service.
The icon will change to indicate that the service has started. Clicking the icon again will stop the service.
Enable Statistics
Use this function to generate statistics for the proxy services.
- In the Actions column of the Proxy Services table, click the Enable Statistics icon of the corresponding proxy service.
The icon will change colour to indicate that the console has started generating statistics for the proxy service. Clicking the icon again, will disable the statistics generation.
Enable Tracing
Use this function to enable tracing for the proxy services.
- In the Actions column of the Proxy Services table, click the Enable Tracing icon of the corresponding proxy service.
The icon will change colour to indicate that the console has started tracing the service. Clicking the icon again will disable the tracing.
An endpoint is a specific destination for a message. It may be specified as an Address endpoint, WSDL endpoint, a Failover group, or a Loadbalance group.
Endpoints can be added, edited, and deleted. You can also enable statistics for Address and WSDL endpoints.
Address Endpoint
An endpoint is defined by specifying the EPR and other attributes of the endpoint directly in the configuration.
- Enter the name, address, format, optimizing, suspend, and timeout details.
The suspend duration is the time to suspend the endpoint after it is detected as failed. This is applicable only when the endpoint is listed under a load balance or failover endpoint.
In the timeout details, any message that fails to arrive into Synapse within the timeout duration, will be dealt with as specified in the Action field.
- Select the WS-Addressing check box to engage the WS-addressing module for the outgoing message.
- If you want to specify security policies for the endpoint, select the WS-Security check box, and specify the policy key. If you select this check box, WS-Addressing will also be automatically selected.
- To specify a policy key, click the Registry Browser icon. The WSO2 ESB Registry Browser dialog box opens.
- Select an appropriate policy from the integrated registry, (click a Folder to select a value) or the local registry (click the Key list to select a value.) and click Select.
- If you want to specify reliable messaging policies, select the WS-RM check box, and follow steps 4 to 6.
- Once you have entered all the details, click Save.
The endpoint you added will be displayed in the Endpoints table.
WSDL Endpoint
An endpoint is based on a WSDL document. A WSDL document can be specified by giving a URI or in-line as a child element of the WSDL element.
- Enter the name of the WSDL document.
- If you want to specify the WSDL document as a URI, click URI and specify the URI in the WSDL URI field.
- If you want to specify the WSDL document as a child of the WSDL element, click In-line WSDL. The WSO2 In-Line Property Editor opens. Specify the WSDL configuration and click Save.
The saved inLine endpoint will be denoted by the Edit Endpoint icon. Click this icon to modify the inLine WSDL you entered.
- Enter the service, port, suspend, and timeout details.
The service and the port is used to select an EPR from the given WSDL document.
The suspend duration is the time to suspend the endpoint after it is detected as failed. This is applicable only when the endpoint is listed under a load balance or failover endpoint.
In the timeout details, any message that fails to arrive into Synapse within the timeout duration will be dealt with as specified in the Action field.
- Select the WS-Addressing check box to engage the WS-addressing module for the outgoing message.
- If you want to specify security policies for the endpoint, select the WS-Security check box, and specify the policy key. If you select this check box, WS-Addressing will also be automatically selected.
- To specify a policy key, click the Registry Browser icon. The WSO2 ESB Registry Browser dialog box will open.
- Select an appropriate policy from the integrated registry, (click a Folder to select a value) or the local registry (click the Key list to select a value.) and click Select.
- If you want to specify reliable messaging policies, select the WS-RM check box, and follow steps 4 to 6.
- Once you have entered all the details, click Save.
The endpoint you added will be displayed in the Endpoints table.
Failover Endpoint
Failover endpoints send messages to the listed endpoints. It treats the first endpoint as the primary endpoint and the rest as backups. Therefore, there has to be more than one endpoint specified in an endpoint group for optimum performance. However, adding only one endpoint is also possible. You can select existing named endpoints or create new anonymous child endpoints for the failover group.
- Enter a name for the failover endpoint.
- Click the Add Endpoint icon. The context menu will display the available endpoint options as well as the Lookup Endpoint option.
- Select existing endpoints or create new endpoints.
- To select an existing endpoint, click Lookup Endpoint, and select the endpoint from the Key field.
- To create new endpoints, select the applicable endpoint option and enter the details.
- Click Save
The endpoint you added will be displayed in the Endpoints table.
Load-balance Endpoint
Distributes the arriving messages (load) among the set of listed endpoints by evaluating the load balancing policy and other parameters. There has to be more than one load-balance endpoint defined for this feature to be effective. However, adding only one endpoint is also accepted.
- Enter a name for the load-balance endpoint.
- Click the Add Endpoint icon. The context menu will display the available endpoint options as well as the Lookup Endpoint option.
- Select existing endpoints or create new endpoints.
- To select an existing endpoint, click Lookup Endpoint, and select the endpoint from the Key field.
- To create new endpoints, select the applicable endpoint option and enter the details.
- Click Save.
You can edit, delete, and enable statistics for endpoints as described below. All existing endpoints will be displayed in the Endpoints table. The endpoint actions are initiated by clicking on the respective icons in the table.
Edit Endpoint
Use this function to modify previously entered endpoints. Note that the endpoint name cannot be modified.
- In the Actions column of the Endpoints table, click the corresponding Edit icon of the endpoint you want to edit. The endpoint page will be displayed.
- Make the necessary changes and click Save.
Delete Endpoint
Use this function to delete previously entered endpoints. However, any endpoints that are been used in Failover and Load-balance endpoints cannot be deleted.
- In the Actions column of the Endpoints table, click the corresponding Delete icon of the endpoint you want to delete.
A message appears requesting you to confirm the deletion.
- Click Yes to confirm.
Enable Statistics
Use this function to generate statistics for Address endpoints and WSDL endpoints.
- In the Actions column of the Endpoints table, click the Enable Statistics icon for the applicable Address endpoint or WSDL endpoint.
The icon will change colour to indicate that the ESB has started generating statistics for the endpoint. Clicking the icon again, will disable the statistics generation.
A sequence element is used to define a sequence of mediators that can be invoked later as a sequence. If the configuration defines a sequence named Main, then it is considered as the main mediation sequence of the ESB. If such a sequence is not defined locally, and a registry has been specified, the registry is looked up for a key named "main" to find the main mediator sequence. The Main and Fault sequences have already been added to the default configuration.
Mediators can be added to, and deleted from a sequence. You can also re-position a mediator within a sequence as required.
The available mediators are as follows:
You can create completely new sequences, or copy an existing sequence (its mediators and properties) and rename it.
The Define New Sequence page will be displayed.
You can use the Save As button to copy and save a sequence in a different sequence name.
You will be prompted to enter a new sequence name. Enter the name and click Save.
Drop - This element is used to drop a message. Once this mediator executes, further processing of the current message stops.
Log - This element is used to log the messages that are being mediated.
To add more properties, click Add Properties again.
Property - This element, which is a mediator, has no direct impact on the message but rather on the message context flowing through Synapse.
You can also edit and modify existing namespaces.
Send - This element is used to send messages out of Synapse to an endpoint.
Sequence - This element is used to invoke a named sequence of mediators.
Fault - This mediator transforms the current message into a fault message, but does NOT send it. The <send> mediator needs to be invoked to send a fault message created this way.
If you select Value, you can directly enter the fault message in the field.
If you select Expression, enter the xpath or Qname expression in the field, and click the Namespace Editor icon. The Namespace Editor dialog box opens. To add your namespace, click New. Enter your prefix and URI in the Add Namespace dialog box and click Add.
You can also edit and modify existing namespaces.
Header - This mediator sets or removes a specified header from the current SOAP message.
You can also edit and modify existing namespaces.
XSLT - This mediator applies the specified XSLT transformation to the given element. If the source element is not specified, by default it picks the first child of the SOAP body.
To add more properties, click Add Properties again.
Filter -This mediator either tests the given Xpath expression as a boolean expression, or matches the evaluation result of a source xpath expression against the given regular expression. If the test succeeds, the filter mediator will execute the enclosed mediators in the sequence.
Enter an expression in the Regex field.
In - The In and Out mediators will execute the child mediators over the current message if the message matches the direction of the mediator. Hence all incoming messages would pass through the in mediators.
Out - The In and Out mediators will execute the child mediators over the current message if the message matches the direction of the mediator. Hence all outgoing messages would pass through the out mediators.
Switch - This mediator will evaluate the given source xpath expression into its string value, and match it against the given regular expressions of each case. If there is a match, mediators enclosed in that case will be executed. If the specified cases do not match and a default case exists, it will be executed.
Validate - This mediator validates the result of the evaluation of the source xpath expression against the schema specified. If the source attribute is not specified, the validation is performed against the first child of the SOAP body of the current message.
To enter more than one key, click Add.
To add more properties, click Add Properties again.
Throttle - The throttle mediator limits the message flow based on the specified policy. The throttling policy containing rules for maximum message count, prohibiting period, etc has to be specified either as in-line or as a registry resource. If the throttle mediator accepts a message, it will be sent through the mediators listed under "On Acceptance". Similarly, if a message is rejected by the throttle mediator, it will be passed through the "On Rejection" mediator list.
Select a sequence from either the integrated registry (click a Folder to select a value) or the local registry (click the Key list to select a value), and click Select.
Class - The class mediator lets you add your own mediation written in Java. Once a custom mediator is written in Java, its class file can be specified for the class mediator. The Java code will be executed when the Class mediator is invoked by the ESB. Additionally, it is possible to specify properties for the Class mediator. These properties will be set in the custom mediator object by invoking its corresponding setters before each invocation.
To add more properties, click Add Properties again.
Script - This mediator can be used to add a new mediation using a scripting language.
Click the Registry Browser icon to browse for the script for the key. The WSO2 ESB Registry Browser dialog box opens. Select a script from either the integrated registry (click a Folder to select a value) or the local registry (click the Key list to select a value), and click Select.
Enter the function of the script to be executed by the ESB.
Spring - This element creates an instance of a mediator, which is managed by Spring. This Spring bean must implement the Mediator interface for it to act as a Mediator. The key will reference the Spring ApplicationContext/Configuration used for the bean.
RM Sequence - This mediator is used to create a sequence of messages to communicate via WS-Reliable Messaging with an WS-RM enabled endpoint
You can edit, delete, enable statistics, and enable tracing for sequences as described below. All existing sequences will be displayed in the Sequences table. The sequence actions are initiated by clicking on the respective icons in the table.
Edit Sequence
Use this function to modify the mediators in previously entered sequences. Note that the sequence name cannot be modified.
- In the Actions column of the Sequences table, click the corresponding Edit icon of the sequence you want to edit. The sequence page will be displayed.
- Make the necessary changes and click Save.
Delete Sequence
Use this function to delete entire sequences that have been entered previously.
- In the Actions column of the Endpoints table, click the corresponding Delete icon of the endpoint you want to delete.
A message appears requesting you to confirm the deletion.
- Click Yes to confirm.
Enable Statistics
Use this function to generate statistics for sequences.
- In the Actions column of the Sequences table, click the Enable Statistics icon of the corresponding sequence.
The icon will change colour to indicate that the console has started generating statistics for the sequence. Clicking the icon again, will disable the statistics generation.
Enable Tracing
Use this function to enable tracing for sequences.
- In the Actions column of the Sequences table, click the Enable Tracing icon of the corresponding sequence.
The icon will change colour to indicate that the console has started tracing the sequence. Clicking the icon again will disable the tracing.
The local registry entries are used to locally define resources such as scripts, schemas, WSDLs, policies and other resources in a configuration. They are not uploaded or fetched from the Integrated Registry. They are static. An entry that exists in the local registry has higher precedence over an entry with the same name that exists in the integrated registry.
In-Lined Text
- Enter a name for the entry.
- In the Value field, specify the property values
- Click Save.
In-Lined XML
- Enter a name for the XML entry.
- In the Value field, enter the XML code.
- Click Save.
Source URL
- Enter a name of the source file.
- In the Value field, specify the location of the source file as a URL.
- Click Save.
You can edit and delete previously entered local registry entries. All existing local registry entries will be displayed in the Registry Entries table. The registry actions are initiated by clicking on the respective icons in the table.
Edit Local Registry Entry
Use this option to modify registry entries.
- In the Actions column of the Registry table, click the corresponding Edit icon of the entry you want to edit. The registry entry page will be displayed.
- Make the necessary changes and click Save.
Delete Local Registry Entry
Use this function to delete registry entries that have been entered previously.
- In the Actions column of the Registry table, click the corresponding Delete icon of the entry you want to delete.
A message appears requesting you to confirm the deletion.
- Click Yes to confirm.
This function commits the configuration changes you made to the local storage of the host running the ESB. The XML code for your configuration is displayed in the Current Configuration text area. You can also make any changes directly in the XML code.
Click Reset to clear any configuration changes you made. This will give you the original configuration.
The registry provides a mechanism of creating and storing configuration elements outside the ESB. These registry contents can be dynamically loaded or modified, which will allow runtime modification of the ESB behaviors. The folder structure gives a clear view of the available files and easy access to modifying the files. Once these files are loaded, their content are cached in the ESB for the specified duration, and is updated at the end of the caching period.
You can use these files at the time of defining target sequences and target endpoints for the proxy services.
You can create a structure by creating sub-folders, or simply add the files to the root folders. The Key, i.e., the path of the file and the cacheable duration can be viewed by clicking each file inside the folder.
Add Registry Entry
The New Registry File page will be displayed.
The file will be displayed in the structure. The frame on the right displays the key and the cacheable duration of the file.
Edit Registry Entry
Delete Registry Entry
A message appears requesting you to confirm the deletion.
This feature provides information about the ESB on the Administrator Console. It displays system information, statistics, logs, and trace messages.
Displays information about the operating system, server name, Axis2 location, repository location and other information about the system. This page is just for informational purposes only.
Displays statistics of the server, proxy service, endpoints, and sequences. The statistics are generated only if the Enable Statistics option is active. This page is automatically updated every minute. The statistics consists of the number of requests, fault count, and response times of the messages and services.
Displays all the messages generated by the system.
Displays the message path of the messages sent from and received by the server.