[Download]
| [Documentation Index] | [Release Note]
WSO2 Web Services Application Server (WSO2 WSAS), v2.1-RC4-
Administrator's Guide
This document provides information and instructions on the functionality
of the Management Console of WSO2 WSAS .
Your feedback on WSO2 WSAS is most appreciated. Please send them to our mailing lists.
Content
Introduction
WSO2 WSAS is a lightweight, high performant and integrated Web services
middleware platform. Learn more about
WSO2 WSAS!
WSO2 WSAS Management Console is your one stop shop to administer the WSO2
Web Services Application Server. You can administer/configure your
modules/services as well as monitor the system through this interface.
WSO2 WSAS Management Console runs on
AJAX (Asynchronous
Javascript and XML) and SOAP, making it a fast administration tool. All the
functionalities are provided by a set of Web services exposed by the WSO2
WSAS.
Before going through the functionality, we recommend that you read the
Web Browser Specific Settings section to ensure
that you have access to the full list of features WSO2 WSAS AJAX Management
console offers through your Web browser.
The functionality of the Management Console is described in detail
below.
Signing In
Once WSO2 WSAS, v2.1-RC4 has been successfully installed (see
Installation Guide for installation
details), start the WSO2 WSAS server. Then, launch a Web browser instance and
point it to the URL
https://localhost:9443/ (when running in
Stand-alone mode) or
https://localhost:9443/wso2wsas/ (when
deployed inside a Servlet container) if you are using the default settings.
This will take you to the "Sign In" page of the WSO2 WSAS Management Console
as shown below.
Note: WSO2 WSAS has two transport listeners: HTTP and
HTTPS. By default, the HTTP listener opens on port 9762, while the HTTPS
listener opens on port 9443. The administrator functionality is exposed only
via the HTTPS port.
You can now read all the WSO2 WSAS
documents by pointing
your Web browser to
https://localhost:9443/docs
(Stand-alone) or
https://localhost:9443/wso2wsas/docs
(Servlet) if you are using the default settings.
Figure: Sign-In Page
The default username and password to sign into WSO2 WSAS Management
Console:
User name : admin
Password : admin
To solve any problems with signing in, click
"Sign-in Help"
The Sign In page contains links to the
"FAQ" and the
"About WSO2 WSAS" page which gives an introduction about WSO2 WSAS and WSO2
Inc.
Navigation Bar
The following links are available on the navigation bar
Home
The Home Page of the Management Console will contain the following useful
system and service information on WSO2 WSAS.
- System Summary
- Server Name - The name of the server
- Server Version - The version of the above named server
- Server Start Time- The time the server was started/restarted
- System Up Time - The time span for which the server has been
running
- Memory Allocated - Total JVM memory allocated for the server
- Memory Usage - Total JVM memory used by the server
- Service Summary
- Total Request Count - Lists the number of requests since the server
started
- Total Response Count - Lists the number of responses since the
server started
- Total Fault Count - Lists the number of faults that occurred since
the server started
- Active Services - Lists how many services are deployed and running
on the server
Figure: WSO2 WSAS HOME
Manage Services
Figure: Services and Service Group Management
As shown above, this page lists the available services or those deployed
in each service group in the system, along with links to view the WSDL1.1,
Schema, Policy and Certificate (containing the public key if the service has
been signed using a private key) of each service.
This page also carries a link that displays
RSS and
Atom feeds.
Figure: WSDL 1.1 of Service echo
Remove Service Group:
A service group can be removed using the 'Remove' action
icon listed for each service group, in which case all the services in that
particular service archive will be removed from the system.
Deploying Services:
Uploading a New Service (.aar, .jar or .zip)
The following new services can be uploaded and managed through this
console.
- Service Artifact
- POJO Artifact
- Spring Service
- Data Service
- Axis1 Service
- EJB Service
Upload a Service Artifact (.aar,.jar,.zip,.dbs)
If the
service archive of the relevant service is an
.aar, you can deploy the service by simply selecting the service
archive by clicking 'Browse', and then uploading the service by clicking
'Upload'. For example, Axis2 packages the services as .aar files. Therefore,
you can simply deploy an Axis2 service by uploading the relevant .aar
file.
Figure: Uploading an .aar file.
Where the
service archive of the relevant service is a .jar or
.zip file, then the deployment requires a few more steps. In this
case, you must select the service archive by clicking 'Browse', and then
upload the service by clicking 'Upload'. Then, a page containing the classes
of the archive will appear as shown below. On this page, select the relevant
classes of the Web services you wish to deploy by selecting the corresponding
check boxes. Once you have selected all the classes, click 'Generate' to
deploy the relevant services. This process is called
Dynamic Service
Generation.
If the artifact is of type .dbs, i.e. a data service, please refer to
Data Service Guide for
detailed instructions.
Figure: Dynamic Service Generation-Uploading .jar or .zip
File
Upload a New POJO Service (.jar)
Likewise, you can also deploy a POJO services by browsing for and
uploading the relevant .jar files. Please note that the classes and methods
in the .jar have to be @webService & @WebMethod annotated, respectively.
You can also browse for and add other .jar resources that are required for
your annotated .jar's proper execution.
Upload a New Spring Service (.xml and .jar)
Likewise, you can also deploy Spring services by browsing for and
uploading the relevant .xml and .jar files. Deploying Spring services follows
the
Dynamic Service Generation procedure as explained
above.
Figure: Uploading a Spring service
After you specify the .xml and .jar files and click
Upload, the following page appears. Here you can select the
Spring beans you want to expose and click
Generate.
Figure: Dynamic Service Generation for Spring Service-Uploading
.xml or .jar File
If the services were successfully deployed, then a message will appear
saying so. The service that you deployed will now be listed on the main page
of
'Manage Services' (as shown in Figure: Services
and Service Group Management).
Please refer to the
Data Services guide for
detailed instructions on how to host data services on WSAS.
Deploy Axis1 Services (.wsdd files)
WSAS has the built-in capability to support your legacy Axis1 services,
and thus ease migrating to the power and flexiblity of Axis2 without the need
to completely change your existing code. This section describes this feature
and how to use it.
Usage
In order to use your Axis1 services, you'll first need to make sure that
all the service and data classes referenced by your WSDD file (typically
called server-config.wsdd) are available to the WSAS Axis1 deployer. In order
to do this, you must upload the appropriate jars and classes.
Use the resources box to provide the paths for any resource .jars that
might be needed, and the Descriptor field to provide the .wsdd file path.
You may also manually put the jars containing your classes into
WSO2WSAS_HOME/repository/services/axis1services/lib, and they will then be
accessible to the Axis2 engine.
Now you're ready to upload your WSDD file, which will actually deploy the
Axis1 services. Browse for the .wsdd file and click
Upload.
Figure: Uploading a .wsdd file.
Once your WSDD file is deployed, all the Axis1 services inside it will
automatically be usable as Axis2 services, all in a single ServiceGroup.
Axis1 RPC Services
When you look at your Axis1 services in the admin console, you'll notice
that certain services do not look as you might expect. Axis2 does not
natively support RPC/encoded services, and many Axis1 services are deployed
this way. When you look at an RPC service in the admin console, you'll only
see a single operation called "invokeAxis1Service". Your service will
function perfectly normally, since the "invokeAxis1Service" operation is
actually a proxy "passthrough" operation which hands all incoming messages to
your Axis1 service. However, you won't be able to engage Modules on a
per-operation basis for these types of services - global and service-based
Modules will work fine.
EJB Service Provider
Please refer to the
EJB Service Provider Guide
for instructions on how to expose an EJB as a web service.
RSS Feed:
RSS feed gives the subscriber updates about any status changes in the
services in WSO2 WSAS. These include activation, de-activation, removal, etc.
of the services. The RSS standard used is 2.0.
Figure: RSS Feed Page
Atom Feed:
Atom feed gives the subscriber updates about any status changes in the
services in WSO2 WSAS. These include activation, de-activation, removal, etc.
of the services. The Atom standard used is 2.0.
Figure:Atom Feed Page
Deleting Faulty Services:
If a
faulty service is deployed, it will be displayed on
the Available Services page as
[n] faulty
service(s):
Clicking on the faulty service link will open the page as shown below, on
which the details of the faulty services will be listed. By using the 'Delete
Faulty Service' icon on this page, you will be able to delete the deployed
faulty service.
Figure: Deleting Faulty Services
Service Group Management:
Clicking on the Service Group on the main page of "
Manage Services" (as shown in Figure:Services and
Service Group Management), will open a page on which you can:
- Manage Service Group Parameters: Users can add, update or delete parameters from the admin console. Parameters should be given a name and a value, which consist of ASCII values. In addition to this, value can have a well formatted XML fragment.
- Manage Module Engagements: Lists the modules engaged
at the service group level and on a global level. You can also engage or
disengage modules to the specific service group.
- Create Service Archive: This feature will provide the user to create an Axis2 archive out of all the configurations available to a given service group. Thus, before shipping the service to a production environment, user can test whether all related functions such as parameters, module engagement, polices etc are available or its validity so on. Though this will give tremendous development time feature, it has its limitations. Currently this feature could archive a created or generated .AAR. WSAS distribution comes with data services, pojo services, and Axis1 services support. All these domains do not have archives. They would simply be a file with XML formatted description. Thus, if such a service is tried to archive, WSAS would not allow it. It should be noted that an archive can be created only for a service group, not to an individual service. Service group is mapped to a physical .AAR. Thus, it's logical to create an archive only to a service group instead.
- MTOM Configuration: MTOM is allowed to configure in three ways, True, False and Optional. If one these values are changed, this will cause all underline services and operations to change its way of corresponding to MTOM
Figure: Service Group Management-Engage Module
Service Management:
Clicking on the service of a specific service group on the main page of
"
Manage Services" (as shown in Figure:Services and
Service Group Management), will open a page that contains certain
service specific information, and also allows you to
manage the services.
Figure: Service Management Page
Service
information consists of:
- Service name and description
- Service status - It will display whether the service is active or
inactive. You also have the option of changing the service status using
the 'Activate'/ 'Inactivate' button.
- Request count - The number of times the service has been called
- Response count -The number of SOAP message responses
- Fault count - The number of times a fault has been encountered
- Max Response Time
- Min Response Time
- Avg Response Time
- End Point References - All the EPRs of the service will be listed here.
The client can use any URL of its choice.
The
service management options that are available are as
follows:
- Manage Service Operations - This opens the page that
lists the published operations of the service, with the
options of editing operation specific parameters, and viewing engaged
modules and Axis2 handlers.

Figure: Published Operations Page
Click on a specific operation link to open the page that displays the
operations statistics and operation
parameters.

Figure: Operation Statistics and Parameters
Click on the 'Edit operation specific parameter' icon
of a relevant service on the 'Published Operations Page". This will open
a page with the operation's editable (declared) parameters. You can
add/update/delete the parameters on this page. When the operation does
not have editable parameters, the message "No editable parameters
present" will be displayed.
To add a new parameter, click 'Add'. You will be prompted for a
parameter name and value. To change a parameter value, change the
parameter value in the text box and click 'Update'.

Figure: Edit Operation Parameter
The 'View Engaged Modules' icon for each operation
shown in "Figure: Published Operations Page" opens a page with,
- a list of engaged modules at operation level with the option of
disengaging the module at operation level by using the 'Disengage'
icon.
- a list containing modules that can be engaged. Select a module from
the list and click 'Engage' to engage the module at operation
level.
- a list of modules engaged at service level.
- a list of globally engaged modules.

Figure: Engaged Operation Level Modules
The "View Axis2 Handler" icon on "Figure: Published
Operations Page" opens a page that displays the flow of the Apache Axis2
handlers of this particular operation of the service.

Figure: View Axis2 Handler
- Manage Module Engagements- Here, the modules engaged
at service level, service group level and global level are listed. You
have the option of engaging/disengaging the modules on a service level
from this page. Modules can be selected from a list and engaged at
service level by clicking 'Engage'. By using the "Disengage" icon of the
relevant module, you can easily disengage a service level module.

Figure: Manage Service Level Module Engagements
- Manage Transports - Here you can add or remove
transport protocols.

Figure: Service Level Transport Configuration
- Manage Security Configuration- The available security
configuration scenarios are listed here. Click the corresponding radio
button to select the scenario you want, and then click Continue. This
will activate the desired security configuration scenario for the
service.

Figure: Service Level Security Configurations
- Edit Service Parameters- This link opens a page with
editable (declared) parameters and non-editable parameters. Declared
parameters can be edited and updated by using the 'Update' button on this
page.

Figure: Edit Service Parameters
- Edit Service Policies - This link opens a page on
which you can edit the policy of the Web service. You can save the
changes made to the policy by clicking 'Update'. If there are policies
available for the Web service, you will see the following page.

Figure: Edit Service Policies
- Generate Client - This link opens a page where you can
generate stubs for the service. Select the relevant values for the
databinding parameters - Package name, Invocation style, Generate test
cases, Unpack classes, and Databinding method. Then click 'Generate'.

Figure: Generate Service Client
- Try it! - This feature allows you to generate a SOAP
1.2 XDHTML client, which has the ability to invoke the actual service.
This will cover most of the popular spaces. It still has room for
improvements.

Figure: Try Service - Operations Available
- Once the XHTML client has been generated, the user can work on a page
as follows. It has two sections, the upper section handles the requests
and the lower section displays the response. Once the user clicks "Try",
the script executes. The "Table Reset" button resets the request table.

Figure: Try Service Operations
- Application GUI- If a Web service invokes a Web based
Application GUI, then this link will point your browser to run the Web
based client application.
Figure: Application GUI
Dynamic Code Generation
Dynamic code generation allows users to generate stubs for the given service if and only if the give service contains a WSDL 1.1
or WSDL 2.0. Dynamic codegen allows to generate Java based stubs using ADB, XMLBeans and OMElements. Each methods has
its own pros and cons and different configurations. ADB has chosen as the default invocation style. Thus, user has
the ability to select unwrapping option. If other invocation styles have selected, unwrapping will not be available.
In addition to this, generated code will be supplied with the source. User can choose either WSDL 1.1 or WSDL 2.0 to generate code from.
Figure: Code Generation
Manage Modules
On this page, you can view all the modules available for engagement in the
system. It will give the name, version and description of the modules. Each
module can be removed using the "Remove module" icon and can be globally
engaged/disengaged through the "Globally engage/disengage" icon.
Once a module is globally engaged, it will be listed under the "Globally
Engaged Modules" list.
When you remove a module, that particular module will be completely
removed from the system. That is, the module handlers will be removed from
the handler chain and the module .mar file will be deleted. However, if you
disable a module, then the module will still be in the system while the
handlers from that module will be removed from the handler chain.
To upload a new module, use the 'Browse' button to browse for the .mar
file (module archive), and then click 'Upload'.. The uploaded module will be
added to the topmost list of the available modules with the options "Engage
globally" or 'Remove module'.

Figure: Globally Engage Modules
When you click on the module name, it takes you to a page where
module configuration is possible. Module configuration is
done through parameter configuration and
policy configuration. The page also lists
module information such as the module ID, version,
description and whether the module is globally engaged.

Figure: Module Information and Configuration
When the Configure Parameters link is clicked, the page
that opens contains editable parameters. You can add or update the parameters
using the 'Add' or 'Update' buttons.

Figure: Module Parameter Configuration
In case there are no editable parameters, a message will appear on the
page informing you that there are no editable parameters found. You will have
the option of adding a new parameter using the 'Add' button.

Figure: Module Parameter Configuration- No Parameters
Found
Similarly, when the 'Configure Policies' link in "Figure:
Module Information and Configuration" is clicked, the page containing the
policies will be opened (as displayed below). You can edit in the text area
itself and update any changes by clicking 'Update'. If there are no policies
for the module, then the page will read as "No module policies found."

Figure: Module Policy Configuration
Sandesha2 Information
If you select the Sandesha2 module and click on "Show Sandesha2 Information", you will be taken to this page.

If there are any incoming or outgoing sequences available for Sandesha2, details of such will be displayed here.
Details such as Sequence,internal Sequence ID,Secure,Status will be shown here if available. i.e. Sandesha2 should have been
engaged at some level (operation, service, or globally) for sequences to be visible. Otherwise, the page above will be shown.
Manage Security
This page lists areas of security management. Currently it contains User
and Role management.
- Role Management - Creates new roles and edits
existing roles.
- User Management - Creates new users, assigns roles
to users and edits existing users.
Figure: Security Management Main Page
Role Management:
Clicking on the Role Management link will open a page that consists of a
list of existing role names, with the option of adding new role names. This
is done by entering a new role name and clicking 'Add' . If a role was added
successfully, a message (alert) will appear.
You can also delete a role by using the "Delete Role" icon.

Figure: Role Management
User Management:
The User Management link opens a page with a list
of present users with the option of adding new users to this list. In
order to add a new user, the Username, Password and Confirm password (same as
password) fields need to be filled. Select a user role from the list, and
then click 'Add' . If the user was added successfully, a message (alert) will
appear informing you that the user has been added successfully.
Note that the User Role list contains all the role names listed on the Role Management page from which new roles can be added as
well.

Figure: User Management
The present users list comes with the "User Name", "User
Description, "User Actions", "User Role" and "User Role Actions" columns.
User Actions contain "Edit" and "Delete User" icons.
Clicking the "Edit" icon opens a page on which you can edit the
corresponding user details - change the role name of the user and reset the
password. Once a new user role is selected from the list, click 'Update Role'
to update the changes. If the role has been successfully changed, a message
will appear confirming the change. To reset the password, the new password
and the confirmation of the new password (same as the new password) should be
correctly entered. Then click 'Reset Password'. If the password was reset
successfully, a message will appear.

Figure: User Management- Edit User
Click the "Delete user" icon to delete the corresponding user. The "Delete
Role" icon in the "User Role Actions" column can be used to delete the user
role.
Manage Transports
This page lists the available HTTPS and HTTP transports, their names and
values.

Figure: Transport Management
Manage KeyStores
This page allows Keystore management. It lists the available keystores',
name, type and the actions "Importing
Certificates" and "Delete Keystore", which removes the keystore.
The page also contains instructions to add a keystore. This is a three
step process:
- Upload the keystore file.
- Enter the password for the Private Key 'client'
- Keystore upload complete. Exit Keystore wizard.
Figure:Keystore Management
Click the "
Import Certificate" icon to open the page
displayed below. Here you have the option of importing a certificate by using
"Browse" and "Upload". The previously imported certificates will also be
listed here.

Figure:Import Certificate for Keystore
Manage Logging
This page contains server settings for logging. Logging settings include
Log4J Loggers and Log4J Appenders. Loggers filter the log messages to
Appenders, while Appenders filter the messages for the second time before
writing them to the log files.
Log4J Loggers contain the value's Name, Log Level and Additivity.
TheLog level list contains TRACE, INFO, DEBUG, WARN, ERROR,
FATAL and OFF from which any one can be selected. Once you select a Log
Level, only the messages at that level and below will be logged. For example,
if you select Log Level ERROR, then all ERROR and FATAL messages will be
logged or rather passed on to the Appender. Switching on
Additivity allows to inherit all the Appenders of the parent
Logger.
Log4J Appenders include values for the Appender Name, Log level, known as
Threshold in this case, Log Pattern and Log File.
The Threshold list is the same as the Log Level in
Loggers, in name and action. The Log Pattern allows you to
edit the format or the layout in which the logs are created. You can have a
look at the log4j
PatternLayout page to learn the meanings of the values that are used in
the log pattern. Finally you can change the location of the log file with the
Log File option.
Global Log4J Configuration:
Note that by using the Global Log4J Configuration options, you can set the
Log Level and Log Pattern of Log4J Appenders and Loggers to the same value at
the same time.
Values for the above three settings can be edited/changed and updated by
using the Update button.
Restore Default
If user wants to restore to the default log4j properties, user can achive this using "Restore Defaults" option. To make this effective, once restore defaults has been done, user has to restart the system.

Figure: Logging Management
Restart Server

Figure: Restart Server
Monitor System

Figure: Monitor System
Monitor Statistics
This page shows some statistics related to the WSO2 WSAS instance. These
include Free memory, Request count, Server name, Server start time, System up
time, Active services, Total memory, Average response time, Minimum response
time and the Maximum response time.

Figure: Monitor Statistics
Monitor Logs
The system log can be viewed on this page. Log entries will be categorized
into information messages, warning messages, error messages, fatal error
messages and debug messages.

Figure: Monitor Logs
Monitor Tracer
This tracer shows the SOAP messages, their respective SOAP message
requests and responses when the services are deployed on the server, and the
invoked operations. Make sure that the messages are monitored by turning the
SOAP Tracer on. By default, it is switched off. You can switch it on by
selecting ON in the list.
Warning:Turning this on will have a performance hit,
since all SOAP messages will be always completely built (i.e., deferred
building will not be done) and stored in the database by WSO2 WSAS. Hence
this option should be used with caution.

Figure: Turn ON SOAP Tracer
The tracer will only show the messages of the operations that were invoked
after switching on the SOAP tracing.
By using this SOAP tracer, it is possible to see the SOAP messages with
their time-stamps, service name, operation invoked and the number of requests
to the server. The most recent SOAP messages are listed on the top. When a
particular SOAP message is selected, its Request and the Response can be
viewed in collapsible/expandable text boxes.
Note: This tracer does not apply to operations invoked in the admin
services, as they are filtered out.

Figure: SOAP Tracer- Request/Response Messages
Monitor Flows

Figure: Monitor Flows- Graphical View
Click the "Text View" link on the top right hand corner of the page to
view the textual representation of the In flow, Out flow, In-Out flow, and
Out-Fault flow SOAP messages. By using the "Graphical View" link, you can go
back to the "Monitor Flows- Graphical View".

Figure: Monitor Flows- Textual View
Miscellaneous
Signing Out
Once signed in, to sign out from the system, click on the Sign Out link at
the upper right-hand of any page.
Register
You can register your WSO2 WSAS instance by clicking on this link. By
registering, you will be providing the developers with valuable information
to make WSO2 WSAS a better product. Only information that is shown to you on
the Register Product page will be submitted to the server, and you can change
the information that is extracted from your WSO2 WSAS instance before you
submit them to the server if you wish to do so.

Figure: Registration Page
Web Browser Specific Settings
This section will give you configuration information that is specific to
the Web browser you use to point to the WSO2 WSAS AJAX Management Console.
Internet Explorer 6 :
AJAX engines make use of an XMLHttpRequst object to exchange data
asynchronously with remote servers. In Internet Explorer 6, this object is
implemented with ActiveX rather than native JavaScript, which requires that
ActiveX be enabled to run the WSO2 WSAS Management Console.
Once you have configured your Web browser as above, see the Signing In section on how to access the Management
Console.
Manage Service Security Configuration
A service can be secured using any of 12 available security scenarios.
These configurations are available from in the "Manage Security Configuration"
option in "Service Management".

There are three main categories of security scenarios available
- Basic message level security : WS-Security
Scenario 1 to 8
- Secure Session : WS-SecureConversation
Scenario 9 and 10
- Security based on a token issued by a SecurityTokenService : WS-Trust
Scenario 11 and 12
Timestamp properties (time to live and maximum time skew values) of Apache
Rampart policy can be adjusted using the service policy editor after configuring
the service.
Security Token Service Configuration
A WS-Trust Security Token Service (wso2wsas-sts) is included in the standard set
of services of WSO2 WSAS. If a service is secured with either Scenario 11 or
Scenario 12 mentioned in the "Service Security
Configuration" the client can obtain a token from wso2wsas-sts and use that
token in the request to the secured service.
Service Management page of wso2wsas-sts has an additional option to configure
the STS.

This basically allows the admin to add trusted service endpoint addresses to the
STS. The STS will only issue tokens to those trusted services. One must specify
the alias of the cert of the trusted service along with the service endpoint
address. The service certificate must be available in the wsas main keystore
(wso2wsas.jks) and the aliases of the available certificates are provided for
selection.