Configuring Tolven V2 Web Services

From DOC

WEBV2_20120109

Note: Tolven V2 and this Tech Note are Beta. This means that this Tech Note, along with the procedures in it, are in a state of continual development and may change without notice from Tolven. We recommend that you place a watch on the WIKI so that you are informed when changes are made.

All other trademarks are the property of their respective owners.

Follow the instructions in this Tech Note if you intend to use the Tolven Healthcare Platform Web Services API.

See the wsdl's for detailed information on the available services.

Click Printable version in the navigation pane to the left to print a copy of this guide before you start.

CR/LFs in Code Samples
Carriage Return/Line Feeds were added to some code samples for the sake of formatting when you print this Tech Note:

If you are copying and pasting code from this guide to the command line, be aware that those CR/LFs may carry over.

Step 1 - Locate WSDLs

Use a Web browser to view each of the WSDLs to confirm that the services have been deployed (default is dev.able.com):

Step 2 - Download (Export) the Tolven Certificate

While viewing any one of the WSDLs, use a Web browser to view the SSL certificate for the Tolven application and download it to your drive. Its CN should be dev.able.com if you followed the default installation instructions. Please verify this using your browser, because you will need it.

The instructions for downloading the certificate depend on your browser:

In Internet Explorer, go to Tools>Internet Options>Content and then click Certificates.

In Firefox, navigate to Tools>Page Info. Click Details and then click View Certificate.

Then export the certificate to your drive.

Step 3 - Create Client Certificate and Keystore

Here, we are assuming that the webservice client is running on a machine named ‘devclient.able.com’.

keytool -genkey -alias tolven -dname "cn=devclient.able.com, ou=services, o=tolven, c=US" -keystore keystore.jks -storepass tolven 
-keypass tolven -validity 7300

Step 4 - Add Server Certificate to Local Truststore

Add the downloaded certificate above to your cacerts.jks. Here, the file dev.able.com.cer is the certificate just downloaded from the server in step 7.

keytool -import -alias dev.able.com -file dev.able.com.cer -keystore cacerts.jks -trustcacerts -storepass tolven -keypass tolven

Step 5 - Generate Web Services Clients

The client classes are located in the org.tolven.wsclient.example project, which you need to check out from SVN branch qa/v2.1.

Step 6 - Locate Newly Generated Stubs

When finished, refresh the project and then locate the jaxws directories which contain the newly generated stubs.

The main Java classes which supply the Web Service client functionality are:

EchoWebServiceClient.java
GeneratorWebServiceClient.java
DocumentWebServiceClient.java
TrimWebServiceClient.java

Each of these classes, contain instructions on how to execute their main method. Make sure that the domain name in the WSDL supplied as a parameter to the main methods is the same as that of the Web Service (for example, dev.able.com).

Step 7 - Edit Hosts File

This step is only required if the default dev.able.com was not used.

If you used something other than dev.able.com, you must also add the following line to your hosts file, so that this made-up domain is recognized on your system:

127.0.0.1 dev.able.com

Step 8 - JBoss Setup

JBoss users who want to use Tolven Web services but are also using self-signed certificates, that is, not real domain names, must perform this step.

1. In order to test for Web services in a development environment, you must install (or upgrade) JBoss with the following ant override property:

jboss6.ignoreHttpsHost=-Dorg.jboss.security.ignoreHttpsHost=true

2. If you already have JBoss installed, you can also manually add the value portion of this property (-Dorg.jboss.security.ignoreHttpsHost=true) to the following Tolven scripts:

tolven-jboss6/bin/startTolvenJBoss.sh tolven-jboss6/bin/startTolvenJBoss.bat

2. Restart JBoss.

Step 9 - Build Web Services Client

Look at the targets called in 'generate-ws-clients'. If you've changed the default domain name, then just before running the target 'build-wsclient-jar', replace all dev.able.com with your domain name.

Copy the jar 'tolven-wsclient-examples.jar' to a new directory. We will use this jar to run the Web Service clients.

Open a command prompt from this directory and run the commands in the next step.

Step 10 - Test the Web Service Interfaces

Use the test clients provided by Tolven to test the Web service interfaces prior to attempting to connect from the eventual calling program. Call examples are included below for the echo and document service. Both clients require access to the local keystore for the calling system and the truststore that contains the public key for the target Tolven server. The document service also requires an accountID and a document filename for the document to be submitted via the Web service. The Tolven instance receiving the request must be configured with a processor that is capable of handling the submitted document type and structure. The Tolven plugin, org.tolven.ccr, includes a document processor and sample ccr documents that you can use for this purpose.

Note: In the examples provided, the HeaderHandler class populates the SOAP header, and the HeaderHandler class is where the expiration time of the request is defined. By default, the time is 60 secs, which makes its way there via the HeaderHandlerResolver class from the client example classes. This means that the common time between the server and client MUST be accurate and must be synched. In other words, you should close the clocks on the client and server platforms to in-synch in order for the Web service to succeed. Even a time difference of as little as five minute could result in the client request's expiring before it ever gets to the server. If you get a message in JBoss for which you cannot find a reason, this may be the cause.

Change the file paths for certificates and url for WSDL as per your configuration

10.1 Call the Echo Service

java -Djavax.net.ssl.keyStore=C:\tolven-config\credentials\devclient.able.com\keystore.jks ^
-Djavax.net.ssl.trustStore=C:\tolven-config\credentials\devclient.able.com\cacerts.jks ^
org.tolven.client.examples.ws.echo.EchoWebServiceClient ^
https://devclient.able.com/ws/echo?wsdl

10.2 Call the Generator Service

The Generator Service provides as its standard output the <test_document_filename> document. Because this document will be generated by Tolven, this will verify that both output and input are working correctly. You will then call this document in the next step. You can use another document name, but be sure and use the correct name of the document you generated when you call the document in the next step.

java -Djavax.net.ssl.keyStore=C:\tolven-config\credentials\devclient.able.com\keystore.jks ^
-Djavax.net.ssl.keyStorePassword=tolven ^
-Djavax.net.ssl.trustStore=C:\tolven-config\credentials\devclient.able.com\cacerts.jks ^
org.tolven.client.examples.ws.generator.GeneratorWebServiceClient ^
https://devclient.able.com/ws/generator?wsdl <''test_document_filename''>

10.3 Call the Document Service

In this example, <accountID> is the numeric ID that is associated with an account to which the Tolven real user has access. The client will prompt for username and password after you invoke the call.

java -Djavax.net.ssl.keyStore=C:\tolven-config\credentials\devclient.able.com\keystore.jks ^
-Djavax.net.ssl.keyStorePassword=tolven ^
-Djavax.net.ssl.trustStore=C:\tolven-config\credentials\devclient.able.com\cacerts.jks ^
org.tolven.client.examples.ws.document.DocumentWebServiceClient ^
https://devclient.able.com/ws/document?wsdl <test_document_filename> <accountID>

Facts about Configuring Tolven V2 Web ServicesRDF feed