Testing USAS/USPS SOAP Services

As more vendors integrate with the USAS/USPS SOAP services, I've been increasingly asked how to test the SOAP services at an ITC to ensure the service is working and to ensure the "end point" URL being used is the correct one.

The first step is to do a simple connection test to be sure the webapp is running and responding to requests.  An easy way to do this is just point your browser at the context where you think the service is running. 

For example, the SSDT's development instances are installed at:

   http://devel.ssdt.nwoca.org/usassoap/
   http://devel.ssdt.nwoca.org/uspssoap/

If you go to this page (substitue your own domain and context and use HTTPS if appropriate), you should see the services "home page" with links to the "WSDL", documentation, etc.  If you don't get this page, you're either on the wrong URL or the webapp is not running.  If you get this far, then the webapp that contains the SOAP service is running.

However, that doesn't mean the SOAP inside the webapp is working.  The next step is to click on the "Service WSDL" link. The WSDL link will take you to the "end point" URL with "?wsdl" at the end.  If this works, then you should see the WSDL document representing the SOAP interface.   It's not important what this stuff means, the fact that you see it is sufficient to indicate the service is running and ready do deal with requests.

The next step is to see if you can login to the service.  Both USAS and USPS have a "login" operation.  The login operation takes a username and password and, if successful, returns a "sessionId".  Both services allow you to invoke the service using an HTTP GET request so you can test the login via any web browser.

For example, if you type the following into the browser:

http://devel.ssdt.nwoca.org/uspssoap/services/USPSWS?method=login&username=TEST&password=TEST

You'll send a login request to the SSDT's devel server.  The response will contain "%ACME-E-AUTHFAILURE, authentication has failed".  This is a good thing because the error message is coming from the OpenVMS back-end so you're getting a response all the way thru the SOAP service to the RPC service. 

If you substitue your own endpoint URL and a valid username/password, you should get a response like:

<soapenv:Envelope>
  <soapenv:Body>
     <loginResponse>
       <loginReturn>nnnnnnnnnnnnnn</loginReturn>
   </loginResponse>
  </soapenv:Body>
</soapenv:Envelope>

The "nnnnnnn" is the session id created for the connection.

The above test indicates that you were able to successfully login to the SOAP service.  Again, both USAS and USPS support identical "login" operations with the same parameters.  So you can test either service this way.

However, this is not a thorough test. In particular, does not test if the user can select a "district" (a SETUPENV) code to get fully connected or access the data files.  Testing the next step is a little more complicated and beyond what I want to teach you about SOAP today. :)

Advanced Test with soap UI

If you're still having trouble with the SOAP services, or a vendor's developer insists it's your problem, you can use soapUI, to setup a more extensive test.

I've attached two soapUI projects to this posting that do the following for USAS or USPS:

  1. Logs in using credentials provided
  2. Select the district's SETUPENV code
  3. Calls the "getDistrictInfo" operation to ensure the data files are accessible

If you want to use one of these you'll first need to download and install soapUI (free version) from their download page.  Then you an invoke the "testrunner" script to execute one of the projects. Note: The instructions below assume you've put the "soapui/bin" directory on your PATH.  If not, you'll need to specify the full path name to the testrunner.bat file.

Next, download the attached files and place them in a directory (like C:\soaptests).

To execute the tests against the SSDT development server, use:

C:\soaptests\> testrunner.bat USASConnectTest-soapui-project.xml

When executed, the script will prompt you with the following dialog:

Type anything you like here because you're running against the SSDT's development server and click Ok.  You'll see a very verbose set of log messages and the test will fail with "Authentication failure" somewhere in the messages.  This is a good thing because it means soapUI is setup correctly and working.

Next, try it with your own endpoint URL, like this:

c:\soaptests\> testrunner.bat  -e https://your.domain.com/usassoap/services/USASWS USASConnectTest-soapui-project.xml

Be sure to specify https: if you're testing SSL connections. This time, enter a valid username and password on your server. 

Although the log messages are verbose, it should be fairly obvious whether the tests succeeded or failed.  If it fails, you should be able to find a detailed message (often a "SOAP Fault") describing the problem.  If you have trouble deciphering the message, pipe output to a log file and open a USD Ticket for the SSDT.

If the tests succeed, then you can be reasonably certain that your service is working end-to-end and the user can access the district's files.   There are, of course, other things that can go wrong (like a specific file missing or insufficient security identifiers for specific functions), but mostly these tests prove that the service and district config is good.

You're also welcome to open these projects with SOAPUI and see how they work. soapUI is a great tool for learning how SOAP services work and diagnosing problems.   Certainly any software developer who's using SOAP should have soapUI (or something very simlar) available.

Leave a comment below or send email if you have questions.

AttachmentSize
USASConnectTest-soapui-project.xml384.15 KB
USPSConnectTest-soapui-project.xml382.85 KB