WSO2 ESB v1.6 - Web Administrator Guide

WSO2 Enterprise Service Bus (ESB) v1.6 Administrator Guide

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.

Table of Contents

Installing and Running the WSO2 ESB

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

Accessing the ESB Web 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/esb. This will take you to the Sign In page of the WSO2 ESB Management Console.

Known Issues and Limitations in this Version

  1. Dependencies are currently allowed to be removed while they have live references to them. 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.

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

Changing Your User Name and Password

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>

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.
Update Update - Click this icon to save your current changes, modifications, etc.
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.
Add Mediator 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 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.
Context-sensitive Help 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.

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 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. Sequence Editor 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. Add namespace

Managing the underlying Synapse Configuration

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

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 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.
  1. Click Proxy Services on the navigator, and then click Add on the New Proxy Service pane.
  2. Enter the proxy service name.
  3. Specify the target sequences and the target endpoint. 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. Basic Config 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.
      1. Click the Add icon, and point to Declared Sequences. The sequences will be displayed as a submenu.
      2. 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.
      1. Click the Add icon, and click Specify as Anonymous. The WSO2 ESB Sequence Editor dialog box opens.
      2. Click the Add Mediator icon and create your sequence as required.
      3. Click Save. The label Anonymous Sequence will be displayed next to the target sequence.
    • Pick from Registry - Specifies a sequence from the ESB registry.
      1. Click the Add icon, and click Pick from Registry. The WSO2 ESB Registry Browser dialog box opens.
      2. 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.
      1. Click the Add icon, and point to Declared Endpoints. The available endpoints will be displayed as a submenu.
      2. 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.
      1. Click the Add icon and point to Specify as Anonymous. The endpoint options will be displayed as a submenu.
      2. 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.
      1. Click the Add icon, and click Pick from Registry. The WSO2 ESB Registry Browser dialog box opens.
      2. 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.
  5. Click Finish to save the basic configuration. Else click Advanced to specify more configuration options. Advanced Proxy Configurations
    1. After adding the basic configuration details, click Advanced. The Transport Configuration page will be displayed.
    2. Select the corresponding check box of the transports you want to use. The currently available options are HTTP, HTTPS, JMS, Mail, and VFS.

      Note that the JMS & Mail transport options will not be available unless you have enabled them through the axis2.xml file.
    3. To add service parameters, click Add.
    4. Enter the parameter name and value. To add another parameter, click Add again. Click the Delete icon to remove any service parameters that you do not require.
    5. Click Next. The QoS Configuration page will be displayed.
    6. Select the corresponding check box of the QoS features you want to activate.
    7. To add service policies, click the Registry Browser icon. The WSO2 ESB Registry Browser dialog box opens.
    8. Select a policy 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.
    9. To add another policy, click Add again.
    10. Click Next. The Miscellaneous Configuration page will be displayed.
    11. To publish a WSDL for the proxy service, click the Add icon. Three options will be displayed as a submenu.
      • Specify Source URL A Source URL field will appear when you select this option. Specify the location of the WSDL in this field.
      • Pick from Registry 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.
      • Specify In-Line The In-Lined WSDL Editor will appear when you select this option. Enter your WSDL and click Save.
    12. Select the Load on startup check box if you want the proxy service to start automatically when the server is started.
    13. Click Finish.

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 Proxy Services table along with their current status. The proxy service actions are initiated by clicking on the respective icons in the table. Proxy Services
Edit Proxy Service Use this function to modify existing proxy services.
  1. 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.
  2. 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.

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

Adding a Scheduled Task

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.
  1. Click Tasks on the navigator, and then click Add on the Manage Task pane.
  2. Enter the task name and the fully qualified class name
  3. Click Load Class to load the available properties that could be set on the class and supply any values where applicable
  4. Specify trigger type as either Simple or Cron, and supply the count and the interval or the Cron expression
Task Config

Scheduled Task Actions

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. Scheduled Tasks
Edit Tasks Use this function to modify existing scheduled tasks.
  1. 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.
  2. 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.

Endpoints

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.

Adding an Endpoint

  1. Click Endpoints on the navigator.
  2. In the Manage Endpoints pane, click Add and select the endpoint you want to configure. Add Endpoint
Address Endpoint An endpoint is defined by specifying the EPR and other attributes of the endpoint directly in the configuration.
  1. 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.
  2. Select the WS-Addressing check box to engage the WS-addressing module for the outgoing message.
  3. 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.
  4. To specify a policy key, click the Registry Browser icon. The WSO2 ESB Registry Browser dialog box opens.
  5. 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.
  6. If you want to specify reliable messaging policies, select the WS-RM check box, and follow steps 4 to 6.
  7. 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.
  1. Enter the name of the WSDL document.
  2. If you want to specify the WSDL document as a URI, click URI and specify the URI in the WSDL URI field.
  3. 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.
  4. 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.
  5. Select the WS-Addressing check box to engage the WS-addressing module for the outgoing message.
  6. 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.
  7. To specify a policy key, click the Registry Browser icon. The WSO2 ESB Registry Browser dialog box will open.
  8. 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.
  9. If you want to specify reliable messaging policies, select the WS-RM check box, and follow steps 4 to 6.
  10. 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.
  1. Enter a name for the failover endpoint.
  2. Click the Add Endpoint icon. The context menu will display the available endpoint options as well as the Lookup Endpoint option.
  3. 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.
  4. 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.
  1. Enter a name for the load-balance endpoint.
  2. 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.
  3. Click the Add Endpoint icon. The context menu will display the available endpoint options as well as the Lookup Endpoint option.
  4. 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.
  5. Click Save.

Endpoint Actions

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. Endpoints
Edit Endpoint Use this function to modify previously entered endpoints. Note that the endpoint name cannot be modified.
  1. 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.
  2. 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.

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. 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:

Adding a Sequence

You can create completely new sequences, or copy an existing sequence (its mediators and properties) and rename it.
  1. Click Sequences on the navigator, and then click Add in the Sequence Management pane. The Define New Sequence page will be displayed.
  2. On this page, click the Add Mediator icon, and select the appropriate mediator from the context menu. Add mediator
  3. Enter the details for the selected mediator (Each mediator is described below.)
    • To add more mediators click the Add icon, and select the mediator you want.
    • To move the position of a mediator in the sequence, click the Move Up or Move Down icon.
    • To delete a mediator, click the Delete icon.
  4. Click Save and a dialog box will open to specify a name for the sequence.
  5. Enter the sequence name and click Save. You can use the Save As button to copy and save a sequence in a different sequence name.

Adding Core Mediators

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.
  1. Select the log level and indicate the log separator.
  2. Optionally, you can also define properties for the log mediator by clicking Add Properties.
  3. Enter the property name, type, and expression in the Properties table. To add more properties, click Add Properties again.
  4. Click the the Update icon to save your changes.
Property - This element, which is a mediator, has no direct impact on the message but rather on the message context flowing through Synapse.
  1. Enter the name of the property.
  2. Indicate whether you want certain values set or removed from the messages by selecting the Set or Remove option respectively.
  3. Click Value or Expression to specify the text you want to set or remove.
    • If you click Value, you just have to enter the text in the field.
    • If you click 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.
  4. Click the Update icon to save your changes.
Send - This element is used to send messages out of Synapse to an endpoint.
  1. Click the Add Endpoint icon. The context menu will display the available endpoint options as well as the Lookup Endpoint option.
  2. 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. Note that there will not be a name field. Please refer to Adding Endpoints for more details.
  3. Click the Update icon to save your changes.
Sequence - This element is used to invoke a named sequence of mediators.
  1. Click the Registry Browser icon. The WSO2 ESB Registry Browser dialog box opens.
  2. 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.
  3. Click the Update icon to save your changes.
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.
  1. Enter database connection details. Either you can create a local database connection pool or use an external data source accessed through JNDI. Apache DBCP is used for local database connection pools. 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.
  2. For a local database connection pool, you can define passional properties.  Select a property name and enter a value.
  3. Enter the SQL statement.  You can have parameters in the SQL statement specified by '?'. For each parameter specify the parameter type (NUMERIC, VARCHAR, etc.), and a value or  an XPath expression to get the parameter value.
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.
  1. Enter database connection details. Either you can create a local database connection pool or use an external data source accessed through JNDI. Apache DBCP is used for local database connection pools. 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.
  2. For a local database connection pool, you can define additional properties.  Select a property name and enter a value.
  3. Enter the SQL query.  You can have parameters in the SQL statement specified by '?'. For each parameter specify the parameter type (NUMERIC, VARCHAR, etc.), and a value or  an XPath expression to get the parameter value.
  4. Map result columns to message properties.
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.
  1. Click Add Target button to specify the target information for each cloned instance.
  2. Enter a sequence or an endpoint or both.  The sequence or endpoint can be looked up from the registry or can be defined inline.
  3. Set Continue Parent to true if the parent message should continue or set to false if the parent message should be dropped.
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.
  1. Enter service URL and the optional action attribute. The mediator will call this service.
  2. Enter how to extract the request message for sending in the source field. You can enter a key or an XPath. The key refers to a message context property or a local entry.
  3. Enter where to append the response message received in the target field.
Iterate - This element is used to iterate a particular message depending on the provided message XPATH.
  1. Set the Continue Parent to true if you want the parent message to be continued after the iteration or false if it needs to be dropped
  2. Specify the Iterate Expression to set the iteration XPATH over the message
  3. Preserve Payload is set to true if you want the messages payload created by iteration needs to be preserved or false if the payload is just the iterated element
  4. Attach Path is only valid when the Preserve Payload is set to true and is used to specify the XPATH of message to which the iterated element is attached
  5. Target is set to mediate the iterated messages using the given sequence or send the iterated messages to the specified endpoint, both of which can be a reference as well as specified inline
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.
  1. Specify the Cache Id (which can be any string without special characters)
  2. If the cache mediator is on the in message path, Cache Type should be set to the finder, where as in out flow, it should be set to the Collector
  3. Hash Generator specifies the XML hash generation algorithm to find the message equivalence
  4. Select the Per-Host scope to set a global cache for the ESB instance or if the cache is specific to the message path then it should be Per-Mediator
  5. Set the Cache timeout to specify the cache validation time and should be an int or a long value
  6. ESB only supports the In-Memory cache for the moment so the Cache Type can not be changed
  7. Maximum Size specifies the cache overflow limit
  8. For a Cache Hit, there is a mediation sequence which can be specified inline as well as set as a reference

Adding Transform 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.
  1. Specify the SOAP version and select the FaultCode.
  2. The FaultString can be a value or an expression. Select the applicable option. 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.
  3. Specify the FaultActor. This is the URI of the entity that caused the fault to happen as specified in the SOAP specification.
  4. In the Detail field, enter a description of the fault.
  5. Click the Update icon to save your changes.
Header - This mediator sets or removes a specified header from the current SOAP message.
  1. In the Name field, enter the name for the header, 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
  2. Click Value or Expression to specify the header text.
    • If you click Value, you just have to enter the text in the field.
    • If you click 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.
  3. Select Set or Remove to indicate whether you want the text set or removed from the header respectively.
  4. Click the Update icon to save your changes.
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.
  1. To specify the XSLT key, click the Registry Browser icon. The WSO2 ESB Registry Browser dialog box opens.
  2. Select a key 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.
  3. In the Source field, enter the xpath or Qname expression, 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.
  4. Optionally, you can also define properties for the XSLT mediator by clicking Add Properties.
  5. Enter the property name, type, and expression in the Properties table. To add more properties, click Add Properties again.
  6. Optionally, you can also define features for the XSLT mediator by clicking Add Feature. 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.
  7. Click the Update icon to save your changes.
XQuery - This mediator can be used to execute XQuery transformations.
  1. Click the Registry Browser icon. The WSO2 ESB Registry Browser dialog box opens.
  2. Select a xquery key 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.
  3. In the Target field, enter the xpath or Qname expression, 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.
  4. Add variables that needs to be specified into the XQuery engine in order for them to be accessed through the script. You can also define variables for the XQuery mediator by clicking Add Variable.
  5. Enter the variable type,name and value/expression in the Variable table. Optionally, you can specify a registry key for the variable that has value type as an expression. To add more variables, click Add Variable again.
  6. Click the Update icon to save your changes.

Adding Filters

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.
  1. You can either enter a source and a regular expression or enter an xpath. Click the applicable option.
    • If you click XPath, enter the xpath 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.
    • If you click Source and Regular Expression, enter the source 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. Enter an expression in the Regex field.
  2. Click the Update icon to save your changes.
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.
  1. In the Source Xpath field, enter the xpath expression 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.
  2. Click the Add Case icon and specify the regular expression in the Case Regular Expression field. Click the Update icon to save the changes. The case expression will be indicated under the Switch Case icon.
  3. Optionally, you can add mediators to this expression, by clicking the Add Mediator icon.
  4. Click the Default Case icon to specify the default expression that will be executed. Click the Add Mediator icon to add mediators to the expression. Click the Update icon to save the changes.
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.
  1. To enter the schema key that validates the source, click the Registry Browser icon. The WSO2 ESB Registry Browser dialog box opens.
  2. 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. To enter more than one key, click Add.
  3. Enter the source xpath expression that will be validated.
  4. Optionally, you can also define properties for the XSLT mediator by clicking Add Properties.
  5. Enter the property name, type, and expression in the Properties table. To add more properties, click Add Properties again.
  6. Click the Update icon to save your changes.
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.
  1. You can specify a throttling policy as an in-lined policy or a registry key, by selecting the appropriate radio button option.
    • If you click In-Lined Policy, Edit Policy icon will be displayed. By clicking this icon, the In-Lined Policy Viewer dialog box opens. Enter your policy and click Save.
    • If you click Referring Policy,the Registry Browser icon appears next to the Referring Policy field. Click the Registry Browser icon. 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.
  2. Specify the mediators to be executed on acceptance and on rejection.
  3. Optionally , you can specify an id for the throttle mediation by filling throttle ID text field. This will be used only if the throttle policy contains a 'MaximumConcurrentAccess' assertion. In this scenario, in order to count completed requests, you have to define the throttle mediator with the same 'id' at both the IN and OUT message mediation flow paths.
  4. Click the Update icon to save your changes.

Adding Extensions

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.
  1. Enter the name for the class.
  2. Optionally, you can also define properties for the Class mediator by clicking Add Properties.
  3. Enter the property name, type, and value / expression in the Properties table. To add more properties, click Add Properties again.
  4. Click the Update icon to save your changes.
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.
  1. Enter class name and click Load Class.  (Class should be in the classpath.)
  2. If the class has set methods which take single String, int, long, float, double or boolean value,  you can enter values as literals or XPath expressions.
Script - This mediator can be used to add a new mediation using a scripting language.
  1. Select the script type.
    • If you select In-Line, you have to specify the language of the script and the source script itself.
    • If you select Registry Key, you have to specify the language of the script, select a script for the key from the registry and also specify the function. 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.
  2. Enter the language of the script. The currently supported languages are JavaScript, Ruby, and Groovy.
  3. Click the Update icon to save your changes.
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.
  1. Enter the Spring bean value, and select the key from the registry. Click the Registry Browser icon. The WSO2 ESB Registry Browser dialog box opens.
  2. Select a key 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.
  3. Click the Update icon to save your changes.
RM Sequence - This mediator is used to create a sequence of messages to communicate via WS-Reliable Messaging with an WS-RM enabled endpoint
  1. Specify the WS-RM version and the message sequence by selecting the appropriate options.
  2. If the Correlated sequence is selected as the Message sequence, two input fields will appear to specify the sequence XPath and the last message XPath. All messages matching the sequence XPath will be sent in the same RM sequence. Last message XPath is used to determine the last message of the sequence. RM sequence will be terminated after the last message.
  3. Click the Update icon to save your changes.

Sequence Actions

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. Sequences
Edit Sequence Use this function to modify the mediators in previously entered sequences. Note that the sequence name cannot be modified.
  1. 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.
  2. 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.

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 Registry on the navigator.
  2. In the Manage Local Registry Entries pane, click Add and select the registry entry you want to add. 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.

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 Registry
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.

Configuration

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.
  1. If required, update the existing code in the Current Configuration text area.
  2. Click Update.
  3. Then click Save. This will save all the configurations that you made. Click Reset to clear any configuration changes you made. This will give you the original configuration.

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

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. Integrated Registry Add Registry Entry
  1. To create a folder, enter a name in the Folder Name field and click Add.
  2. To create a new file, click the appropriate folder and then click New. The New Registry File page will be displayed.
  3. Enter the file name and write the XML code in the text area.
  4. Click Create. The file will be displayed in the structure. The frame on the right displays the key and the cacheable duration of the file.
  5. To update the duration of the caching, if required, modify the duration in the Cacheable duration field and click Update.
Edit Registry Entry
  1. Select the file from the folder structure and click Edit.
  2. Make the necessary changes in the code and click Save.
  3. If required, you can also modify the cacheable duration and click Update.
Delete Registry Entry

Monitoring the System

This feature provides information about the ESB on the Administrator Console. It displays system information, statistics, logs, and trace messages.

System Information

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.

Statistics

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.

System Logs

Displays all the messages generated by the system.

Trace Messages

Displays the message path of the messages sent from and received by the server.

Log Settings

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/. Log settings

References

WSO2 ESB Installation Guide Synapse Configuration Language