SOAP Monitor

The SOAP monitor checks the availability and response time of the SOAP interface (SOAP 1.0 and 1.1). It can also monitor the validity of SOAP inputs (requests) and SOAP outputs (responses).

The following table lists the SOAP monitor files.

Guidelines for configuring the SOAP monitor

The SOAP monitor tests the operation of a SOAP service by sending the target SOAP interface a request that contains a set of inputs, and then receiving and analyzing the outputs that are contained in the response that is received from the interface. When a request is sent to the SOAP interface, the request can either succeed or fail. A request succeeds if a response is received and the values in the response message match the specified output values. A request fails if no response is received or a response is received but the values in its message do not match the output values.

The SOAP inputs and outputs that are contained in requests and responses depend on the functions of the SOAP service under test, when you design a test for a SOAP service, must specify inputs and outputs appropriate to that service. The inputs consist of the names of the data to be sent and their assigned input values. The outputs consist of the names of the data to be received and their expected output values. These data names are sourced from a local Web Service Description Language (WSDL) file, which you specify when you configure the SOAP monitor. The input and output data names must match the names and data types in the WSDL file. The data names must also be in the same order as in the WSDL file. If the names do not match, or the order is incorrect, an error message is generated when the monitor tries to poll the SOAP interface.

The format of inputs is:

dataname:datatype=assigned_value, dataname:datatype=assigned_value, ...

The format of outputs is:

dataname:datatype=expected_value, dataname:datatype=expected_value, ...

SOAP data types

The SOAP monitor supports simple, array, and user-defined data types. Simple data types include Integer, String, and Boolean. Arrays might contain simple data types and other array and user-defined data types.

Table 2. Simple data types

Simple data types
anyURI	float	language	Qname
boolean	gDay	long	short
byte	gMonth	Name	string
date	gMonthDay	NCName	time
dateTime	gYear	negativeInteger	token
decimal	gYearMonth	NMTOKEN	unsignedByte
double	ID	NMTOKENS	unsignedInt
duration	IDREFS	nonNegativeInteger	unsignedLong
ENTITIES	int	nonPostiveInteger	unsignedShort
ENTITY	integer	normalizedString

SOAP authentication

If the SOAP interface that you want to monitor requires basic HTTP authentication, specify credentials for accessing the interface in the SOAP profile element when using Internet Service Monitoring Configuration tool.

To set the required SOAP authentication parameters:

1. In the Internet Service Monitoring Configuration tool, select the profile element for which you want to add authentication information.
2. On the Advanced tab, click in the Value field for the username parameter and enter the required value.
3. Click in the Value field for the password parameter and enter the required value. The password is encrypted.
4. Click OK.

If authentication is no longer required, delete the values for the username and password parameters.

Properties

The properties options specific to the SOAP monitor are described in the following table.

Table 3. SOAP monitor properties options

Property name	Property parameter	Description	Default
SoapParser	string	XML parsing library.	$ISHOME/platform/$ARCH/bin/AxisXMLParserXerces.dll
SoapTransport	string	SOAP transport library.	$ISHOME/platform/$ARCH/bin/HTTPTransport.dll
SoapChannel	string	SOAP channel library	$ISHOME/platform/$ARCH/bin/HTTPChannel.dll
SoapSecureChannel	string	SOAP secure channel library.	$ISHOME/platform/$ARCH/bin/HTTPSSLChannel.dll
SoapClientLog	string	The name of the extra SOAP client log file.	$ISHOME/log/SoapClient.log

Cipher suites

The SSLCipherSuite property specifies the cipher suite that is used by the SOAP monitor.

For more information, see SSL setting in Internet Service Monitoring.

Configuring the SOAP monitor services tests

Use the SOAP monitor configuration parameters to define service tests.

Table 4. SOAP monitor configuration 

Element	Description
wsdl	The path to a local copy of the WSDL file.
operation	The name of the SOAP operation.
operationnamespace	The namespace of the SOAP operation.
location	The URL of the SOAP service to be monitored.
description	A text field for providing descriptive information on the element.
timeout	The time, in seconds, to wait for the SOAP service to respond. Default: 10
poll	The time, in seconds, between each poll. Default: 300
failureretests	The number of times to retest before failure is indicated. Default: 0
retestinterval	The time, in seconds, to wait between each failure retest. Default: 10
Soap parameters
inputs	Provides access to the name, type, and value fields, including attributes, for SOAP inputs. Use simple, complex, or array soap parameters. For example: Simple: symbol:string="IBM" Complex: outer:{item1:string,item2:string}(aaa:string='bbb') ={item1(attr:string='ccc')='', item2(attr:string='ddd',attr2:string='eee')='fff'} In this example the attributes in parentheses, marked in bold, are optional. Array: input:int[]=[1,2,3,4]
outputs	Provides access to the name, type, and value fields, including attributes, for SOAP outputs. Use simple, complex, or array soap parameters. For more information about syntax, see the examples for SOAP parameter inputs.

Service level classification

Service level classifications define the rules for determining the level of service that is provided by the SOAP interface.

Available service level classification options for the SOAP monitor are:

totalTime
message

In service level classifications:

• Specify more service level classifications by manually entering the name of the monitor element. The name must match the name that is shown for the element in the Monitor elements section.
• message can be any message in the $message element to IBM® Application Performance Management server if used in any widget. For a list of possible values, see Status messages.

Monitor elements

In addition to the test results common to all elements, the SOAP monitor generates a set of test results that contain data specific to SOAP service tests.

The following table lists the additional elements for the SOAP monitor.

Table 5. SOAP monitor elements 

Element	Description
(Location)	The URL of the SOAP service that is monitored.
(Operation)	The name of the SOAP service that is monitored.
$outputMatch	Success if returned value matches the output value, else Failure.
$responseValueName	The value name received in the SOAP response.
$soapname	The container name in the SOAP response. Only applicable to array and user-defined complex data types.
$soaptype	The container type in the SOAP response. Only applicable to array and user-defined complex data types.
(WSDL)	The path to a local copy of the WSDL file.

Status messages

The SOAP monitor provides status messages in the ResultMessage attribute when using IBM Application Performance Management. These messages indicate the result of the test.

The messages are either Success if the returned values match the output values or an error message. The error message contains a description of the error.

Example

Monitor the availability of the SOAP interface at 5-minute intervals. If the SOAP interface is unavailable, repeat the test at most two times, with 5 seconds between each repeated test. Send a request that adds 1 + 2 and check that the response contains the value of 3.

Create a SOAP profile element and set the fields that are shown in the following table.

Table 6. SOAP profile element example

Configuration field	Value
wsdl	c:\%ISMHOME%\etc\SOAP.wsdl
operation	add
operationnamespace	http://localhost/SOAP/Calculator
location	http://serverA/SOAP/Calculator
description	basic Calculator SOAP monitor
Active	Selected
timeout	30
poll	300
failureretests	2
retestinterval	5
inputs	[in0=1,in1=2]
outputs	[addReturn=3]