web_service_call
Example: web_service_call | Web Services Functions (SOAP, WEB_SERVICE, Silverlight) |
Calls a web service.
int web_service_call( const char *StepName, [URL,] ExpectedResponse, <List of specifications>, [BEGIN_ARGUMENTS, Arguments, END_ARGUMENTS,] [Send Attachments, ][BEGIN_RESULT, Results, END_RESULT,] [Receive Attachments, ] LAST );
StepName | The name of the step, as it appears in the test tree. Any text can be used. |
ExpectedResponse | The type of response to accept. See Expected Response. |
URL | The URL (Uniform Resource Locator) of the web service to load. |
List of specifications | A comma separated list of the format "Specification=value". For a list, see Specifications. |
BEGIN_ARGUMENTS | A marker that indicates the beginning of the ARGUMENTS section. |
Arguments | ArgumentName=Value. Either the argument name as specified in the WSDL and its assigned value, or one of the User Handler Arguments.
|
END_ARGUMENTS | A marker that indicates the end of the ARGUMENTS section. |
Send Attachments | The attachments to send. For details, see Attachment Specifications. |
BEGIN_RESULT | A marker that indicates the beginning of the RESULT section. |
Results | ResultName=ParamName. The name of result argument or return value as specified in the WSDL, and the name of parameter in which to store the result.
|
END_RESULT | A marker that indicates the end of the RESULT section. |
Receive Attachments | The expected attachments to save when received. For details, see Attachment Specifications. |
LAST | A marker that indicates the end of the arguments list. |
The web_service_call function calls a web service.
This function is generated when you use the Import WSDL wizard in Web Service Vusers. When you import a WSDL document, by default a web_service_call function is generated.
This is a high-level function that lets you modify all the SOAP arguments intuitively. Because editing the arguments is likely to be error-prone, it is recommended that the function be modified in the tree view rather than in the script editor.
By default, the URL end-point is taken from the WSDL file. Use the URL argument to overwrite (or parameterize) the Web Service end-point.
If you import a web service using the .NET toolkit you may need a web_service_set_option call before the web_service_call in these cases.:
- If the SOAP request message includes WS-Addressing and the WS-Addressing is not required, invoke web_service_set_option("ExcludeWseHeaders", true) before the web_service_call.
- If the SOAP response body is in MIME format, invoke web_service_set_option("HandleMIMEResponse", true) before the web_service_call.
- If the response does not match the ExpectedResponse argument because the server adds security tokens, invoke web_service_set_option("DoNotValidateSecurity", true) before the web_service_call.
Return Values
This function returns LR_PASS (0) on success, and LR_FAIL (1) on failure. Note that in many cases, this return value indicates the technical success of the function, and not the result. For example, a function that registers a string to be found in a subsequent step returns LR_PASS to indicate that the registration was successful. This does not indicate that the string was found in the server response.
Parameterization
The URL argument can be parameterized. Most of the values of the specifications can be parameterized. Exceptions are noted in the descriptions below.
The expected response is one of the following:
Value | Effect |
---|---|
"ExpectedResponse=SoapResult" | Accept SOAP output responses and fail on SOAP faults. |
"ExpectedResponse=SoapFault" | Accept SOAP faults and fail on SOAP output responses. |
"ExpectedResponse=AnySoap" | Accept both SOAP output and SOAP fault responses. |
SOAPMethod: the Web Service method to be called, including the service name, port name, and method name. SOAPMethod cannot be parameterized.
The elements are separated by a period. For example:
SOAPMethod=RPCEncodedEchoService|RPCEncodedEchoServiceSoap|EchoStructContainingArray
RPCEncodedEchoService is the service name.
RPCEncodedEchoServiceSoap is the port name.
EchoStructContainingArray is the method name.
SOAPHeader:an optional custom SOAP header in XML format. The header is enclosed in a SoapHeader tag. For example:
"SOAPHeader=<SoapHeader><element1>some text</element1><element2>some text</element2><element3>some text</element3></SoapHeader>"
Service: the name of the service as defined in WSDL.
WSDL: the location of the WSDL document. WSDL and its arguments cannot be parameterized.
Snapshot: the name of the .inf file containing a snapshot of the step. This argument is recorded. Do not add it when entering the step manually. If it is recorded, do not edit it.
ResponseParam: the name of the output parameter in which to store the server response.
RecordedBuffer: a buffer created during recording that contains the message sent. Do not edit this argument or enter it manually.
ClientEmulation: This argument takes either the name of toolkit (DotNet or Axis) or a recorded keyword, which means that the recorded buffer will be replayed. ClientEmulation is optional. If it is present, it overrides the run time settings.
SOAPAction: The HTTP header as specified in the WSDL.
UseWSDLCopy: This optional argument determines whether the global WSDL or the local copy will be read during the test run. If the value is 1, the local copy is used. If the value is 0, the global WSDL is used. The default is to read the global WSDL.
AsyncEvent: The name of the event to be used in a subsequent call to web_service_wait_for_event. If the web_service_call invocation contains a non-empty AsyncEvent argument, the invocation sends the request and test run continues immediately, without waiting for the response. The run continues until the web_service_wait_for_event call. This argument is optional.
WSAAction: the action to be performed on the destination server.
WSAReplyTo: the IP address to which the response is sent using WS-Addressing. The value is generally a literal IP address of the load generator. When "WSAReplyTo=autodetect" is specified, the IP of the load generator will be detected in runtime. Autodetect requires that service can translate the load generator's host name into IP using a DNS. WS-Addressing is supported in .NET and Axis toolkits. This argument is optional.
JMSSendQueueName: the JNDI name of the send queue. It points to a queue name that can be located by a JNDI lookup operation. This value cannot be empty when using JMS transport. If not using JMS transport, do not pass this argument.
JMSReceiveQueueName: the JNDI name of the receive queue when using JMS transport. It points to a queue name that can be located by a JNDI lookup operation. If this value is missing or empty a temporary queue will be used for receiving. If not using JMS transport, do not pass this argument.
UserHandlerFunction: The name of a function defined in the script.
UserHandlerName: The name of the user handler and the DLL for handlers defined externally to the script. If you specify a handler function defined in the script as the UserHandlerFunction, then UserHandlerName is ignored.
UserHandlerArgs: A list of configuration arguments for the handler. Use the handler's GetArguments
method to retrieve the arguments in your handler.
UserHandlerOrder: The order in which the user handler is processed in the request. One of BeforeSecurity, AfterSecurity
, AfterAttachments
or ReplaceTransport
.
For more information about user handlers, see "Customizing Web Service Script Behavior" in the Virtual User Generator Help Center (select the relevant version).