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 as a Windows 2000 or Windows 2003 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

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

Web Service Authentication

This monitor supports web service providers that require Basic, Digest or NTLM authentication for invoking the service. A username and password are always required, but for NTLM authentication a Domain Name must also be specified.

There is no authentication support for obtaining the WSDL file. If a WSDL file retrieval requires authentication, first retrieve it using a browser with the appropriate credentials, then copy its display contents into a .wsdl file in SiteScope/templates.wsdl.

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 click 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 <SiteScope install path>/SiteScope/templates.wsdl/, where ssHome is the SiteScope home directory 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 <SiteScope install path>/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. A list of available methods will then be displayed in a drop down box from which you will need to select a method to be invoked when monitoring this web service. The ensuing screen will display the argument list for the selected method and argument structures, 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, that is, 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, for example, "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

Select how often the monitor should try to reach the host. The default interval is to run or update the monitor once every 10 minutes. Use the drop-down list to the right of the text box to specify another update interval in increments of seconds, minutes, hours, or days. The update interval must be 15 seconds or longer.

Title

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 do not enter a name, a default name will be created.

Advanced Options

The Advanced Options section presents a number of ways to customize monitor behavior and display. Use this section to customize error and warning thresholds, disable the monitor, set monitor-to-monitor dependencies, customize display options, and enter other monitor specific settings required for special infrastructure environments. The options for this monitor type are described below. Complete the entries as needed and click the Add or Update button to save the settings.

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. This field is shown only when editing an existing web service. During initial setup this value will be extracted from the WSDL file.
HTTP 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. This field is shown only when editing an existing web service. During initial setup this will be extracted from the WSDL file.
Use .NET SOAP: Web services based on the .NET platform require a slightly different dialect of SOAP. Check this box to configure this monitor to generate a MS-compatible SOAP request.
Request's schema: The request schema. Currently SiteScope only supports SOAP.
NTLM Domain name: If the web service requires NTLM / Challenge Response authentication, a domain name is required as part of your credentials (as well as a user name and password below).
Authorization User Name: If the web service requires a name and password for access (Basic, Digest or NTLM authentication), enter the name in this box.
Authorization Password: If the web service requires a name and password for access (Basic, Digest or NTLM authentication), enter the password in this box.
HTTP Proxy: Optionally, a proxy server can be used to access the web service. Enter the domain name and port of an HTTP Proxy Server including the protocol (e.g. http://www.domain.com:port). If no port is specified, port 80 is assumed.
Proxy Server User Name: If the proxy server requires a name and password to access the web service, 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 web service, 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): You use this option 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: By default, SiteScope 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. Click the Edit schedule link to create or edit a monitor schedule. For more information about working with monitor schedules, see the section on Schedule Preferences for Monitoring.
Monitor Description: 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: Enter an optional description for this monitor that will make it easier to understand what the monitor does. For example, network traffic or main server response time. This description will be displayed on with each bar chart and graph in Management Reports and appended to the tool-tip displayed when you pass the mouse cursor over the status icon for this monitor on the monitor detail page.
Depends Condition: If you choose to make the running of this monitor dependent on the status of another monitor, select 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 on which it depends reports the condition selected in this option.
List Order: 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: Use this option to customize the conditions under which the Web Service Monitor generates an error status message.
Warning if: Use this option to customize the conditions under which the Web Service Monitor generates a warning status message.
Good if: Use this option to customize the conditions under which the Web Service Monitor generates a good status message.