Details

WebserviceTool (successor of taSoapClient) is a generic webservice client with which you can consume HTTP and HTTPS based webservices (SOAP and REST).
It is based on the Eve VM 1.50 and runs on Win32 desktops (with and without Java) and on systems with a Java VM. Webservice requests can be automated in the GUI and from the commandline using BeanShell scripts.

WebserviceTool v5.10

What is WebserviceTool?
Multi language
Entering and organizing data
Encryption
Finding and replacing data
Invoking a request
Invoking a batch of requests
TLS client authentication
Multi-user shared installation support
Automation with BeanShell Scripts
Starting WebserviceTool with commandline options
Debugging

What is WebserviceTool ?

This application (successor of taSoapClient) is a generic webservice client with which you can consume HTTP and HTTPS based webservices.
It is based on the Eve VM 1.50 ( http://www.ewesoft.com). For better performance, the application uses the JavaVM if installed. If you experience slow keyboard or graphic response, set the environment variable J2D_D3D=false before you start WebserviceTool.

The program has following features:

Runs on Win32 Desktops (with or without Java) and on systems with a Java VM.
Supports SOAP and REST webservices.
Multi lingual GUI
Commandline support
Multi-user support from shared, central installation
The GUI to enter the input data for the webservice requests is dynamically created based on the XML request files. The data entry can be supported with specific forms (configurable).
The XML files for SOAP requests can be created from the WSDL
The XML files for REST requests can be created from the OpenApi v3 JSON file
Supports webservices with HTTPS (TLS 1.2), also with SNI (Server Name Indication)
Supports webservices with certificate based TLS client authentication
Supports webservices with Basic Authentication
Supports webservices with UsernameToken Authentication (plain and digest)
Supports webservices with NTLM Authentication
Supports HTTP proxies with Basic Authentication
Supports proxies with HTTPS Tunneling (HTTP CONNECT)
Supports WSHttpBinding
Supports HTTP custom header fields
Supports batch requests
Supports automation with signed BeanShell scripts (in the GUI and from the commandline). In GUI mode, data can be passed to the script from user-defined input forms.
Webservice definition files (*.ws5) are stored encrypted. In the request files, fields can be defined as encrypted.
Webservice definitions can be imported and exported
For REST webservices XML and JSON format are supported. POST parameters can be sent in form-encoded format.
The XML response of the webservice is displayed as tree, user-fiendly text or table. Selections in tree, text and table view can be copied to the clipboard. The table content is in tab-delimited format, so it can be pasted into a spreadsheet application.
The request and the response can be logged to disk (manually or automatically with the Auto-Log option). The log files are stored in the 'Log' subdirectory of the directory that contains the request file.
You can search for a text string in the response.
Content that is referenced (XML multiref) can be de-referenced so that the content is shown at the XML element where it belongs.
Built-in text editor for modifying the request files
Shows saved log files or XML data from the clipboard
For troubleshooting the user can activate the debug mode that logs a lot of information that can help solve the problem.

top

Multi language

The application is delivered in english and german, but is designed to support any number of languages. To translate the application into your language or to change the existing english / german texts, follow the instructions in the 'Custom Language Package' (WebserviceTool-Custom.zip).

top

Entering and organizing webservices

The data in the webservice definition file (*.ws5) is organized in a tree and webservices and / or their requests can be moved along in the tree with the Cut and Paste functions.

Defining proxy settings

At the root node you can define the http proxy settings:

Name: The name of the root node. You can choose any name you like here.
Description: Enter any description you like. It will be displayed at the bottom of the GUI when you select the root node.
Use proxy: Check this box if you want to use the http proxy. This is a global option: The proxy is only used if also 'Use proxy' is checked for the webservice (see below).
Proxy server: The address of the proxy server, e.g. http://proxy.local:9090 or http://192.168.100.1:8080
Proxy user: Your username at the proxy
Proxy password: Your password at the proxy

Adding a new webservice

When adding a new webservice, you'll need to enter following things:

Name: The name of the webservice. You can choose any name you like - it is only used as name of the node in the GUI.
Description: Enter any description you like. It will be displayed at the bottom of the GUI when you select the webservice.
URL: This is the SOAP service endpoint or the REST base URL, e.g. http://www.webservicex.net/country.asmx
max. TLS version: Always choose the highest version available. Only choose a lower version if you get errors during TLS handshake.
SHA1 fingerprint: This character string identifies the HTTPS server by its certificate. If you do not want to verify the server, you can enter DO_NOT_VERIFY here (NOT recommended!).
Use SNI: ServerNameIndication is a TLS extension and should be active for all encrypted connections. Only turn off if you get errors during TLS handshake.
Encoding: Character set used by the webservice
Use REST: Check this option for REST webservices. For SOAP webservices leave this option un-checked.
Use WSHttpBinding: Check this option for SOAP 1.2 webservices that use WSHttpBinding instead of BasicHttpBinding. For REST webservices this option has no effect.
Show attributes as elements: Check this option if you want the XML attributes of a element to be shown as child elements instead. This might be useful for certain REST web services.
Authentication: Choose the authentication type
Username: Your username to access the webservice.
Password: Your password to access the webservice.
HTTP custom header fields: Here you can optionally add new or replace existing HTTP header fields which need to be set on all requests. Enter 1 field per line in the following format: name:value
Use proxy: Check this option, if you want to use the proxy defined at the root node.
Connect timeout: This is the timeout in ms after which the attempt to connect to the server is aborted.
Read timeout:This is the timeout in ms after which the attempt to read data from the server is aborted.
Request directory: This is the directory, where the XML request files are stored. The directory can be an absolute path or relative to the location of the webservice definition file. You can use an environment variable here for better multi-user support.
Private key: The private key in PKCS8 PEM format
Client certificate: The client certificate in PEM format
Supress password in logs: Passwords are replaced with ***
Modification password: Enter a password if you want to protect this entry against unauthorized modification

Adding a new request

When adding a new request for a webservice, you'll need to enter following things:

Name: The name of the request. You can choose any name you like - it is only used as name of the node in the GUI.
Description: Enter any description you like. It will be displayed at the bottom of the GUI when you select the request.
Username: Your username to access the webservice. If this is empty, the username and password defined in the webservice will be used.
Password: Your password to access the webservice.
SOAP action: Enter the SOAP action here (for SOAP webservices).
HTTP command: Choose the HTTP command here (for REST webservices).
HTTP custom header fields: Here you can optionally add new or replace existing HTTP header fields. Enter 1 field per line in the following format: name:value. To delete global header fields, leave the value empty.
Replace href: Check this option if you want to de-reference href-ed content. If you see href="#id1" or the like in the webservice response and you'd expected to see some meaningful data there, you should check this option.
File name: Enter the file name of the request file.
Default element: Defines the element, that will be pre-selected in the tree when the response is shown. The element is defined in Xpath notation.
Example: /doc/pag/lin[2] selects the second lin-element of the first pag-element within the root element doc.
Default view: Default view for showing the response.
Auto-Log: Request and response are automatically logged to disk.
Save request: Updates the request files with the input entered during invoke.
Modification password: Enter a password if you want to protect this entry against unauthorized modification

Creating request files

At the beginning of the request file, you can specify the XML encoding. This encoding is used to read and update the request file but need not be the same encoding that is used to communicate with the webservice. For Windows systems (with native VM or Java VM) we recommend to use following definition: <?xml version="1.0" encoding="ISO-8859-1"?>. For Linux systems we recommend <?xml version="1.0" encoding="UTF-8"?>. If there is no XML encoding defined, ISO-8859-1 (=Windows1252, "ANSI") is being used.

The program can create SOAP XML requests automatically for WSDL files that use the document/literal style. To do this, choose 'Add/update request from WSDL' in the 'Edit' menu. This menu option is only active for the PRO version and when running on a Java VM 1.5 or later. When adding requests for the first time, you need to choose a SOAP binding (later on, the binding cannot be changed anymore because you must not mix requests from different bindings!). Then, you can choose the operations for which you want to create requests. Requests whose name match the name of the operation are updated. XML request files whose filename match the operation name are overwritten from the definition in the WSDL. Non-existing requests are added at the end of the request list and the corresponding XML request files are added in the 'Request directory' specified for the webservice. All leaf elements are automatically marked as input fields (see below for customization).

If the WSDL is not supported by the program, we recommend that you use a SOAP tool like the free soapUI to create the XML request files.

In the request files, you can use variables in the format ${API.globalVars.key}. During the loading of the request, these placeholders are replaced with the content of the corresponding variable. The API.globalVars variables must be set through a script (see API documentation).
Example:
<accountId>${API.globalVars.accId}</accountId>
If, in a script, you use API.globalVars.put("accId","1234"); to set the variable API.globalVars.accId, then the above XML element would be read as follows:
<accountId>1234</accountId>

In the request files, you can use special XML attributes to leaf elements (these attributes are not sent when a request is invoked):

wst_title="Label of the input field" will mark the element as input field which will then be shown in the dynamic GUI when invoking the request
wst_isPassword="true" has the effect that in the GUI, the data entry is cloaked (with *). If the data should also be cloaked in the log, set also the wst_isEncrypted attribute
wst_isEncrypted="true" defines that the data in this element is encrypted. Only during data entry in the GUI and while sending the request, the data is decrypted.
wst_noUpdate="true" will prevent the element to be updated when the request file is updated.
wst_name="variableName" can be used in URL parameters or HTTP header fields of a REST request to override the name of a parameter/header field (normally, the name of the XML element is used). In REST query parameters, you can set this attribute to "" to add the variable to the URL without its name (and without =)
With wst_inputForm you can define an input form that facilitates the data entry. The form is defined with a JSON object where the key formType can have following values: singleItemChooser (choose 1 value from a list), multiItemChooser (choose 1 or several values from a list), fileOpenChooser (choose a file for opening), fileSaveChooser (choose a file for saving), dirChooser (choose a directory), dateChooser (choose a date), dateTimeChooser (choose a date and time) or numericInput (enter an integer)
Depending on the form type, additional keys are necessary or optional. The optional keys all begin with opt and can be omitted.
wst_isReadonly="true" prevents the user from entering data directly into the input field. This attribute only makes sense in combination with wst_inputForm
With wst_textLines="5" you can define the number of text lines for the input field.

Following wst_inputForm definitions are supported:

  {'formType':'dirChooser','optStartDir':'C:/Downloads'} // you can use / or \\
  {'formType':'fileOpenChooser','optStartDir':'C:/Downloads'}
  {'formType':'fileSaveChooser','optStartDir':'C:/Downloads'}
  {'formType':'singleItemChooser','values':'value1,value2,value3','optLabels':'label1,label2,label3'} // optSeparator is also supported
  {'formType':'multiItemChooser','values':'value1\tvalue2\tvalue3','optSeparator':'\t'} // optLabels is also supported
  {'formType':'dateChooser','format':'dd.MM.yyyy'}
  {'formType':'dateTimeChooser','format':'yyyy-MM-dd\'T\'HH:mm:ss'}
  {'formType':'numericInput','minValue':1900,'maxValue':2100}

If there are no wst_ attributes in the request, the request is sent unmodified (see ApiRequest.baRequest)

REST webservices can use more HTTP commands than just POST. They normally use GET to retrieve data and PUT or POST to send data. Data can be passed as URL parameters or as PUT/POST data. The requests are defined the same way as for SOAP requests, but with following changes:

HTTP command: Choose what the service wants
Request data: The request data is defined as XML data with following structure: The root element can be named as you like and can contain following 3 child elements:
- httpHeaderFields: Add this element if you need to set HTTP header fields. The children's name and content will set the header fields. If the content is empty, the header field will be removed. Header fields can be set in multiple ways. When this is the case, the fields are set/overwritten in following order: webservicefile:webservice node, webservicefile:request node, request XML file, API method ApiRequest.setHeaderField
- relativeURL: This element is normally always needed. The children of this element can be named as you like. It is the content which is used to build the URL later on.
- parameters: Add this element if you need to pass URL parameters. The children of this element must have the same name as the name of the parameters you want to pass. The content will be sent as value of the parameter.
- POSTdata: Add this element if you need to send data with the PUT or POST command. The children must conform to the specification of your REST webservice. The optional attribut "Content-Type" can be set to "application/json" for JSON data or to "application/x-www-form-urlencoded" to send form-encoded parameters. The default-value is "application/json" for REST webservices and "text/xml" for SOAP webservices.

Below, there is an example for the Pivotal Tracker API (http://www.pivotaltracker.com/help/api).

<PivotalTracker>
  <relativeURL>
    <part1>projects</part1>
    <part2 wst_title="Project number">1234</part2>
    <part3>stories</part3>
  </relativeURL>
  <parameters>
    <token wst_title="Security token" wst_noUpdate="true">010203040506070809A0</token>
  </parameters>
  <POSTdata>
    <story>
      <story_type wst_title="Story type">feature</story_type>
      <name wst_title="Story name">User Story 123</name>
      <requested_by wst_title="Requestor"&gtTom Arn</name>
      <description wst_title="Story description">This is the user story number 123</description>
    </story>
  </POSTdata> 
</PivotalTracker>

If you define the (base) URL for this webservice as https://www.pivotaltracker.com/services/v3 the request data above will create a dynamic GUI where you can enter the relative parts of the URL, the URL parameters and the data for the POST. When the request is sent to the webservice, following HTTP raw code will be sent:

POST /services/v3/projects/1234/stories?token=010203040506070809A0 HTTP/1.1
Host: www.pivotaltracker.com
Content-Type: text/xml; charset=utf-8
Content-Length: 181

<story>
  <story_type>feature</story_type>
  <name>User Story 123</name>
  <requested_by>Tom Arn</name>
  <description>This is the user story number 123</description>
</story>

top

Data encryption

Data encryption is used in following contexts:

to encrypt webservice files (*.wst5) with a password
to encrypt the webservice file password when used in scripts with API.loadWebserviceFile: to get an encrypted password, start the GUI, select the root node and choose Menu -> Extras -> Encryption
to encrypt request passwords when used in scripts with ApiRequest.setPassword or API.guiGetUserInput: to get an encrypted password, start the GUI, select the webservice and choose Menu -> Extras -> Encryption
to encrypt data fields in request files: use the wst_isEncrypted attribute and let the APP handle the encryption. Encrypted passwords generated in the GUI will not work here.

Finding and replacing data

You can search for webservices / requests that contain the string you are searching for. The search is always case-insensitive and searches all text fields of all entries.
'Find' always searches from the root of the tree. 'Find next' continues the search from the last found entry (not from the currently selected entry).
With 'Find and replace' you can define a text which, with 'Replace, find next' ,will replace the search string in the currently selected entry.

top

Invoking requests

In order to perform a webservice request, you must select a request and invoke it. The program will then dynamically build and show a GUI based on the defined request file. Enter all inputs and press OK. The program will then put your inputs into the request, send it to the webservice and display the response in a new tab on the screen. For SOAP webservices, also the request is shown in a tab on the screen.

top

Invoking a batch of requests

If you need to invoke the same request several times with different data, you can automate this task by using the batch invoke function:

File path: Choose the file containing the input data. The file must be a tab-delimited ANSI encoded text file. Every line contains all input fields of one request. In the data fields you can use ^t for tabulators and ^n for new lines.
Show response in GUI: If checked, every response will be shown in a tab of the GUI.
Auto-Log: This read-only checkbox shows the Auto-Log option of the request. If checked, all responses are automatically logged.
Save request: This read-only checkbox shows the Save-request option of the request. If checked, the request file will be updated after every request. For performance reasons you should un-check this option in batch mode.
Start: Starts the batch process. By pressing the button again, the process can be aborted.

This feature depends on the type of license you purchased and might therefore not be available to you.

top

TLS client authentication

If your client credentials are in a PKCS12 file (extension .p12) you need to extract the private key and the certificate with the openssl program.

To extract the certificate enter following command:
openssl pkcs12 -clcerts -nokeys -in yourFile.p12 -out yourFile-clcert.pem
This will create the text file yourFile-clcert.pem containing the certificate in following block:
-----BEGIN CERTIFICATE----- MII... -----END CERTIFICATE-----
You can now copy and paste this block to WebserviceTool.

To extract the private key enter following commands:
openssl pkcs12 -nocerts -in yourFile.p12 -out yourFile-private.pem openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in yourFile-private.pem -out yourFile-private_pkcs8.pem
This will create the text file yourFile-private_pkcs8.pem containing the unencrypted private key in following block:
-----BEGIN PRIVATE KEY----- MII... -----END PRIVATE KEY-----
You can now copy and paste this block to WebserviceTool.

Since the file yourFile-private_pkcs8.pem contains your private key in unencrypted format, make sure to savely erase this file afterwards and use a secure password for your webservice file (.ws5) to ensure your private key is well protected.

top

Multi-user shared installation support

Several users can start the application from a shared installation and can use shared webservice definition files. For this the application supports following features:

Installation to a central, shared directory by using the manual installation method (WebserviceTool_win32manual.zip)
The file locking on .ws5 files prevents that the users are overwriting each other's changes. The lock state can be viewed under File > Infos and it is displayed in the first tab: [W] = you can write, [R] = you can only read, [F] = you can now take over the write lock, [f] = you can take over the write lock after reloading the .ws5 file
To allow each user to have his own copies of the request files and his own log files, an environment variable (e.g. %USERNAME%) can be used in the path of the request directory. This environment variable must be set before the application is started.
Protection against modifications with password
Suppression of passwords in logs

top

Automation with BeanShell Scripts

With BeanShell Scripts (www.beanshell.org) you can automate whole processes, in the GUI and from the commandline. The scripts must have the extension .bsh, must be written in UTF-8 encoding and must be signed. If you do not write your scripts with the built-in editor, then you must finally open the finished script in the built-in editor and save them. This will add / update the signature in the top line of the script.

In the settings you can define that you want to confirm scripts with a foreign signature, before they are executed. If, in adition, you define that you want to cache the confirmed script signatures, your confirmations will be stored (in %userprofile%\WebserviceTool\SignatureCache.properties), so you won't have to confirm unchanged scripts again.
In the settings you can also define regex patterns with which you can match error messages in the script console. With the button "Goto error" in the script console you can then open the script in the editor and go to line which caused the error. You can define several regex expressions, 1 per line. The expressions must contain a group <filename> and optionally a group <linenumber> . In the standard settings, you'll find some regex examples.

In the scripts you can use all classes from the Eve Class Library and from the other included Java Libraries (see separate API documentation).

Example for a GUI script:

this.interpreter.setStrictJava(true);
import ch.tanapro.WebserviceTool.api.*;
import bsh.*;
import nanoxml.*;

ApiWebserviceFile awsf;
ApiRequest req;
ApiResponse resp;
String token;
boolean ok;
int rc;

// checks for error and cleans up in case of error
boolean fnCheckForError()
{
  if (API.lastError == null) return false;
  System.out.println(API.lastError); 
  return true;
}

// main script
System.out.println("Starting GUI script");
if (!API.isGuiAvailable())
{
  System.out.println("This script can only run from the GUI");
  return;
}

// get currently open webservice file
awsf = API.wsFile;

// get request
req = API.getRequestByID (1454686907404L); // the id can be found in File -> Infos
if (fnCheckForError()) return;
System.out.println("Token request loaded successfully");

// let the user enter the token data
rc = API.guiEditRequest(req);
if (rc==1) API.lastError="Cancelled by user";
if (fnCheckForError()) return;

// invoke token request
System.out.println("Sending token request...");
resp = API.invokeRequest (req, null);
if (fnCheckForError()) return;
System.out.println("Token request invoked successfully");

// show in GUI
rc = API.guiShowInGUI(req, resp, "");
if (fnCheckForError()) return;

// get token from response
System.out.println("Getting token");
XMLElement xml = API.getXMLElementByXpath(resp.xResponse, "/REST/XML/access_token");
if (xml==null) API.lastError="Token not found";
if (fnCheckForError()) return;
token = xml.getContent();
System.out.println("Token found successfully");

// get request selected in GUI
System.out.println("Invoking request #"+awsf.selectedRequest);
req = API.getRequestByID (awsf.selectedRequest);
if (fnCheckForError()) return;
System.out.println("Request loaded successfully");

// let the user enter the request data
rc = API.guiEditRequest(req);
if (rc==1) API.lastError="Cancelled by user";
if (fnCheckForError()) return;

// invoke request
System.out.println("Setting token...");
req.setHeaderField ("Authorization", "bearer "+token); // set access token
System.out.println("Sending request...");
resp = API.invokeRequest (req, null);
if (fnCheckForError()) return;
System.out.println("Request invoked successfully");

// show in GUI
rc = API.guiShowInGUI(req, resp, "b");
if (fnCheckForError()) return;

To run a script from the commandline, the program must be started as follows:
java -cp eve.jar Eve WebserviceTool.eve -S scriptfile.bsh
oder
eve WebserviceTool.eve -S scriptfile.bsh
You can get a complete list of supported program parameters with the parameter -?

Example for a commandline script:

this.interpreter.setStrictJava(true);
import ch.tanapro.WebserviceTool.api.*;
import java.util.Vector;
import bsh.*;
import nanoxml.*;

ApiWebserviceFile awsf=null;
ApiRequest req;
ApiResponse resp;
Vector vInput, vData;
boolean ok;

// checks for error and cleans up in case of error
boolean fnCheckForError()
{
  if (API.lastError == null) return false;
  System.out.println(API.lastError); 
  if (awsf!=null) API.closeWebserviceFile();
  return true;
}

// main script
System.out.println("Starting commandline script");

awsf = API.loadWebserviceFile(API.webserviceFile, "N7YExq7qhDbFLkMyYPxN2h7zk83Nse/+JQvuQw00IZnZPJPQWJRELGcqPr2YBpwc1x/q3vN7I11RdAZWW062PaBOvOZYLJbfZa2V4IOSYAP+juy8XGiH/+qHYpGodqro");
if (fnCheckForError()) return;
// get the key with:
// System.out.println(API.getEncryptedKey("the password for the webservice file"));

req = API.getRequestByID (1454402306498L);
if (fnCheckForError()) return;

vInput = API.readInputFile(API.inputFile); // Vector of Vectors of String
if (fnCheckForError()) return;
vData = (Vector) vInput.get(0); // Vector of Strings
resp = API.invokeRequest (req, vData);
if (fnCheckForError()) return;

// You can get the response like this:
// String response = resp.xResponse.toString();

System.out.println("Saving logs...");
resp.saveLogs();

API.closeWebserviceFile();

More details about the API can be found in the separate API documentation.

Restrictions

This feature depends on the type of license you purchased and might therefore not be available to you.

top

Starting WebserviceTool with commandline options

Start WebserviceTool with

java -cp eve.jar Eve WebserviceTool.eve [options]
   or: 
javaw -cp eve.jar Eve WebserviceTool.eve [options]
   or: 
evew WebserviceTool.eve [options]
   or: 
eve  WebserviceTool.eve [options]

Use javaw.exe/evew.exe for GUI mode and java.exe/eve.exe for console mode.

Available options:
[-?], for showing the commandline options
[-d], for debugging
[-F <fontSize>] (default = automatic)
[-W <webserviceFile.ws5>]
[-S <scriptFile.bsh>]
[-U <username>], only together with -S
[-P <password>], only together with -S
[-I <inputFile>], only together with -S
[-O <outputFile>], only together with -S

Returns following exit codes:
0 = OK
1 = Warning
2 = Error
The exit code can be set from the script by calling
API.setScriptResultCode(int code)

If you run WebserviceTool on Windows, then start it from a batch file and include following command before starting WebserviceTool:
set J2D_D3D=false
This will massively improve the graphics performance on many systems.
With the Java VM, WebserviceTool performs in general 3 or 4 times better than with the Eve VM.

top

Debugging

If you encounter problems when working with this application, you might want to activate the debug mode. This mode gathers data on certain operations and you can then view this data after the operation is done. The debug data might help you find out what is going wrong.
When the application starts, the debug mode is always off. The application does not remember the state of the debug mode.

top

tanapro WebserviceTool (Desktop)

WebserviceTool v5.10

What is WebserviceTool ?

Multi language

Entering and organizing webservices

Defining proxy settings

Adding a new webservice

Adding a new request

Creating request files

Data encryption

Finding and replacing data

Invoking requests

Invoking a batch of requests

TLS client authentication

Multi-user shared installation support

Automation with BeanShell Scripts

Starting WebserviceTool with commandline options

Debugging