The Administrator Guide describes how to configure the WSO2 ESB using the Web based management console. The WSO2 Management Console has been tested on the Mozilla Firefox 2.0 and Internet Explorer 7 Web Browsers at a resolution of 1024x768.
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:9444/esb. This will take you to the Sign In page of the WSO2 ESB Management Console.
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 is : 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/webapp/WEB-INF/classes/conf folder. You can create multiple user accounts if required as follows.
<ESBUsers> <User> <Username>admin</Username> <Password>admin</Password> <Description>admin</Description> </User> <User> <Username>esb</Username> <Password>esb</Password> <Description>esb</Description> </User> </ESBUsers>
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. |
![]() |
Context-sensitive Help - To learn about a feature, move the mouse pointer to the top of this icon. A context-sensitive help window will pop up. |
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 sequences of mediators. Clicking on the Add Mediator icon will give you the mediators as a context menu.
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, tasks and proxy services. Messages coming into ESB are processed by the underlying Synapse engine through mediation sequences and delivered to the specified endpoints. In addition, scheduled tasks may inject new messages into the ESB periodically or execute other tasks.
Proxy services define virtual services hosted on the ESB that can accept requests, mediate them, and deliver them to an actual service. Proxy services could perform transport or interface 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 endpoint.
- 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 endpoint.
- 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 endpoint.
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.
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.
The built-in Quartz scheduler lets administrators schedule tasks to run at specified intervals. Tasks may be used to initiate long-running tasks, automate recurring processes and facilitate reporting etc. The tasks are simple Java classes that must implement org.apache.synapse.startup.Task interface that just defines a single 'public void execute();' method. A Task may thus use the ESB/Apache Synapse API's to poll external services, inject messages into the ESB or perform any task that could be implemented in Java.
This function allows you to add a scheduled task. At a minimum a task id, fully qualified class name and the trigger type information must be specified. If the task class has setter methods, the UI is able to dynamically load the class so that the administrator could specify the values to be used for initialization of the task.
You can edit, delete, enable statistics and enable tracing for the tasks as described below. All existing scheduled tasks will be displayed in the Manage Tasks table along with their current status. The task actions are initiated by clicking on the respective icons in the table.
Edit Tasks
Use this function to modify existing scheduled tasks.
- In the Actions column of the Manage Tasks table, click the corresponding Edit icon of the task you want to edit. The Edit task page will be displayed.
- Make the necessary changes and click Save.
Delete Task
Use this function to remove any scheduled tasks that have been entered previously.
- In the Actions column of the Manage Tasks, click the corresponding Delete icon of the entry you want to delete.
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 WSDL 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.
- Select the session management method if required. You can select transport, SOAP or client ID based session management. If a session management method is specified, sessions are bound to endpoints in the first client message and all successive messages for those sessions are directed to their associated endpoints.
- 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.
- In the Actions column of the Endpoints table, click the corresponding Delete icon of the endpoint you want to delete.
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, any 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.
DBreport - This mediator can run an SQL statement java a given database and write information from the message into that database. This mediator is used for database write operations.
Pool - Enter database driver class name (database driver should be available in the classpath), database-specific URL, username and password.
Data source - Enter JNDI initial context class name, JNDI data source name, JNDI URL, username and password.
DBlookup - This mediator can run an SQL query in a given database and set the result as properties in the message context. This mediator is used for database read operations.
Pool - Enter database driver class name (database driver should be available in the classpath), database-specific URL, username and password.
Data source - Enter JNDI initial context class name, JNDI data source name, JNDI URL, username and password.
Clone - This mediator can make identical messages (clones) and mediate each of them using the specified sequences and/or send them to the specified endpoints.
Callout - This mediator calls the given service URL with the request message which is given by the source attribute, waits for the response and attaches the received response to the destination which is given by the target attribute.
Iterate - This element is used to iterate a particular message depending on the provided message XPATH.
Cache - This element is used to cache the responses going through the ESB to service new requests coming in to it, without invoking the same operations again, if the request message is already available in the cache.
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.
There is a feature called "“http://ws.apache.org/ns/synapse/transform/feature/dom” and the value for this feature must be defined as "true" or "false".This feature is for deciding switching between DOM and Stream during the transformation process.
All Any other features will be set to the TransformerFactory.
XQuery - This mediator can be used to execute XQuery transformations.
To add more variables, click Add Variable 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 can specify the maximum message count, the prohibited period after reaching the count,maximum concurrent connections, etc. It can be specified either as in-line policy 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.
Command - This mediator is used to execute a method in a user-defined class. The class should implement org.apache.synapse.Command interface or should have public void execute() method.
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.
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.
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
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.
Log settings page allows you to change the log properties and see the changes dynamically.
You can change the log levels of root level, service level and trace level using the given select boxes. These three log level settings will affect the system immediately as soon as you make the change but will not be saved to the log4j.properties file. So it will be restored to the log4j.properties file settings when the system is restarted.
You can change the log4j.properties file contents by editing the text area below. When you click the Save button log properties will be saved and reloaded. Those changes will be permanent. By editing the log4j.properties file you can add new appenders, logging patterns etc. To learn about all the logging configuration options available see http://logging.apache.org/log4j/.