WSO2 ESB - User Guide [ Documentation Index ]

WSO2 Enterprise Service Bus (ESB) User Guide

The User Guide describes how to configure WSO2 ESB using the Web based management console. The WSO2 Management Console has been tested on the Mozilla Firefox 2.0, 3.0 and Internet Explorer 6.0, 7.0 Web Browsers at a resolution of 1024x768.

Contents

Installing and Running the WSO2 ESB

Please refer the Installation Guide for details on how to install and run the WSO2 ESB.

Accessing the ESB Web based Management Console

Once WSO2 ESB has been successfully installed and started, launch a Web browser instance and point it to the URL https://localhost:9443/carbon. This will take you to the Sign In page of the WSO2 ESB Management Console.

Signing In

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 get any errors when trying to sign in, click Sign-in Help. A list of possible errors, their descriptions and solutions will be displayed.

Changing Your User Name and Password

You can change the default password using user management. Click on User Management menu from left.

Please refer the documentation on managing users for details.

Icons and Descriptions

Icon Description
Add 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 Edit - Click this icon to modify an existing item.
Delete Delete - Click this icon to permanently delete an item. A message will appear prompting you to confirm the deletion.
Registry Picker 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. Also user has the option of choosing from the Governance registry as well as from the Configuration registry.
Namespace Namespace Editor - Click this icon to open the Namespace Editor dialog box.
Stats Enabled Disable Statistics - This icon indicates that statistics generation is in progress. Click this icon to stop statistics generation for the respective element.
Stats Disabled Enable Statistics - This icon indicates that statics are not been generated at present. Click this icon to start statistics generation for the respective element.
Trace Enabled Disable Tracing - This icon indicates that message tracing is in progress. Click this icon to stop tracing for the respective element.
Trace Disabled Enable Tracing - This icon indicates that messages are not been traced at present. Click this icon to start tracing messages for the respective element.
Proxy Service Proxy Service - This icon will be used to denote Proxy Services on the services listing page.
Context-sensitive Help Context-sensitive Help - To learn about a feature, click this icon. A context-sensitive help window will pop up.

Common Screens and Dialog Boxes

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.

Registry Browser

Add Namespace - This dialog box is invoked by clicking Namespaces link from the configuration section of mediators. 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.

Add namespace

Managing the underlying Synapse Configuration

The Synapse configuration language consists of endpoints, sequences, registry entries, tasks, proxy services and more. 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

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.

Adding a Proxy Service

This function allows you to add a proxy service. Please refer Adding a Proxy Service for details.

Proxy Service Actions

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 services listing page with a special icon been used to denote Proxy Services. Clicking on the name of a Proxy Service there will take you to configurations specific to that service. The proxy service actions are initiated by clicking on the respective links that could be found in the in the table.

Proxy Services

Please refer the documentation of the service listing page for general configurations that could be done on a proxy service.

Proxy Service specific configurations

Edit Proxy Service

Use this function to modify existing proxy services.

  1. In the Specific Configuration section of the Proxy Service click the Edit link. The proxy service page will be displayed.

Redeploy Proxy Service

Use this function to redeploy the proxy service.

  1. In the Specific Configuration section of the Proxy Service click the Redeploy link. This will redeploy the proxy service.

Enable Statistics

Use this function to generate statistics for the proxy services.

  • In the Specific Configuration section of the Proxy Service click the Enable Statistics link.

Enable Tracing

Use this function to enable tracing for the proxy services.

  • In the Specific Configuration section of the Proxy Service click the Enable Tracing link.

Scheduled Tasks

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 APIs to poll external services, inject messages into the ESB or perform any task that could be implemented in Java.

Please refer the documentation on scheduled tasks for details.

Endpoints

An endpoint is a specific destination for a message. It may be specified as an Address endpoint, WSDL endpoint, a fail over group, or a load balance group.

Endpoints can be added, edited, and deleted. You can also enable statistics for Address and WSDL endpoints.

Please refer the documentation on endpoints for details.

Sequences

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. If User doesn't define a main or fault sequence ESB will create default sequences.

Please refer the documentation on managing sequences for details.

Message Stores

A Message Store element is used to define a Message store that can be used to store ESB Messages. Store mediator can be used to store the messages in a message store.Message processor associated with Message store can be used to implement different messaging patterns.

Associated Message processors can be used to consume messages from message stores and do processing.

Users can create there own message store implementations and use it. WSO2 ESB ships with in memory message store and a jms message store.

Please refer the documentation on managing Message stores for details.

Message Processor

A sequence element is used to define a Message Processor which can be used to process messages in an associated message store.

Please refer the documentation on managing sequences for details.

Local Registry Entries

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.

Adding a Local Registry Entry

  1. Click Local Entries on the navigator.
  2. In the Manage Local Registry Entries pane, you can choose the type of local entry you want and click Add of each entry to add a one.

    Registry Entry

In-Lined Text

  1. Enter a name for the entry.
  2. In the Value field, specify the property values
  3. Click Save.

In-Lined XML

  1. Enter a name for the XML entry.
  2. In the Value field, enter the XML code.
  3. Click Save.

Source URL

  1. Enter a name of the source file.
  2. In the Value field, specify the location of the source file as a URL.
  3. Click Save.

Local Registry Actions

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.

Local entry actions

Edit Local Registry Entry

Use this option to modify registry entries.

  1. 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.
  2. 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.

ESB Configuration (Source View)

This function commits the configuration changes you have 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.

To apply your changes and save the configuration to the local storage click the Update button. This will first validate the provided configuration and warn you about any faults or inconsistencies detected. User has the option of proceeding with the update operation or cancelling it at this point. If no faults are detected, the configuration will be applied and saved to the storage.

The Reset operation could be used to revert any changes you have made to the source view and revert back to last saved configuration.

Please refer the documentation on managing synapse configuration for details.

Managing the Integrated Registry

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.

Manage Registry Entry

Please refer the documentation on managing the embedded registry for details.

Monitoring the System

This feature provides runtime information about the ESB on the Administrator Console. It displays system statistics, mediation statistics, transport statistics, system logs, SOAP tracer, mediation tracer and Message flows.

A detailed guide on monitoring WSO2 ESB can be found here.

References

WSO2 ESB Installation Guide

ESB Configuration Language