Getting Started

This guide will help you interact with and extend OpenClinica 3 in a programmatic way. This guide is for developers who have a basic familiarity with HTTP and web services. HTML and javascript expertise helps too.

The Basics

You’ll likely want to start with the REST API. This provides you with hooks to interact with an OpenClinica study in a lot of neat ways.

Access the OpenClinica REST API

REST API is a fancy way of saying you can access a URL that gives you back XML or JSON data in a consistent format. REST APIs are becoming the lingua franca of the web, and are widely used in mobile apps, social networking Web sites, mashup tools, and automated business processes. They are easy to leverage by most tools, including many that are free. Best of all, the learning curve is not too steep, especially if you’re already familiar with the basics of how the web works.

We also have a SOAP API. If you’re not sure what this is, use REST. We’re no longer adding new functionality to SOAP. API references in this guide refer to the REST API unless explicitly mentioned otherwise. 

Set Up Your Development Environment

You’ll need an OpenClinica environment to develop and test your application or module against. If you’re an OpenClinica Enterprise user, you may be able to use your test environment. Find out the URL of the test environment and make sure you have a test study and a user account on the system. Otherwise, you can download and install the latest version of OpenClinica Community Edition. 

Security and Permissions

Different parts of the API use different security mechanisms. We’re working on unifying these but for now you’ll need to understand the differences, and take note of which API methods support which types of authentication. 

  • Session: You need to programmatically login to /pages/login/login and subsequently call the API.  
  • API Key: Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password. You can obtain your api key by calling this API:
  • OAuth: All developers need to register their application before getting started. A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.
  • Network/firewall dependent: Network/firewall constraints need to be put in place to secure these APIs.  

 Each API method is labled with the authentication method(s) it supports.

Getting under the hood

Parts of this guide contain specifications on the OpenClinica eCRF meta model, how we handle dates and datatypes, and how we interpret and implement the CDISC Operational Data Model. 

Building Modules

Follow this guide to build new data extract/reporting formats. 

OpenClinica will soon include a more comprehensive developer toolkit so you can easily develop your own custom modules, including dashboards, workflows, and visualizations. *** UNDER CONSTRUCTION, check back frequently! ***

Developing the Core

If you can’t accomplish what you need via a module, and/or are itching to fix bugs, expand the API, and otherwise make OpenClinica better, you can help improve OpenClinica core. 

This guide will help you build from the source code and set up a development environment.


Sharing your work helps make OpenClinica more useful for everyone and gives you help improving and maintaining it. Submit code as a pull request to github. Share your ideas/questions/testing/writing on the OpenClinica forums (you’ll have to register first). Someone out there might be thinking along the same lines and want to help you out!