SiteScope User's Guide

Web Service Monitor

The Web Service Monitor is used to check Simple Object Access Protocol (SOAP) enabled web services for availability and stability. The Web Service Monitor sends a SOAP based request to the server and checks the response to verify that the service is responding.

The Simple Object Access Protocol (SOAP) is a way for a program running under one operating system to communicate with another program running under the same or different operating system (such as a Win 2000 program talking to a Linux based program) The Simple Object Access Protocol uses the Hypertext Transfer Protocol (HTTP) and Extensible Markup Language (XML) for information exchange with services in a distributed environment.

This monitor uses a Web Services Description Language (WSDL) file to extract technical interface details about a web service and uses information returned to create an actual SOAP request to that web service. That is this monitor emulates a real web service client making a request. The SOAP request can be used to confirm that the web service is serving the expected response data and in a timely manner. The status of the Web Service Monitor is set based on the results of the SOAP request

Usage Guidelines

Why should I use this monitor?

This monitor should be used to ensure the availability of a web service accepting SOAP requests. The Web Service Monitor checks that the service can send a response to the client in certain amount of time and to ensure that the SOAP response is correct based on your selected match specifications.

You can find more information on SOAP on the W3C web site at: http://www.w3.org/TR/SOAP/

Information on WSDL is available from Microsoft® at: http://msdn.microsoft.com/xml/general/wsdl.asp

Support Levels

The following specification features are currently supported:

WSDL 1.2
SOAP 1.1
Simple and Complex Types based on XML Schema 2001
SOAP binding with the HTTP(s) protocol only
SOAP with Attachments is not supported

Be advised that SOAP and WSDL technologies are still undergoing evolution. Consequently there can be instances of WSDL documents that we may not be able to process with complete accuracy. In addition, certain SOAP requests we send may not interoperate effectively with all web service providers due to inherent specification ambiguities. However, it is our full intent and commitment to continually keep our implementations up to date with the latest web service specifications.

Status

The status reading shows the most recent result for the monitor. This status value is displayed in the URL Group table within SiteScope. It is also recorded in the SiteScope log files, e-mail alert messages, and can be transmitted as a pager alert. The possible status values are:

OK
unknown host name
unable to reach server
unable to connect to server
timed out reading
content match error
document moved
unauthorized
forbidden
not found
proxy authentication required
server error
not implemented
server busy

The final status result is either OK, error, or warning based on the threshold established for these conditions.

Completing the Web Service Monitor Form

To display the Web Service Monitor Form, either click the Edit link for an existing Web Service Monitor listed in a monitor table, or click the add a Monitor link on a group's detail page and choose the "Web Service Monitor" link.

Complete the items on the Add Web Service Monitor form as follows. When the required items are complete, click the Add Monitor button.

URL of the WSDL

Enter the URL or the file path of the WSDL file to be used for this monitor. All file paths entered must be relative to ssHome/SiteScope/templates.wsdl/, where ssHome is where SiteScope was installed on your system. In addition, your WSDL files must have an extension of .wsdl.

File:

Optionally you can select a WSDL file from this drop down list. This list reflects the files found by searching on ssHome/SiteScope/templates.wsdl/*.wsdl

Method Name

Select the name of the method to be invoked. During initial setup this will be extracted from the WSDL file.

Pressing on the Get Methods button causes the specified WSDL file to be retrieved and analyzed for method arguments. The ensuing screen will display the argument list and structure, if any, that will need actual input values.

Server URL

Shows the URL of the web service to be monitored. During initial setup this will be extracted from the WSDL file.

Name of arguments

Shows the name and type/structure of the arguments to the method specified above. SiteScope supports both simple (primitive) and complex (user-defined using XML schema) types. Simple type arguments will appear in the form:

parm-name(parm-type) =

where you will need to enter the parameter value to be used in invoking the web service, after the equal sign. Strings with embedded spaces should be enclosed in double quotes. Each parameter must be in a separate line, i.e. do not remove the carriage return at the end of each parameter.

A complex type parameter is displayed as one long string, with needed input fields marked with asterisks (***). An example of a complex type parameter is shown below:

stocksymbol[COMPLEX] =<stocksymbol xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:fw100="urn:ws-stock" xsi:type="fw100:getQuote"> <ticker xsi:type="xsd:string">***</ticker></stocksymbol>

You must replace these occurrences of asterisks with meaningful values of the appropriate type (the needed type will be shown, e.g. "xsd:string" above), otherwise the web service request may fail. Do not add any carriage returns within a complex type parameter.

If the web service method does not take any parameters, the text box should be empty (and left that way).

Update every

Enter how frequently the monitor should try to reach the host. The drop-down list to the right of the text box lets you specify time increments of seconds, minutes, hours, or days. You must specify a time increment of at least 15 seconds or greater.

Title (Optional)

Enter a title for this monitor. This title appears in the Name text box on the monitor table when you open the subject group's detail page. If you don't enter a name, a default name will be created.

Advanced Options

The advanced options give you the ability to customize error and warning thresholds. If you choose not to set them, SiteScope will use pre-set defaults if available. If a default is not available, SiteScope will not be able to utilize the condition.

Disable: Check this box to temporarily disable this monitor and any associated alerts. To enable the monitor again, clear the box.
Match Content: Enter a string of text to check for in the returned page or frameset. If the text is not contained in the page, the monitor will display "no match on content". The search is case sensitive. Remember that HTML tags are part of a text document, so include the HTML tags if they are part of the text you are searching for (for example, "< B> Hello< /B> World"). This works for XML pages as well. You may also perform a Perl regular expression match by enclosing the string in forward slashes, with an "i" after the trailing slash indicating case-insensitive matching. (for example, "/href=Doc\d+\.html/" or "/href=doc\d+\.html/i"). If you want a particular piece of text to be saved and displayed as part of the status, use parentheses in a Perl regular expression. For example /Temperature: (\d+). This would return the temperature as it appears on the page and this could be used when setting an Error if or Warning if threshold
Method Name Space: The XML name space for the method in the SOAP request. During initial setup this value will be extracted from the WSDL file.
Content Type: The SOAP http header content type value. Default is: text/xml; charset=”utf-8”.
SOAP ACTION: The SOAP ACTION url in the header of the SOAP request to the Web Service. During initial setup this will be extracted from the WSDL file.
Request's schema: The request schema. Currently SiteScope only supports SOAP.
HTTP Proxy: Optionally, a proxy server can be used to access the URL. Enter the domain name and port of an HTTP Proxy Server
Authorization User Name: If the URL specified requires a name and password for access, enter the name in this box.
Authorization Password: If the URL specified requires a name and password for access, enter the password in this box.
Proxy Server User Name: If the proxy server requires a name and password to access the URL, enter the name here. Technical note: your proxy server must support Proxy-Authenticate for these options to function.
Proxy Server Password: If the proxy server requires a name and password to access the URL, enter the password here. Technical note Your proxy server must support Proxy-Authenticate for these options to function.
Verify Error: Check this box if you want SiteScope to automatically run this monitor again immediately if it detects an error.
Update Every (on error): This options allows you to set a new monitoring interval for monitors that have registered an error condition. For example, you may want SiteScope to monitor this item every 10 minutes normally, but as often as every 2 minutes if an error has been detected. Note that this increased scheduling will also affect the number of alerts generated by this monitor.
Schedule (Optional): By default, SiteScope's monitors are enabled every day of the week. You may, however, schedule your monitors to run only on certain days or on a fixed schedule. Choose the Edit schedule link to create or edit a monitor schedule. For information about creating schedules, read these instructions.
Monitor Description (Optional): Enter any additional information or details you want to associate with this monitor. The Monitor Description can include HTML tags such as the <BR> <HR>, and <B> tags to control display format and style. The description will appear on the Monitor Detail page.
Report Description (Optional): Enter a description for this monitor that will make it easier to understand what this monitor does. This description will appear in the headings of Management Reports and on the info pop-up for this monitor.
Depends Condition (Optional): If you choose to make the running of this monitor dependent on the status of another monitor, choose the status condition that the other monitor or monitor group should have in order for the current monitor to run normally. The current monitor will be run normally as long as the monitor or group on which it depends reports the condition selected in this option.
List Order (Optional): By default, new monitors are listed last on the Monitor Detail page. You may use this drop-down list to choose a different placement for this monitor.
Error if: This option allows you to customize the conditions under which the Web Service Monitor generates an error status message.
Warning if: This option allows you to customize the conditions under which the Web Service Monitor generates a warning status message.
Good if: This option allows you to customize the conditions under which the Web Service Monitor generates a good status message.