HTML Tips to Enhance Your eCRF

In some cases, the display of your OpenClinica eCRF may not be exactly what you had in mind. You may want to highlight key words or phrases, create a bullet point list, or insert a URL or image. Using HTML tags, you can make some simple manipulations to change the look and feel of your case report forms and make them more inviting for data entry.

Using HTML tags to enhance your eCRF

The HTML tags described in this document can be used in the following columns in the CRF Excel template:

  • Items Tab: LEFT_ITEM_TEXT
  • Items Tab: RIGHT_ITEM_TEXT
  • Items Tab: HEADER
  • Items Tab: SUBHEADER
  • Sections Tab: INSTRUCTIONS

What are HTML tags?

HTML, or Hyper Text Markup Language, is a markup language that is commonly used for web page development. HTML is written using “tags” that surround text or elements. These tags typically come in pairs, with a start tag and an end tag:

<start tag>Text to format</end tag>

To insert an HTML tag, simply surround the text you want to format with the desired tag. Below are the HTML tags that work in OpenClinica:


You can download this HTML Tags Knowledge Article to help you to get started.

Inserting URLs and Images

HTML also allows you to insert a URL or Image into your CRF, which may be used to provide users with additional information or references.

Insert a URL

A URL may be inserted into a CRF in order to provide a link to further instructions or protocol information. To insert a URL into your CRF, use the following format:

Inserting images - using HTML tags to optimize your eCRF

Simply replace the areas highlighted in yellow with (a) your URL (inside the quotation marks) and (b) the hyperlinked text that you want to display to the user.

The following example will prompt the user to “Click Here!” and will open the OpenClinica website in a new browser tab:

<a href=”” target=”_blank”>Click Here!</a>

Inserting an image - using HTML tags to optimize your eCRF

Insert an Image

Similarly, HTML can be used to insert an image into your CRF. You might consider using an image to display a pain scale (or other reference image), or even to display your company’s logo.

Inserting an image - using HTML tags in OpenClinica

To insert an image into your CRF, use the following format:

<img src=”images/ImageName”>

Again, simply replace the highlighted text with your image name. You can use PNG, JPG, or GIF image extensions. You can control the height and width of the image using the following format:

<img src=”images/ImageName” width=“n” height=“n”>

The highlighted n corresponds to the desired width and height of the image in pixels.

The following example will insert an image (image1.png) with a width of 300 and a height of 150:

<img src=”images/image1.png” width=”300″ height=”150″>

You can download this Images & URLs Example CRF to help you practice.

The examples included in the above CRF Excel template will insert an image that already exists in the images directory of your OpenClinica application. To insert a custom image, community users will need to place the image in the following directory of the OpenClinica application:


OpenClinica Enterprise customers can request an image be placed on the application server by reaching out to the OpenClinica Enterprise Support team via the Issue Tracker.

Have you used HTML in your CRFs? Let us know if you have any other suggestions or tips!


 The RESPONSE_OPTIONS_TEXT field is not included in the list above, as HTML tags are currently not supported for response options.

 The QUESTION_NUMBER field will display the text properly, but has been known to cause issues when extracting data. Therefore, HTML should not be used in this column.

Calculating ROI for ePRO

I recently delivered a webinar titled “Getting Started with eCOA/ePRO,” in which roughly a third of attendees polled cited expense as the number one reason that has prevented them from adopting an ePRO solution. So what does ePRO really cost? Is it worth it? Here I strive to provide a basic, high-level framework for thinking about the return on investment ROI of eCOA vs. paper.

Let’s start by taking a look at the costs that are unique to each approach.


In a traditional paper based model, you are incurring costs that stem from printing, mailing, data entry, and data cleaning. These are all expenses than can be estimated with a fair degree of accuracy, with the cost of data entry being the most significant of these. To estimate the cost of data entry, see how long it takes to key in a subject completed paper casebook, multiply this by your cost of labor (don’t forget to include overhead!).


The cost side for ePRO is similarly straightforward, but the expense elements are different. You’re either building an ePRO system (which will almost carry a highly unpredictable cost) of buying one (much more predictable cost). Assuming you’re buying, here are the costs you may expect to incur:

· License
· Hosting
· Training and support
· Professional services (e.g. study configuration)
· Devices

You should evaluate whether your study and selected ePRO system will allow for patients to use their own devices, or if you will need to provision devices (or some mix thereof). The cost of provisioning devices, especially for a global study can be significant—in addition to the costs of the devices themselves, you will need to consider the costs of data plans, and logistics associated with supporting the devices. I’m a big fan of BYOD (bring your own device) but, depending on the study, it may not be feasible to utilize while maintaining scientific validity of data collected.

Once you’ve mapped out your costs of each route, you can begin to weigh these against the benefits of going eCOA.


Paper vs. eCOA

When you boil it down, people employ ePRO/eCOA to maximize data quality, increase productivity, and/or enable new capabilities that help answer their research questions. ePRO is e-source, so you don’t have worry about administering a paper data entry process. Depending on the study, the cost savings from this alone might justify ePRO.

There are some additional benefits ePRO offers over paper that may be harder to quantify, but nonetheless  very real. For example, there are clear data quality benefits to ePRO. The electronic system can ensure a minimum standard of data quality through edit checks and enforced data structures. ePRO data will always be cleaner than the same data captured on paper.

Benefits and Motivations for eCOA


The use of an ePRO system also allows you to know for sure when the data were recorded. For instance, patients can be reminded automatically when their diaries are overdue, and you now only have much stronger assurances that data were collected at the appropriate time (vs paper), you can also more easily monitor the study progress.

Bypassing manual data entry and having the system provide notifications to subjects to ensure data are captured in a timely way might allow for faster and better in-study decision making and even may accelerate study closeout. Also, an increasing amount of evidence exists that mobile-based messaging and communication strategies help increase patient engagement and treatment adherence. And of course, not having to deal with a stack of paper during a site visit might allow the clinician’s interaction with the patient to be higher quality.

Quantifying the benefits of all of these things can be tough, but start with those which are most quantifiable and see if those items alone these alone provide a compelling ROI (from my experience they often do).  Then the less tangible benefits become gravy to the ROI argument.  When modeling costs over time and a pay-back period, keep in mind that ePRO will typically carry a higher upfront cost than paper, with the cost saving benefits realized downstream over time. With today’s technologies, even most smaller studies should be able to realize a positive payback.

Naturally, there may be additional ROI factors to consider which are specific to your situation. If you have particular thoughts, questions, or experiences on this topic I encourage you to add a comment to this post.

Engage. Learn. Repeat.

At OpenClinica we are driven to reduce obstacles to the advancement of medical research. The OpenClinica open source project started because EDC was too complex, too inaccessible, and too expensive. Not to mention far too difficult to evaluate and improve. So we built an EDC / CDMS platform and released it under an open source license. It is now the world’s most widely used open source EDC system and has an active, growing user community.


As the user base grew, we listened to users and understood that integration and interoperability were another major obstacle. While we don’t claim to have fully cracked that nut yet, OpenClinica’s CDISC ODM-based APIs have been pretty widely adopted and helped to drive some significant innovations. These APIs have been improved upon by a large number of developers in the few years they have been part of the codebase.


As we continue to improve the clinical and researcher experience, our attention has more recently been directed to the experience of trial participants. The difficulty of meaningful, timely engagement with these volunteers also strikes us as an obstacle to successful research. We live in a world where 90% of American adults have mobile phones, 81% text, and 63% use their phone to go online (Pew), and even older age groups are adopting smartphones at a rapid pace [1]. Because of this, we think that mobile technology could be a pretty effective means to help more meaningfully engage participants research.


Why is this important? Treating research volunteers as participants, as opposed to subjects, can lead to concrete benefits – improving participation, motivation, and adherence. Increasing your ability to meet recruitment goals, budget, and completion timelines. Getting more complete, timely data. Even enabling new protocol designs that better target populations and/or more closely align with real-world use. But most of all, it just seems like the right thing to do. As one HIV trial participant put it, “I’d initially had this nagging fear in my head, that, once recruited, I would cease to be nothing more than a patient number – a series of digits, test results and charts in a file – which is quite a daunting prospect when you’re not entirely sure how your body is going to respond to the vaccine. This could not have been further from the reality of the trial. I felt safe, informed and valued at every stage of the trial.”


The great (and often unrecognized) news is that so many of the people involved in research and care already do an unbelievable job creating this type of engagement – making participants feel safe, informed, and valued. But it takes a lot of work. With a mobile-enabled, real-time solution like OpenClinica Participate, you can provide an engagement channel and data capture experience that is simple, elegant, and easy to use on any device. Because it is fully integrated with OpenClinica and captures data in a regulatory-compliant manner, you can reduce time and headache for your research team from, for instance, merging disparate sources of data and keying in paper reports. Leaving you more time to focus on the kinds of human to human engagement that technology cannot do.
Participate Webinar
[1]  For the over 55 age group, most likely to participate in many types of trials, the picture is a bit different. As of 2013, around 80% have mobile phone but only 37% are smartphones. However over-55s are the fastest growing smartphone adopters, expected by Deloitte to soon reach 50% and reach parity with other age groups by 2020.
See Outside of the developed world, the picture is different, though the opposite of what you might expect. According to Donna Malvey, PhD, co-author of mHealth: Transforming Healthcare, cell phones are even more pervasive, and mHealth “apps are the difference between life and death. If you’re in Africa and you have a sick baby, mHealth apps enable you to get healthcare you would normally not have access to… In China and India, in particular, mobile apps can bring healthcare to rural areas. “


OC15 in Review

Two weeks ago, members of the OpenClinica community converged on the Lloyd Hotel in Amsterdam for the 2015 OpenClinica Global Conference. The event was highlighted by a keynote from John Wilbanks, who inspired us with a great talk on how mobile technology and open source can help break new ground in understanding disease. Smartphone-based engagement tools, used in real world settings, can enable greater participation in research, cut costs, and make new research designs and insights possible. It’s not just theoretical, as his company, Sage BioNetworks, is walking the walk by open-sourcing its e-consent toolkit and working with Apple on studies using ResearchKit.

Our community demonstrated it is also a powerful driver of innovation. Through innovative applications, by integrating with other powerful tools, or augmenting the OpenClinica core with custom built extensions, OpenClinica is playing a role in patient engagement, big data, and translational science. TraIT shared its work integrating OpenClinica into a Translational Molecular Medicine infrastructure (ppt), Aachen University presented its integration of medical imaging applications, and University of Cambridge’s RDCIT team unveiled its integration sophisticated pedigree and phenotyping capabilities to support clinical genomics research (pdf). We got to take deep dives into powerful GUIs for data import, client libraries for OC’s web services API, and data marts/reporting. That’s just a few. Many of these efforts are open source and are being shared freely–a phenomenon unique in the field of clinical research.

We have become a community that rapidly disseminates ideas and code while holding each other to rigorous standards of quality. We are building on a shared foundation of strong data provenance, audit trails, privacy protections, and GCP compliance. OC15 was a reminder of how openly and effectively our community collaborates, and how great we are at welcoming new participants. I left OC15 inspired and motivated by the participants’ passion and creativity.

Engineering OpenClinica’s Future

We recently introduced OpenClinica Participate™.

We believe all research participants—patients, clinicians, researchers, should have technology that meets the ‘anytime, anywhere’ expectations of a mobile, smartphone enabled world. Based on conversations with the OpenClinica community, many of you share this view as well. We are committed to making sure, at minimum, that OpenClinica’s patient engagement technology ‘just works’ in mobile, real world environments. Wherever possible, we will go beyond that and work to make the participant experience engaging, fun, and inspiring.

As transformational as these patient engagement capabilities can be, what we’ve been working on is about more than that. This is about a foundation for the future of the OpenClinica project.

EnketoAs I briefly pointed out in an earlier post, OpenClinica Participate forms are powered by the new enketo-express app that was built around the widely used enketo-core form engine (both available on GitHub).

OpenROSA_LogoOpenClinica will soon natively support the OpenRosa API, which will let you run Enketo, ODK Collect, or any of a number of OpenRosa-compliant data capture clients. Eventually, we envision the Enketo forms engine will replace the current CRF engine in the OpenClinica code base.

odk_medium_squareIf you’re not familiar with Enketo, ODK, or OpenRosa, here’s a primer. Most important is understanding there is a rich global ecosystem of technology, developers and users around the OpenRosa Xform standard. The resultant solutions have been battle tested in diverse health care and field-based data collection settings over many years. In keeping with the open source principles of flexibility and choice, aligning the OpenClinica ecosystem with this community will provide new features and options that you can use.

As my 5 year-old son has taught me when we watch Spider-Man cartoons, with great power comes great responsibility. So it is with open source software. Tapping in to the richness and variety of the OpenRosa community creates new possibilities, but it can add complexity too by expanding the options you have to choose from. OpenClinica is released under an open source license so that many developers can improve, combine, and share their code in a way that enhances quality, usability, and features, and we believe that this richness will drive the next cycle of innovation.

With this goal of better encouraging code contributions, the focus of the repositories and downloads will be easy-to-use open-source libraries: building blocks for developers to create their own OpenClinica-powered apps and modules.

If you are developing on the OpenClinica code base to add features or build custom solutions, you’ll have a greater ability to mix and match just the pieces you need, and to share back your improvements in a modular fashion. It will be much easier for developers to use the libraries and share their experience and contributions back with the community. We will gladly help out if you experience issues. Our own engineers will be able to focus more of their time on improving quality, usability, and functionality, rather than on packaging, testing, and supporting so many different environments. We hope to build a strong collaboration with the Enketo and OpenRosa communities that spawns new ideas and developments.

So try it out! Check out OpenClinica Participate or get started by hooking up OpenClinica with Enketo.

And need I say, you’ll certainly be able to learn more about these OpenClinica innovations at the upcoming OC15 conference in Amsterdam, May 31-June 1.

Reacting to #ResearchKit

OpenClinica_AppleRK Apple, Inc. has a remarkable ability to capture the world’s attention when announcing “the next big thing.” They have honed their well-known Reality Distortion Field skills for over 30 years. As the largest company in the world, and bellwether of the technology industry, Apple’s announcements are immediately recounted, opined, lionized, and criticized all across the Internet—sometimes with very limited real information on the new product itself. Of course, it helps to have their unmatched track record in actually delivering the next big thing.

ResearchKit has grabbed such attention. Maybe not as much as The Watch, but amongst the minority of us who pay attention to such things. And the reactions have been typically polarized—it’s either an “ethics quagmire” or “Apple fixing the world.”

But reality rarely presents an either-or proposition. I’ve written before on the need to use technology in simple, scalable ways to engage more participants in research and capture more data. Every form of engaging with patients and conducting research is fraught with potential for bias, bad data, and ethical dilemmas. Properly controlling these factors is difficult, and the current handling of these factors lead many to conclude that clinical research is overly “bloated and highly controlled”. There’s truth to that, but the fundamental need for good controls is real. As technology enables us to engage in new ways, how we implement such controls is likely to transform, perhaps unrecognizably so.

I don’t think Apple—or anybody—has these problems fully solved yet. And I expect we’re going to a see a vigorous debate in coming years between #bigdata and #cleandata that I hope will lead us to more of both. But ResearchKit, or at least the announcement thereof, is a game changer. Whether or not ResearchKit in its present form becomes a widely adopted platform, the impact was felt overnight: “11,000 iPhone owners signed up for a heart health study using Apple’s newly-announced ResearchKit in the first 24 hours… To get 10,000 people enrolled in a medical study normally, it would take a year and 50 medical centers around the country”. ResearchKit builds on momentum towards patient-centricity established in the last five years within pharma, NIH, online patient communities, mHealth, and health care, and uses Apple’s consumer clout to bring it to the attention of the average person on the street.

So let’s break down what we know about ResearchKit. Since this is a blog about OpenClinica, we’ll also share early thoughts on how we see OpenClinica, ResearchKit, and OpenClinica Participate fitting together.

It’s Open Source. Great move! We’ll learn more about what this means when the code is released next month.

The technical paper indicates it is a front-end software framework for research, and that they expect it to expand over time as modules are contributed by researchers. Through use of both platforms’ APIs, OpenClinica could serve as a powerful backend and ‘brain’ to ResearchKit.

It’s not clear if data goes through Apple’s servers on its way to a final destination. I also haven’t seen anything from Apple mentioning if it will be portable to other non-iOS platforms (which represent 80% of mobile device market share), though its open source nature would suggest that will be possible.

Surveys. Analogous in many ways to the forms module in OpenClinica Participate, it is a pre-built user interface for question and answer surveys. As somebody who’s worked in this realm for years, I know that this can mean a lot of things. What specific features are supported, how flexible is it, how easy is the build process? Perhaps most important, can it be ported to other mobile app platforms, or to the web?

Informed Consent. The need for fundamental ethical controls for for research conduct and data use are just as important in the virtual world as they are in the brick-and-mortar realm, and Informed Consent is a cornerstone. I’m glad to see ResearchKit taking this on; I don’t expect they have it 100% figured out, but their work with Sage Bionetworks, who has released an open toolkit on Participant Centered Consent, is a great sign.

Active Tasks. Maybe the most exciting component, here’s where ResearchKit takes advantage of the powerful sensors and hardware in the device and provides a way to build interactive tests and activities. In this way, I expect ResearchKit will be a great complementary/alternative frontend to OpenClinica Participate when specialized tests tied to specific, highly-calibrated devices are required.

In general, the promise is big: that technology will lower barriers in a way that leads to fundamental advances in our understanding of human health and breakthrough treatments. That we’ll go from data collected once every three months to once every second, and we’ll encounter–and solve–problems of selection bias, identity management, privacy, and more along the way. And that, according to John Wilbanks at Sage, “there’s coming a day when you’re not going to have an excuse to have a tiny cohort just because you chose not the use digital technologies to engage people.”

Introducing OpenClinica Participate

In clinical research, we all work towards better evidence-based, patient-centered health interventions. We all understand the importance of evidence. But how about patient-centered? We hear this phrase perhaps too often nowadays, but it’s more than just a buzzword. A patient-centered approach directs research toward questions that are important to patients so they can make more informed healthcare decisions. It measures the outcomes that are noticeable and important to patients, and produces results that help them weigh the value of healthcare.

At OpenClinica, we think increasing the patient-centeredness of research is vital. Industry, NIH, FDA, and the general public seem to agree, and furthermore share our view that technology can increase patient engagement. This can happen by designing highly accessible, mobile technology to:

  • Improve patient participation, motivation, and adherence
  • Increase ability to meet recruitment goals, budget, and completion timelines
  • Enable new designs that better target populations and/or more closely align with real-world use

HTCPhoneI’d like to introduce our upcoming product, OpenClinica Participate, a tool tightly integrated with OpenClinica for engaging patients and collecting data directly from study participants.

If you took our recent survey, you got a glimpse of what your forms for patient-reported outcomes could look like in OpenClinica Participate. Driven by a powerful forms engine based on proven open-source technology, the participant forms are simple, dynamic, mobile-focused, and platform-independent.

But it’s about a lot more than mobile-friendly forms. Patient expectations are rising while trial participation is shrinking. Clinical trials need to engage ‘Subjects’ as ‘Participants’ — by recruiting and retaining through real-time engagement and meeting the ‘anytime, anywhere’ expectations of a mobile, smartphone enabled world. It starts with an intuitive, action-oriented dashboard. Participants are greeted with a simple interface that motivates and focuses them on what they need to do today. The layout is responsive and knows whether you are using your phone, a tablet, or a traditional browser. Communication with the participant can occur through multiple channels — via the dashboard, through SMS, or via email, with options to help you make sure the right balance is struck between security and accessibility.

Participate_OCUILast, and perhaps most important, Participate is tightly integrated with the OpenClinica EDC platform. The Participate solution allows you to design your study and forms using the OpenClinica study build tools you already know, while seamlessly capturing all your clinical and participant-reported outcomes in a single database. You can build skip patterns, repeats, and other logic into your participant forms just as you do with traditional OpenClinica CRFs, using the same rules engine. You can use scheduling rules to identify the next time participant feedback is required. As data is submitted by study participants, their activities become part of the same audit trail that tracks what your clinical users do. The data they submit can immediately be reviewed and extracted along with CRF data from other sources.

Participate is extremely easy to adopt. As a modular add-on to your hosted OpenClinica Enterprise instance, it can be activated for any new study from within your study build screen. Forms are powered by the widely used open source enketo-express library and all editions of OpenClinica will support the widely-used OpenRosa API to let you run Enketo, ODK Collect, or any of a number of OpenRosa-compliant data capture clients. Participate utilizes a cloud-based Software-as-a-Service (SaaS) delivery model, so there is no costly and delay-inducing software deployment to worry about.


Visit the OpenClinica Participate Website


OpenClinica CRF Features – Everything But the Kitchen Sink

Whenever I teach case report form (CRF) design in the OpenClinica Central User Training class, the thought that always comes to mind is, “so many features, so little time.”  OpenClinica has so many features available for building your CRFs, that there is no way to cover every possibility within the limited timeframe of a training class. Fortunately, there are other ways of getting information out to users, so here I am to introduce you to additional features you may want to incorporate into your CRFs.

Some of these features use JQuery, a cross-platform JavaScript library designed to simplify scripting HTML. The JQuery code in the attached CRF template was tested on Firefox 35.0.1; it may function differently in different browsers or different languages. As with anything you set up for your study, if you decide to use any of the features presented here, be sure to test them in your test environment prior to using them in production.

Click to download: Kitchen Sink CRF and Associated Rules (zip file)

The attached CRF has 10 sections, and each section focuses on different feature sets. To see a list of all the Sections, click the drop-down arrow in the “Jump” box and then click the appropriate Section topic to see the features included within that topic.

CRF tabs

Throughout the CRF, each feature is labeled so you can easily recognize it and locate it in the CRF template. For example, “Left Item Text” is not a prompt you would ever include on your CRF, but it is the feature being demonstrated and is labeled as such so you can easily see where Left Item Text appears on any CRF you design. Each  Section of the CRF is listed below with a brief description as well as a screenshot so you can see how the features are represented.

1. Text

The Text Section illustrates various text features such as bold, italics, colors, and displaying images or a URL.  This section also covers the positioning of left item text, right item text, header, subheader, title, subtitle, and instruction text. The Instruction area of this section includes many text options that you can apply. If you would like to include blue text on your CRF, simply reference “Text color can be changed” in the Instructions cell of the Section worksheet of the attached CRF template and copy the formatting into your CRF.

CRF Text Tab
Click to enlarge

2. Response Options

This Section illustrates the various means of displaying responses on your CRF. It also provides additional features such as the “undo” button for deselecting a radio button, and an example of how to include a Visual Analog Scale. Again, simply reference the associated items in the Response Options section of the attached CRF template and copy the features you’d like into your CRF.

CRF Response Options
Click to enlarge

3. Layouts

The Layouts Section features different layout options such as column positions, horizontal vs. vertical checkboxes, and grid displays.

CRF Layouts
Click to enlarge

4. Required Items, Show/Hide, Decimals

This section demonstrates show and hide functionality, shows how real numbers (decimals) are displayed, and illustrates how required items are represented.

CRF Required Items
Click to enlarge

5. Validations This section demonstrates the various simple validations that are possible within the CRF template (less than, greater than, ranges, etc.). It also includes examples of some regular expressions.

CRF Validations
Click to enlarge

6. Calculations I

This is the first of two calculation sections. In this section, you’ll see examples of calculations and group calculations. You’ll have to upload the CRF, associate it with an event, and enter data to see the calculations in action.

CRF Calculations1
Click to enlarge

7. Calculations II

This second calculation section shows additional calculations and includes JQuery code for including a “calculate” button and for doing instant calculations. As above, you’ll have to upload the CRF, associate it with an event, and  enter data to see the calculations in action.

CRF Calculations2
Click to enlarge

8. Discrepancy Note*

The Discrepancy Note Section illustrates the effect of a Discrepancy Note Action Rule.

CRF Discrepancy Note
Click to enlarge

9. Show and Insert Actions*

This Section illustrates the effect of  Show and Insert Action Rules.

Before the rule is fired:                                            After the rule is fired:

CRF Action1                                CRF Action2
Click to enlarge

10. Email Action*

This Section illustrates the effect of an Email Action Rule.

CRF Email Action
Click to enlarge

*These last three Sections listed have Rules associated with them, and the Rules must be uploaded in order to experience the full functionality of these Sections. The Rules are also attached to this post.  If you want to use these Rules in your Study, be aware that you’ll have to edit them to reference the correct Object IDs for your Study.

So there you have it – one CRF, with everything but the kitchen sink. Check out the features and use them as you like. Just keep in mind that when designing CRFs, keeping it simple is always the best approach. There are times, however, when adding a little style to a form can help clarify things for data entry and may even help reduce discrepancies.

Happy designing!


Acknowledgements: Special thanks to Gerben Rienk Visser of Trial Data Solutions for many of these ideas, and to OpenClinica Application Support Engineer Jessica Gosselin for creating the Kitchen Sink CRF – we hope you find it useful!

Demystifying the Decode() Function

When I started learning to use OpenClinica, I was mystified by all of the things there were to learn. One year later, I continue to be surprised by the number of new skills and tricks I am discovering – whether in the form of existing functionality, new features (EventAction Rules!) or community contributions.

In May, I was putting together a workshop for OC14, OpenClinica’s Global Conference, on best practices for building studies in OpenClinica, and a colleague suggested I spend some time explaining all of the functions in our platform that can be used for calculations.

Alright, I thought, that should be easy. Functions for calculations in OpenClinica, while useful, are pretty simple. After reviewing the information found in the CRF Excel template for calculations, this is what I found:

Decode() screenshot

Sum()? Got it.

Min() and max()? Easy.

Stdev()? Fine.

Decode()? … wait, what?

A vague memory of our trainer’s explanation of the decode() function at OpenClinica’s Central User Training flashed through my mind. My guess is that there are users out there who don’t even know this little gem exists. Some of you may have seen it and simply dismissed it.

So what exactly is the decode() function?

The decode() function allows you to create an IF-THEN-ELSE type of statement. An item is compared to a list of search values, one by one. If the item matches a search value, then a corresponding result value is returned.

Here is your basic format:

decode(ComparatorItem, SearchVal1, ResultVal1, SearchVal2, ResultVal2, … DefaultValue)

The ComparatorItem is compared to each SearchVal in the list, one at a time:

  • The ComparatorItem is first compared to SearchVal1.
    • If the ComparatorItem = SearchVal1, return ResultVal1.
    • Otherwise, if ComparatorItem = SearchVal2, return Result2
    • And so on…
  • If none of the values in the Search List match the ComparatorItem, then the DefaultValue is returned.
    • The DefaultValue is optional, and can be omitted entirely.

The decode() function is probably best explained using an example. I will start by illustrating the general format of the function, and then move on to a few examples that may prove useful in your OpenClinica studies.

Let’s say users are entering a cardinal direction initial (i.e. N, S, E, W) and you want to decode the initial to the actual cardinal direction name (i.e. North, South, East, West). Your decode function would resemble the following:

decode(DirectionInitial, N, North, S, South, E, East, W, West, Unknown)

decode() function

Upon clicking save, the entry in the DirectionInitial Item will first be compared to “N” and if there is a match, “North” is returned. Otherwise, the DirectionInitial Item is compared to “E” and if there is a match, “East” is returned, and so on. If DirectionInitial Item does not match any of the options (N, S, E, or W), then “Unknown” will be returned.

Let’s look at a few examples that may be more applicable to your OpenClinica studies…


If you have a Vital Signs or Physical Exam CRF, you may be capturing the Subject’s temperature. In the case report form, there can be two options for temperature units (Celsius or Fahrenheit), but the statistician may be interested only in a final temperature in degrees Celsius. To please both your data entry person and your statistician, you can create a field to capture the Temperature, and then create another Units field to record either Celsius or Fahrenheit. The final Temperature item will contain the decode function, which would resemble the following:

decode(TemperatureUnits, Celsius, Temperature, Fahrenheit, ((Temperature-32)*(5/9)) )

If TemperatureUnits is equal to “Celsius,” then return the value recorded in the Temperature Item. Otherwise, if TemperatureUnits is equal to “Fahrenheit,” then convert the value recorded in the Temperature Item to Celsius.

decode() function example


Additionally, the decode() function is a great tool when scoring responses. For example, you may have an eligibility questionnaire with response options Yes, No, and NA, corresponding to response values 1, 0, and 99. You would like to count the number of ‘Yes’ responses. However, a simple sum() function will not work because if ‘NA’ is selected, ‘99’ will be included in the calculation. This can be solved by combining the decode() function with the sum() function.

First, you will need to determine the decode function for each item. In this case your function would be as follows:


If Yes is selected (value of 1), then 1 will be returned. If No is selected (value of 0) then 0 will be returned. If NA is selected (value of 99) then 0 will be returned.

Note: We only want to calculate the number of ‘Yes’ responses.

This can then be combined into a sum() function. If you have three eligibility items in your CRF, then your decode function would be as follows:

sum(decode(Item1, 1,1,0,0,99,0), decode(Item2, 1,1,0,0,99,0), decode(Item3, 1,1,0,0,99,0)

decode() function examples

Interested in seeing any of these examples in action?
You can download this CRF Excel template which includes each of the three above examples.

Also, if you found another useful way to use this function, feel free to comment and share your tips with us!

Video Demos: Printing Subject Casebooks, Blank Casebooks and Blank CRFs

We’re in the process of updating our documentation to include video demos of various OpenClinica features. Take a look at the video links below on printing subject casebooks and CRFs for a taste of what’s to come – and learn something cool in the process!

Printing a Subject Casebook is a great, though much overlooked feature of OpenClinica. First introduced in OpenClinica 3.2, this feature allows you to print a Subject’s entire casebook, including all the data entered for that Subject. You have various output formats and options to include the audit history and notes and discrepancies in the results. The Subject’s data, metadata, and provenance data – it’s all there, from start to finish. It’s easy to view online, and formatted beautifully for printing. Just for fun, we tossed in demos on printing blank casebooks and blank CRF pages as well.

Check out the videos below and…happy printing!