Using SoapUI Webservice Client with KCS Webservices (TWS)

Last updated
Save as PDF

Article # 3034917 - Page views: 178

Issue

I want to demonstrate my customer how he can use the Webservice functionality provided by TWS.
But I have no programming skills to develop a VB.NET, C# or Java program.
Is there any tool available which could be used to simulate a Webservice client using the TWS web service?

Solution

Yes there is a Java based Webservice client named SoapUI, which can also be used to simulate a Webservice client using the TWS Webservice.
The step by step procedure described below explains how you can use this client to send a message with a PDF attachment using the TWS "SendMessage" web service method.

Download location:
Navigate to the SoapUI Webpage. Under Downloads - SoapUI you will be rerouted to http://sourceforge.net/projects/soapui/files/ where you can download the latest version of the SoapUI client.
If you want to install the SoapUI client on a 64-bit operating system you should download and install Version of the SoapUI client (e.g. http://sourceforge.net/projects/soapui/files/soapui/5.1.3/SoapUI-x64- 5.1.3.exe/download) SoapUI provides also a PRO client, but for testing TWS functionality the FREE version is sufficient. The required Java package is included in the setup files and will be installed automatically.
TWS configuration options:
TWS must be already installed. Installation and configuration for TWS is not covered within this article, we will only discuss some important configuration options.
Please verify/reconfigure the following items in your TWS configuration (Windows start menu entry Kofax Communication Server - Configure TCOSS Web Services)
- Did you define a valid KCS UserID and Password in the section TCOSS of the TWS configuration tool?
  If the UserID and Password are specified within the TWS configuration tool, you might post a webservice request to the TWS Web server anonymously, ie. without entering additionally any UserID/password in the SoapUI client. If the UserID and Password are not specified within the TWS Configuration tool, you must configure the SoapUI client with a valid UserID/password, which is described below in the section Authentication
- Did you specify a valid Local computer name within the section HTTP of the configuration tool?
  The Local computer name should be a full-qualified hostname. The machine running the SoapUI client should be able to resolve this hostname to the correct IP address running the HTTP listener for TWS. The Local computer name is also included in the WSDL (Web service description language file), if a webservice client like SoapUI connect to the Webservice and requests all possible Webservice methods. Therefore you should not leave the default value localhost and it should be already configured correctly before you connect with the SoapUI client to the TWS web service.
- Is there any value specified in the field Local IP address in the HTTP section of the configuration tool? Typically the local IP address is only specifed, if the machine running TWS contains multiple network adapters and you want to bind the TWS HTTP listener to one specific network adapter/IP address. If this configuration parameter is kept empty, which is the default value, TWS will bind the HTTP listener to all local IP addresses.
- What is the configured Local Port for TWS, the default value is the TCP port 25082. IP Address and port are important when connecting the SoapUI client to the TWS server.
- Is the Use SSL checkbox enabled within the HTTP section of the configuration tool? If the SSL option is enabled, the SoapUI client will connect with the https: prefix, without SSL you will use the http: prefix.
  If the SSL option is enabled you have to request also a certificate for the machine running TWS, e.g. using the openssl tool and you must provide valid certificates for the following fields:
  - The field SSL Server certificate contains the Webserver certificate in base-64 encoded format. You get the server certificate from a certification authority (CA) after putting a certification request to the CA.
  - The field SSL Private key contains the private key in base-64 format (the private key is generated e.g. with the openssl command line tool together with the certification request)
  - The field SSL chain certificate contains the root certificate of the certification Authority in base-64 format

Please Note: For simplicity the article below does not cover a connection to TWS configured for SSL

TWS 1.png

Installation / starting the SoapUI client
Execute the SoapUI-x64-x.x.x.exe file. When the setup asks for the components to install, it is sufficient to install just SoapUI, the components Source, HermesJMS and Tutorials can be deselected.
After Setup is finished, start the SoapUI client from the Windows Start menu: SmartBear - SoapUI x.x.x - SoapUI x.x.x.
When starting the SoapUI client for the very first time, it will ask you to register with an email address, but you can select the option Skip
Afterwards SoapUI will show you an empty project workspace.

Creating a new SoapUI Project
Select from the menu File - New SOAP Project
In the next dialog named New SOAP Project, select a project name, e.g. TWS
In the field Initial WSDL: enter the http URL leading to the TSL.WSDL file, e.g. http://twsServerName:25082/file/tsl.wsdl, see Notes below.
The checkbox Create Requests - Create sample requests for all operations should be enabled, which is the default setting
The other two checkboxes Create TestSuite and Relative Paths should be cleared

Notes:

http is the protocol to connect to TWS: If checkbox Use SSL is enabled within the HTTP Settings of the TWS Configuration panel, use https instead

twsServerName is the full qualified hostname of the machine running TWS, you might also use directly the IP address which is configured as Local IP Address in the TWS configuration. If SoapUI and TWS are installed on the same machine, you might also use localhost

25082 is the Local Port as configured under HTTP Settings of the TWS Configuration panel, port 25082 is the default

tsl.wsdl is the webservice description file for the webservice methods provided by the TWS workflow engine. It must be specified with the full path.

Press OK to create the project and the sample requests. You can save the project any time using the menu option
File - Save All Projects

The SoapUI Main Window
Now the SoapUI client loads the definitions from the tsl.wsdl file and afterwards it will show you all available Webservice methods in the left treeview.
For each of the available Webservice Methods you will find a sample request, if you expand the small + on the left side of the Webservice method name.
You can modify the Request 1, which is automatically added at the time the Project is created or you might add a new Request, which is the method we will use to check our example.

To add a new request, right-click the SendMessage node in the left tree view window and select the context menu option New Request.

Assign a name to the new request, e.g. Simple message with PDF attachment and press OK. The request will be added as child item below the SendMessage method in the tree view.
Doubleclick the request in the tree view and it will open a new window, which contains on the left side a request pane with all possible SendMessage parameters and on the right side a response pane. The response pane is initially empty and it will show the server response at the time you sent the request to the TWS Webservice server.
For Beginners: Paste the sample request attached to this article
- Click into the request pane, do a right-click and select from the context menu Select all
- Press the DEL key to clear all contents and get an empty request.
- Load the attached SoapUI-Example.txt into Notepad and within Notepad select the whole content with Ctrl-A. Copy the contents to the clipboard using Ctrl-C
- Navigate back to SoapUI and paste the contents into the request pane using Ctrl-V
- Modify the request according to your needs (e.g. change the fax number under <mic:Recipient> <mic:Address> <mic:Number> from 8664555383 to your own number)
- Continue with Step 9 to send the web service request
For more advanced technicians: Adopt the system provided sample request according to your needs
Instead of importing the example from the attached file you can also double-click the Request 1 and modify this one according to your needs. Follow the best practice rules listed below
- All optional parameters are marked out with the  comment in the sample request.
- Remove all parameters, which are not needed for your request and remove also all those  comments
- Remove any empty lines, which are possibly inserted by paste operations.
- If you want to have multiple message parts, e.g. a message body AND an attachment, select the whole parts from the <mic:Attachment> start-tag to the </mic:Attachment> end tag, copy the part to the clipboard and paste it again in the correct location (just below the previous </mic:Attachment> end tag). Modify then each message part separately. The example attached above also contains a message body and additionally a PDF attachment.
- Specific parameters are defined as enumeration values, e.g. the parameters FaxResolution, DeliveryNotification and SendingCopy
  For those parameters you can only define specific predefined values. To find out possible values, open the tsl.wsdl file in a browser (http://twsServerName:25082/file/tsl.wsdl) and use Ctrl-F to check for the corresponding parameter name (e.g. FaxResolution). In this way you will find out that:
  - FaxResolution has the possible values: FINE and NORMAL
  - DeliveryNotification has the possible values: NO, POSITIVE, NEGATIVE and ALL SendingCopy has the possible values NO, FIRST and ALL
  - Type (for Recipient) has the possible values TO, CC and BCC
  - TciConverter (see also additional notes below) has the posssible values: imgio and tcdc
  - ScaleTo has the possible values: DISABLED, LETTER, LEGAL, A3, A4, A5
  - ImageResolution has the possible values: 0 (=unspecified), 200 or 300
  - ImageCoding has the possible values: ANY, T.6, JPEG and JPEG-GRAYSCALE
  - ....
- Take care that enumeration values are case sensitive, so ...
  if they are shown in the wsdl file with capital characters, write them within your request with capital characters, if they are shown in the WSDL file with small characters, write them with small characters.
- For other parameters the additional documentation within the WSDL file might be also helpful, e.g. for the property Priority, which must be specified with a numeric value, it explains 0=low, 1=normal, 2=high,...12=highest
- In the field BinaryContent you have to provide the binary data of the specified attachment file in base-64 encoded format. Use any of the online base-64 converters (e.g. http://www.motobit.com/util/base64-decoder- encoder.asp) to convert the binary attachment file into base-64 code and paste then the base-64 code into the BinaryContent field.
  The attached SoapUI-Example.txt also contains a PDF attachment, which was converted to base-64 format
- The field BinaryFileName should contain a filename matching the binary data pasted into the field BinaryContent. It is especially important to specify a valid file extension, because the file extension is important for activating the correct conversion script in case of additional alternative content types (e.g. FAX image, TIFF Image) are requested.
- In the section ConversionOptions you specify, whether the original binary attachment format should be additionally converted to other formats, for example:
  - if you want to send out an attachment to a FAX recipient, the attachment must be converted to FAX format (=TCI), therefore you should enable Tci=1 and Binary=1 to you get in addition to the original binary format also a TCI alternative content, which can be faxed out.
  - If you want to send Attachment messages to Kofax Capture in TIFF format, you should set Tif=1 and Binary=1
  - Text=1 is only necessary if you want to send out a binary attachment (e.g. doc attachment) to a pure text based service (SMS, Telex)
  - Pdf=1 creates a PDF alternative content for the specified attachment. This option should be only set to 1, if also a PDF Printer (e.g. Bullzip) is installed on the TWS Server and configured within TWS section PDF Printer Settings
- When specifying the TciConverter, take care of following rules:
  - PDF, Postscript and PCL files and monochrome Image attachment (Black&White Images) formats you should select the TciConverter=imgio
    These files can be converted via TCIMG32.DLL and with the help of 3rd party libraries (Datalogics library for PDF files, Lincoln converter for Postscript/PCL) and therefore imgio is the proper conversion method.
  - All oll other file types (e.g. Microsoft Office files, doc, docx, xls, xlsx, ppt, pptx, html,...) should use the tcdc converter (which includes also conversions using the KfxConverter newly introduced with KCS 10.0)

Authentication - How to specify a UserID and a password within the SoapUI Webservice request
To login into KCS, TWS uses by default the User ID / Password specified in the TWS configuration tool (start menu entry Kofax Communication Server - Configure TCOSS Web Services, section TCOSS)

If the UserID specified in the TWS configuration is empty, you have to specify a valid KCS UserId and password within the SoapUI Webservice request otherwise your webservice request cannot be posted successfully.
If the UserID specified in the TWS configuration is not empty and no UserID/Password is specified in the SoapUI webservice request, the login credentials from the TWS configuration will be used.
If the UserID specified in the TWS configuration is not empty and you specifiy additionally UserID/Password in the SoapUI Webservice request, these SoapUI credentials will be used with higher preference.
To specify a UserID/Password within the SoapUI client, press the Auth button in the SoapUI client, which is located at the bottom of the request pane (see screenshot of the SoapUI main window above)
If the Authorization drop down list shows No authorization, open the drop down list and select the option Add new authorization...
A new dialog opens, select the type Basic authorization (this currently the only authorization type supported by TWS) and press OK

Enter a valid KCS User and his password into the fields Username: and Password:. The field Domain: is kept empty (is used for NTLM authentication, which is currently not supported by TWS)

Please Note: With HTTP basic authentication the userID/password is base-64 encoded within the HTTP header and therefore it is easy to get a valid UserID/password, if someone captures the network traffic. Therefore when using HTTP basic authentication you should enable also SSL.

POST https://vmsb-kcs2012r2:25082/soap/tsl HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8 SOAPAction: "tsl"
Authorization: Basic VENURUNIOnBhc3N3b3Jk
Content-Length: 274754
Host: vmsb-kcs2012r2:25082
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

Sending the Webservice Request
To send the Web service request, press the green Arrow which is located on top of the request pane.
In the response pane you will see a response, either a positive response containing a message ID:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Header/>
    <s:Body>
        <wf:SendMessageResponse xmlns:wf="http://www.topcall.com/2005/MicroWorkflows">
            <wf:MessageID>024EF8CF2A2A21B1</wf:MessageID>
        </wf:SendMessageResponse>
    </s:Body>
</s:Envelope>

or an error message indicating the reason for the error message

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
    <s:Header/>
    <s:Body>
        <s:Fault>
            <faultcode>s:Server</faultcode>
            <faultstring>610 wrong password</faultstring>
            <detail>
                <t:result xmlns:t="http://www.topcall.com/XMLSchema/2004/tn">
                    <t:code>586157318</t:code>
                    <t:info>610 wrong password</t:info>
                </t:result>
            </detail>
        </s:Fault>
    </s:Body>
</s:Envelope>

Level of Complexity

Moderate

Applies to

Product	Version	Build	Environment	Hardware
Kofax Communication Server	10.0 or higher		Tested with SoapUI version 5.1.3 x64

References

Add any references to other internal or external articles

Article # 3034917