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
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:
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).
At the root node you can define the http proxy settings:
When adding a new webservice, you'll need to enter following things:
name:value
When adding a new request for a webservice, you'll need to enter following things:
name:value
. To delete global header fields, leave the value empty.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):
{'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:
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">Tom 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>
Data encryption is used in following contexts:
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.
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.
If you need to invoke the same request several times with different data, you can automate this task by using the batch invoke function:
This feature depends on the type of license you purchased and might therefore not be available to you.
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.
Several users can start the application from a shared installation and can use shared webservice definition files. For this the application supports following features:
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.
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.
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.