Using OpenClinica Web Services - OpenClinica Reference Guide

2.1 Using OpenClinica Web Services

Installation

To use OpenClinica Web Services, they must first be installed. Follow the instructions in the installation guide in your OpenClinica download, or contact your OpenClinica Enterprise support representative.

The OpenClinica Web Services module is deployed on Apache Tomcat as a separate “war” (web application archive) from the main OpenClinica application. A typical OpenClinica Web Services installation is as follows: the 2 directories (“OpenClinica” for 3.1.x-web and “OpenClinica-ws” for 3.1.x-ws) are present in the tomcat/webapps with the same db connection parameters (db=openclinica and clinica user).

In this configuration, you can access the usual web interface through https://yourDomain.com/OpenClinica, and access the web services by SOAP requests using https://yourDomain.com/OpenClinica-ws. When you verify (as it is explained in the documentation) your -ws installation by loading https://yourDomain.com/OpenClinica-ws in your browser, it is only for confirming the application is deployed and can connect to the database. It will return a login page with an empty rss feed, but you cannot access the web application through this login page.

You can then begin to work on SOAP requests, authenticating with the login and the password of a user with the option “Authorize SOAP web services in this account” ticked.

Dates

All date values in OpenClinica Web Services should use the (ISO 8601) YYYY-MM-DD format.

OpenClinica Web Services Security

OpenClinica Web services use the same security infrastructure as the OpenClinica web application. Passwords stored in OpenClinica use 1 of 2 digest types. The primary type is AES. Older installations may have some user accounts that have MD5 passwords. MD5 has been deprecated since OpenClinica 3.0.

Spring XwsSecurityInterceptor is used to secure OpenClinica Web Services. For more information on Spring XwsSecurity go to:

http://static.springsource.org/spring-ws/sites/1.5/reference/html/security.html

To use OpenClinica Web services:

The user is expected to provide his user name in clear text and his hash based password.
The user account should be authorized to use web services; this authorization is granted in User Account setup.
The password will need to be encrypted using the appropriate digest type.
OpenClinica web services are secured and require that you modify the “<soapenv:Header/>” line in the SOAP XML request with the following (substituting username/password as appropriate):

<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1"
 xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsse:UsernameToken wsu:Id="UsernameToken-27777511"
 xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:Username>username</wsse:Username>
<wsse:Password
 type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">
 password</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>

Export PDF