<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
  ~  Copyright (c) 2009, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
  ~
  ~  WSO2 Inc. licenses this file to you under the Apache License,
  ~  Version 2.0 (the "License"); you may not use this file except
  ~  in compliance with the License.
  ~  You may obtain a copy of the License at
  ~
  ~    http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~  Unless required by applicable law or agreed to in writing,
  ~  software distributed under the License is distributed on an
  ~  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~  KIND, either express or implied.  See the License for the
  ~  specific language governing permissions and limitations
  ~  under the License.
  -->

<!DOCTYPE html
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <title>
      WSO2 ESB - User Guide
    </title>
    <link href="css/esb-docs.css" rel="stylesheet"/>
    <link href="styles/dist-docs.css" rel="stylesheet" type="text/css" media="all"/>
  </head>
  <body>
      [ <a href="docs_index.html"> Documentation Index </a> ]
    <h1>
      WSO2 Enterprise Service Bus (ESB) User Guide
    </h1>
    <p>
      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.
    </p>
    <h2>Contents</h2>
    <div class="toc">
      <ul>
        <li>
          <a href="#Installing">Installing and Running the WSO2 ESB</a>
        </li>
        <li>
          <a href="#Accessing">Accessing the ESB Web based Management Console</a>
        </li>
        <li>
          <a href="#Signing">Signing In</a>
          <ul>
            <li>
              <a href="#Changing">Changing Your User Name and Password</a>
            </li>
            <li>
              <a href="#Icons">Icons and Descriptions</a>
            </li>
            <li>
              <a href="#Common">Common Screens and Dialog Boxes</a>
            </li>
          </ul>
        </li>
        <li>
          <a href="#Managing">Managing the Elements in a Synapse
          Configuration</a>
          <ul>
            <li>
              <a href="#Proxy">Proxy Services</a>
              <ul>
                <li>
                  <a href="#Adding">Adding a Proxy Service</a>
                </li>
                <li>
                  <a href="#Proxy1">Proxy Service Actions</a>
                </li>
              </ul>
            </li>
            <li>
              <a href="#Task">Scheduled Tasks</a>              
            </li>
            <li>
              <a href="#Endpoints">Endpoints</a>              
            </li>
            <li>
              <a href="#Sequences">Sequences</a>              
            </li>
            <li>
              <a href="#MessageStores">Message Stores</a>
            </li>
              <li>
                  <a href="#MessageProcessors">Message Processors</a>
              </li>
            <li>
              <a href="#Local">Local Registry Entries</a>
              <ul>
                <li>
                  <a href="#Local1">Adding a Local Registry Entry</a>
                </li>
                <li>
                  <a href="#Registry">Registry Actions</a>
                </li>
              </ul>
            </li>
            <li>
              <a href="#Configurat">Configuration</a>
            </li>
          </ul>
        </li>
        <li>
          <a href="#Managing1">Managing the Integrated Registry</a>
          <ul>
            <li>
              <a href="#Manage">Manage Registry Entry</a>
            </li>
          </ul>
        </li>
        <li>
          <a href="#Monitoring">Monitoring the System</a>
        </li>
        <li>
          <a href="#References">References</a>
        </li>
      </ul>
    </div>
    <h2 id="Installing">
      Installing and Running the WSO2 ESB
    </h2>
    <p>
      Please refer the <a href="installation_guide.html">Installation Guide</a>
      for details on how to install and run the WSO2 ESB.
    </p>
    <p>
      <a id="access"/>
    </p>
    <h2 id="Accessing">
      Accessing the ESB Web based Management Console
    </h2>
    <p>
      Once WSO2 ESB has been successfully installed and started, launch a Web
      browser instance and point it to the URL <a
      href="https://localhost:9443/carbon">https://localhost:9443/carbon</a>.
      This will take you to the <em>Sign In</em> page of the WSO2 ESB
      Management Console.
    </p>
    <h2 id="Signing">
      Signing In
    </h2>
    <p>
      Enter your user name and password to log on to the ESB Management Console.
    </p>
    <p>
      <strong>The default username / password is : admin / admin</strong>
    </p>
    <p>
      You can change your password using the <a href="#Changing">instructions</a>
      given below.
    </p>
    <p>
      If you get any errors when trying
      to sign in, click <strong>Sign-in Help</strong>. A list of
      possible errors, their descriptions and solutions will be displayed.
    </p>
    <h3 id="Changing">
      Changing Your User Name and Password
    </h3>
      <p>
          You can change the default password using user management. Click on User Management menu
          from left.
      </p>
      <p>
          Please refer the <a href="user/docs/userguide.html">documentation</a> on managing
          users for details.
      </p>
    <h3 id="Icons">
      Icons and Descriptions
    </h3>
    <table border="1">
      <tbody>
        <tr>
          <td>
            <strong>Icon</strong>
          </td>
          <td>
            <strong>Description</strong>
          </td>
        </tr>
        <tr>
          <td>
            <img alt="Add" src="images/add.gif"/>
          </td>
          <td>
            <strong>Add</strong> - Click this icon to add an item. Most
            often clicking on this icon gives a submenu from which you can
            select an element.
          </td>
        </tr>
        <tr>
          <td>
            <img alt="Edit" src="images/edit.gif"/>
          </td>
          <td>
            <strong>Edit</strong> - Click this icon to modify an
            existing item.
          </td>
        </tr>
        <tr>
          <td>
            <img alt="Delete" src="images/delete.gif"/>
          </td>
          <td>
            <strong>Delete</strong> - Click this icon to permanently
            delete an item. A message will appear prompting you to confirm the
            deletion.
          </td>
        </tr>
        <tr>
          <td>
            <img alt="Registry Picker" src="images/registry_picker.gif"/>
          </td>
          <td>
            <strong>Registry Browser</strong> - 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.
          </td>
        </tr>
        <tr>
          <td>
            <img alt="Namespace" src="images/nseditor-icon.gif"/>
          </td>
          <td>
            <strong>Namespace Editor</strong> - Click this icon to open
            the <em>Namespace Editor</em> dialog box.
          </td>
        </tr>
        <tr>
          <td>
            <img alt="Stats Enabled" src="images/stat-icon.gif"/>
          </td>
          <td>
            <strong>Disable Statistics</strong> - This icon indicates
            that statistics generation is in progress. Click this icon to stop
            statistics generation for the respective element.
          </td>
        </tr>
        <tr>
          <td>
            <img alt="Stats Disabled" src="images/stat-icon-disabled.gif"/>
          </td>
          <td>
            <strong>Enable Statistics</strong> - This icon indicates
            that statics are not been generated at present. Click this icon to
            start statistics generation for the respective element.
          </td>
        </tr>
        <tr>
          <td>
            <img alt="Trace Enabled" src="images/tracer-icon.gif"/>
          </td>
          <td>
            <strong>Disable Tracing</strong> - This icon indicates that
            message tracing is in progress. Click this icon to stop tracing for
            the respective element.
          </td>
        </tr>
        <tr>
          <td>
            <img alt="Trace Disabled" src="images/tracer-icon-disabled.gif"/>
          </td>
          <td>
            <strong>Enable Tracing</strong> - This icon indicates that
            messages are not been traced at present. Click this icon to start
            tracing messages for the respective element.
          </td>
        </tr>
          <tr>
          <td>
            <img alt="Proxy Service" src="images/proxy-service.gif"/>
          </td>
          <td>
            <strong>Proxy Service</strong> - This icon will be used to denote
              Proxy Services on the services listing page.
          </td>
        </tr>
        <tr>
          <td>
            <img alt="Context-sensitive Help" src="images/help.gif"/>
          </td>
          <td>
            <strong>Context-sensitive Help</strong> - To learn about a
            feature, click this icon. A context-sensitive help window will pop up.
          </td>
        </tr>
      </tbody>
    </table>
    <p/>
    <h3 id="Common">
      Common Screens and Dialog Boxes
    </h3>
    <p/>
    <p>
      <strong>Registry Browser </strong>- This dialog box is invoked
      from the <strong>Pick from Registry</strong> option. The Registry
      Browser contains elements from the integrated registry and the local
      registry.
    </p>
    <p/>
    <p>
      <img alt="Registry Browser" src="images/registrybrowser.png"/>
    </p>
    <p/>
    <p>
      <strong>Add Namespace</strong> - This dialog box is invoked by
      clicking <em>Namespaces</em> 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.
    </p>
    <p>
      <img alt="Add namespace" src="images/ns-add.png"/>
    </p>
    <p/>
    <h2 id="Managing">
      Managing the underlying Synapse Configuration
    </h2>
    <p>
      The <a href="configuration_language.html">Synapse configuration
      language</a> 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.
    </p>
    <h3 id="Proxy">
      Proxy Services
    </h3>
    <p>
      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.
    </p>
    <p/>
    <h4><a id="Adding"></a>
      Adding a Proxy Service
    </h4>
    <p>
      This function allows you to add a proxy service. Please refer
        <a href="proxyservices/docs/userguide.html">Adding a Proxy Service</a> for details.
    </p>
    <h4><a id="Proxy1"></a>
      Proxy Service Actions
    </h4>
    <p>
      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.
    </p>
    <p/>
    <p>
      <img alt="Proxy Services" src="images/proxy.png"/>
    </p>
    <p/>
      <p>
          Please refer the <a href="service-mgt/docs/userguide.html">documentation</a> of
          the service listing page for general configurations that could be done on a proxy service.
      </p>
      <p>
        <strong>Proxy Service specific configurations</strong>
      </p>
      <blockquote>
      <p>
        <strong>Edit Proxy Service</strong>
      </p>
      <p>
        Use this function to modify existing proxy services.
      </p>
      <ol>
        <li>
          In the <strong>Specific Configuration</strong> section of the Proxy Service
          click the Edit link. The proxy service page will be displayed.
        </li>
      </ol>
      <p>
        <strong>Redeploy Proxy Service</strong>
      </p>
      <p>
        Use this function to redeploy the proxy service.
      </p>
      <ol>
        <li>
          In the <strong>Specific Configuration</strong> section of the Proxy Service
          click the Redeploy link. This will redeploy the proxy service.
        </li>
      </ol>
      <p>
        <strong>Enable Statistics</strong>
      </p>
      <p>
        Use this function to generate statistics for the proxy services.
      </p>
      <ul>
        <li>
          In the <strong>Specific Configuration</strong> section of the Proxy Service
          click the Enable Statistics link.
        </li>
      </ul>
    </blockquote>
    <blockquote>
      <p>
        <strong>Enable Tracing</strong>
      </p>
      <p>
        Use this function to enable tracing for the proxy services.
      </p>
      <ul>
        <li>
          In the <strong>Specific Configuration</strong> section of the Proxy Service
          click the Enable Tracing link.
        </li>
      </ul>
    </blockquote>
    <p/>
    <h3 id="Task">
      Scheduled Tasks
    </h3>
    <p>
      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.
    </p>
    <p>
        Please refer the <a href="task/docs/userguide.html">
        documentation</a> on scheduled tasks for details.
    </p>
    <h3 id="Endpoints">
      Endpoints
    </h3>
    <p>
      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.
    </p>
    <p>
      Endpoints can be added, edited, and deleted. You can also enable
      statistics for Address and WSDL endpoints.
    </p>
    <p>
      Please refer the <a href="endpoints/docs/userguide.html">documentation</a> on
      endpoints for details.
    </p>
    <h3 id="Sequences">
      Sequences
    </h3>
    <p>
      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.
    </p>
   <p>
       Please refer the <a href="sequences/docs/userguide.html">documentation</a> on managing
       sequences for details.
   </p>

      <h3 id="MessageStores">
          Message Stores
      </h3>
      <p>
          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.
      </p>
      <p>
        Associated Message processors can be used to consume messages from message stores and do processing.
      </p>
      <p>
          Users can create there own message store implementations and use it. WSO2 ESB ships with in memory
          message store and a jms message store.
      </p>
      <p>
          Please refer the
          <a href="message_store/docs/userguide.html">documentation</a>
          on managing
          Message stores for details.
      </p>
      <h3 id="MessageProcessors">
          Message Processor
      </h3>
      <p>
          A sequence element is used to define a Message Processor which can be used to process messages
          in an associated message store.
      </p>
      <p>
          Please refer the
          <a href="sequences/docs/userguide.html">documentation</a>
          on managing
          sequences for details.
      </p>
    <h3 id="Local">
      Local Registry Entries
    </h3>
    <p>
      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.
    </p>
    <h4><a id="Local1"></a>
      Adding a Local Registry Entry
    </h4>
    <ol>
      <li>
        Click <strong>Local Entries</strong> on the navigator.
      </li>
      <li>
        In the Manage Local Registry Entries pane, you can choose the type of
          local entry you want and click <strong>Add</strong> of each entry to add a
          one.
        <p/>
        <p>
          <img alt="Registry Entry" src="images/registry-entry-types.png"/>
        </p>
        <p/>
      </li>
    </ol>
    <blockquote>
      <p>
        <strong>In-Lined Text</strong>
      </p>
    </blockquote>
    <blockquote>
      <ol>
        <li>
          Enter a name for the entry.
        </li>
        <li>
          In the <strong>Value</strong> field, specify the property
          values
        </li>
        <li>
          Click <strong>Save</strong>.<br/>
        </li>
      </ol>
      <p>
        <strong>In-Lined XML</strong>
      </p>
    </blockquote>
    <blockquote>
      <ol>
        <li>
          Enter a name for the XML entry.
        </li>
        <li>
          In the <strong>Value</strong> field, enter the XML code.
        </li>
        <li>
          Click <strong>Save</strong>.
        </li>
      </ol>
      <p>
        <strong>Source URL</strong>
      </p>
      <ol>
        <li>
          Enter a name of the source file.
        </li>
        <li>
          In the <strong>Value</strong> field, specify the location of
          the source file as a URL.
        </li>
        <li>
          Click <strong>Save</strong>.
        </li>
      </ol>
    </blockquote>
    <h4><a id="Registry"></a>
      Local Registry Actions
    </h4>
    <p>
      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.
    </p>
    <p/>
    <p>
      <img alt="Local entry actions" src="images/editing-registry-entry.png"/>
    </p>
    <p/>
    <blockquote>
      <p>
        <strong>Edit Local Registry Entry</strong>
      </p>
      <p>
        Use this option to modify registry entries.
      </p>
      <ol>
        <li>
          In the <strong>Actions</strong> column of the Registry table,
          click the corresponding Edit icon of the entry you want to edit. The
          registry entry page will be displayed.
        </li>
        <li>
          Make the necessary changes and click <strong>Save</strong>.
        </li>
      </ol>
      <p>
        <strong>Delete Local Registry Entry</strong>
      </p>
      <p>
        Use this function to delete registry entries that have been entered
        previously.
      </p>
      <ul>
        <li>
          In the <strong>Actions</strong> column of the Registry table,
          click the corresponding Delete icon of the entry you want to delete.
        </li>
      </ul>
    </blockquote>
    <h3 id="Configurat">
      ESB Configuration (Source View)
    </h3>
    <p>
      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.
    </p>
    <p>
      To apply your changes and save the configuration to the local storage click
      the <strong>Update</strong> 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.
    </p>
    <p>
      The <strong>Reset</strong> operation could be used to revert any changes you
      have made to the source view and revert back to last saved configuration.
    </p>
    <p>
        Please refer the <a href="configadmin/docs/userguide.html">documentation</a> on managing
        synapse configuration for details.
    </p>
    <p/>  
    <p/>
    <p/>
    <h2 id="Managing1">
      Managing the Integrated Registry
    </h2>
    <p>
      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.
    </p>
    <p>
      You can use these files at the time of defining target sequences and
      target endpoints for the proxy services.
    </p>
    <p/>
    <h4><a id="Manage"></a>
      Manage Registry Entry
    </h4>
    <p>Please refer the <a href="resources/docs/userguide.html">documentation</a> on managing
       the embedded registry for details.</p>
    <p/>
    <h2 id="Monitoring">
      Monitoring the System
    </h2>
    <p>
      This feature provides runtime information about the ESB on the Administrator
      Console. It displays <a href="statistics/docs/userguide.html">system statistics</a>,
        <a href="mediationstats/docs/userguide.html">mediation statistics</a>,
        <a href="transport/docs/userguide.html">transport statistics</a>, 
        <a href="log-view/docs/userguide.html">system logs</a>,
        <a href="tracer/docs/userguide.html">SOAP tracer</a>,
        <a href="mediation-tracer/docs/userguide.html">mediation tracer</a> and
        <a href="viewflows/docs/userguide.html">Message flows</a>.
    </p>
    <p>
      A detailed guide on monitoring WSO2 ESB can be found
      <a href="monitoring.html" target="_blank">here</a>.
    </p>
    <p/>
    <p/>
    <h2 id="References">
      References
    </h2>
    <p>
      <a href="installation_guide.html">WSO2 ESB Installation Guide</a>
    </p>
    <p>
      <a href="configuration_language.html">ESB Configuration Language</a>
    </p>
    <p/>
  </body>
</html>
