Define a SOAP request based on a WSDL definition

The first example will use a web service provided by StrikeIron, this service is a Text Disguise CAPTCHA-Image service. Provided you register your email you will be allowed to freely test the service. The WSDL is available at http://web.archive.org/web/20170918222402/http://www.textdisguise.com:80/TextDisguise/CaptchaService/CaptchaService.asmx?WSDL

A CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) is a program that can generate images that most humans can see, but current computer programs cannot. Many applications need the security of knowing that the "thing" interacting with them is, in fact, a real live person capable of thinking who is responsible for the interaction. Text Disguise solves this problem by embedding a word into an image, distorted and is then shown to the user. The user has to confirm the value entered into the box to continue.

The Text Disguise CAPTCHA-Image service defines two basic methods called GetNewWord and ValidateImageWord. The first method, GetNewWord, expects no direct arguments. It returns a captcha image identifier and a link to that image. The image can be displayed and the user prompted to enter the text he or she sees in the image.

The second method, ValidateImageWord, expects two arguments, the text entered by the user and the image identifier. The method returns true if the text is consistent with the image identifier and false otherwise.

The HTTP request containing a call to the GetNewWord method looks like the following:

POST http://ws.strikeiron.com/textdisguise/CaptchaService

Content-Type: text/xml; charset=utf-8

SOAPAction: "http://www.textdisguise.com/TextDisguise/CaptchaService/GetNewWord"

User-Agent: Jakarta Commons-HttpClient/3.0

Host: ws.strikeiron.com

Content-Length: 723

<?xml version="1.0" encoding="UTF-8"?>

<soapenv:Envelope

  xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

  xmlns:xsd="http://www.w3.org/2001/XMLSchema"

  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <soapenv:Header>

    <ns1:LicenseInfo

        xmlns:ns1="http://ws.strikeiron.com"

        soapenv:actor="" soapenv:mustUnderstand="0">

      <ns1:UnregisteredUser>

        <ns1:EmailAddress>john.doe@dot.com</ns1:EmailAddress>

      </ns1:UnregisteredUser>

      <ns1:RegisteredUser>

        <ns1:UserID/>

        <ns1:Password/>

      </ns1:RegisteredUser>

    </ns1:LicenseInfo>

  </soapenv:Header>

  <soapenv:Body>

    <GetNewWord

        xmlns="http://www.textdisguise.com/TextDisguise/CaptchaService/">

      <GetNewWord/>

    </GetNewWord>

  </soapenv:Body>

</soapenv:Envelope>

Several points are worth noticing:

The HTTP request header defines the end point of the method, the address where the service resides, in the example this is http://ws.strikeiron.com/textdisguise/CaptchaService.
The HTTP request header contains a SOAPAction item.
The HTTP request defines a text/xml content type.
The SOAP header, soapenv:Header element, expects an nsl:unregisteredUser element that must contain your email address.
The SOAP body, soapenv:Body element only contains a reference to the invoked method GetNewWord and has no parameters.

The previous points are noteworthy because most of these elements are generated by NeoLoad and based on the WSDL definition, but as detailed in the following section, NeoLoad user interface will let you customize and configure all of them.

The process is composed of the following steps:

Creating and defining the SOAP request based on WSDL definition
Configuring the request (parameters)
Testing the request

To define a SOAP request based on a WSDL definition

Create a SOAP Request:
- Select the Design section.
- Create a new User Path: Right-click the User Path node and select New User Path. Enter "UserPath", then click OK.
- Add a new SOAP request: Right-click the Actions Container of the User Path just created and select Insert as child, then SOAP request.
- Create the request from a WSDL definition: Check the Generate request using a WSDL file option and enter the URL of that file. In the example the URL is:
  http://www.textdisguise.com/TextDisguise/CaptchaService/CaptchaService.asmx?WSDL
  NeoLoad analyzes the WSDL and extracts the methods that can be called. Click Next.
- Select the method to call: Based on the WSDL definition, NeoLoad lists the methods that you can choose from. Here, you will select the CaptchaServiceSoap.GetNewWord method. Click Next.
- Define a request name: NeoLoad provides a default request name which it usually derives from the method name defined in the WSDL. Most of the time you will not need to change this name. You might want to change it if you use this call several times with different parameter and configuration values. Click Next.
- Define the service end point: This step lets you define the address for invoking the specified service. The WSDL includes this URL and most of the time you will not need to change this address. You might want to change the endpoint to switch from a test environment to a production one. Click Finish.
- Check the main configuration elements:
  - At this point, the SOAP request is added to the User Path.
  - NeoLoad right panel displays the main configuration elements of the SOAP request. This includes the end point URL which is defined by both the Server and Path elements. These elements, as mentioned earlier, have been extracted from the WSDL but can be changed to custom values. As with HTTP requests, the Path element can been defined using NeoLoad variables.
  - The WSDL element can equally be changed or reloaded. Reloading is particularly useful when the SOAP request and it is associated WSDL are out of sync.
  - Reloading WSDL will re-initialize all previous configuration elements. All previously defined parameters will be lost.
- Check the HTTP headers:
  - Most SOAP requests require at least two HTTP header elements when SOAP is tunneled through HTTP. Always make sure that these elements are correctly set. They are available in the Advanced parameters dialog box and are accessed by selecting the Advanced button.
  - In the example these elements are ContentType and SOAPAction. If your web service Framework requires additional HTTP header elements you can set them in the Advanced parameters dialog box.
Configure the SOAP request:
- Before actually testing the SOAP request, additional elements including parameter values and encoding types must be configured. Select the Edit Call Parameters button to access the SOAP configuration dialog box.
- Define the main parameters of the SOAP body:
  - The Parameters tab makes it possible for you to define the structure of the SOAP body. The tree structure in the left most panel of the SOAP Parameters dialog box displays the structure and content of the SOAP body.
  - As mentioned earlier, the GetNewWord method expects no parameters or an empty so the tree only has one root element called GetNewWord (an empty element as defined in the WSDL). Had there been several elements or several possible elements, NeoLoad would have displayed them in the tree. In the example no further configuration for the body is necessary.
- Define the SOAP header:
  - Select the Headers tab to define and configure elements related to the SOAP header. The SOAP header elements are presented in exactly the same way as the SOAP body elements are. The left most panel contains an XML tree displaying the structure and contents of the header of the SOAP envelope. Adding and removing elements is achieved using the + (plus) and - (minus) buttons. Moving elements around is achieved using the up and down buttons
  - The structure contains either Container elements, such as UnregisteredUser in this case, or leaf elements such as EmailAddress. Container elements are meant to contain other elements. Right clicking on them will pop up a menu from which you can choose to move the selected element or add and remove child elements. NeoLoad will only suggest child elements that are consistent with the WSDL definition.
  - Leaf elements on the other hand cannot contain other elements but have an associated value. In the example you must enter a valid email address for the EmailAddress element.
  - For both Container and leaf elements, you can define attribute names and attribute values. Again attributes must be consistent with WSDL definition. Encoding allows special characters such as >, <, or &'to be encoded.
- Configure advanced settings: The Advanced Settings panel makes it possible for you to configure the binding styles of the SOAP request and the format of attachments. This information has been extracted from the WSDL and you should definitely be familiar with the types of bindings if you decide to change this setting.
- View XML: The last tab of the SOAP Parameters dialog box displays the actual XML content that will be sent. NeoLoad generates its content on the fly using the XML elements and attributes you have defined. Right clicking on the XML and selecting the Format as Pretty XML item will display a neatly indented XML. You can search the generated XML for a particular expression by right clicking on the XML and selecting the Search item (or using the CTRL + F shortcut keys).

Test the SOAP request:

By creating a temporary User Path, NeoLoad provides an easy and quick method to check your SOAP request. Select the Check button to open the Check User Path dialog box.
Start checking: If you have already tested User Paths using NeoLoad you will be familiar with the following dialog box. By selecting the Start checking button, NeoLoad will generate the SOAP request and send it to the specified end point. NeoLoad displays the associated response code and the number of failed assertions for the sent request. When the line associated to the request is selected the dialog box displays further details in the lower part of the dialog box. You can choose to display the SOAP request that was sent or the XML response. You can search the SOAP request or the XML response for a particular expression by right clicking on the XML and selecting the Search item (or using the CTRL + F shortcut keys). You can neatly format SOAP request or the XML response by right clicking on the XML and selecting the Format as pretty XML item.

If you are following the example and testing it, the first time you will send the request the response will look like the following (the HTTP header has been omitted):

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope

     xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

     xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <soap:Header/>

  <soap:Body>

    <soap:Fault>

      <faultcode>soap:Client</faultcode>

      <faultstring>

        Thank you for your attempt to try this Web service. Before the

        free trial can occur,

        you must first validate your email address.

        Simply click on the link in the email that was just sent to you,

        and you will then be able to invoke every Web service

        within the StrikeIron Web Services Marketplace, including this one.

      </faultstring>

      <faultactor/>

    </soap:Fault>

  </soap:Body>

</soap:Envelope>

As indicated in the faultstring element, all you need to do to use the service a limited amount of times is to validate the email address you sent by following the link that StrikeIron has sent to you. Once your address is validated invoking the service should get you a response such as the one that follows (the HTML header has been omitted):

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope

    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"

    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <Header xmlns="http://schemas.xmlsoap.org/soap/envelope/">

    <SubscriptionInfo xmlns="http://ws.strikeiron.com">

      <LicenseStatusCode>1</LicenseStatusCode>

      <LicenseStatus>Valid key</LicenseStatus>

      <LicenseActionCode>0</LicenseActionCode>

      <LicenseAction>Decremented hit count</LicenseAction>

      <RemainingHits>4</RemainingHits>

      <Amount>0</Amount>

    </SubscriptionInfo>

  </Header>

  <soap:Body>

    <GetNewWordResponse

        xmlns="http://www.textdisguise.com/TextDisguise/CaptchaService/">

      <GetNewWordResult>

        <CaptchaImageGuid>

          82e16912-14c1-4253-bbcb-699585e3ba63

        </CaptchaImageGuid>

        <Url>

          http://www.textdisguise.com/TextDisguise/CaptchaService/

          CaptchaImage.aspx?

          guid=82e16912-14c1-4253-bbcb-699585e3ba63

        </Url>

      </GetNewWordResult>

    </GetNewWordResponse>

  </soap:Body>

</soap:Envelope>

From this point on you can use the link defined by the URL element in an HTML page. As detailed in the following section you can then use the ValidateImageWord method and the CaptchaImageGuid to validate a text entered by the user.