Building Forms in OpenClinica: Start Here

Modified on Fri, 20 Nov at 5:07 PM

 

ℹ️ Note: This page is for Data Managers responsible for study design.

 

In OpenClinica, a form is an electronic case report form (eCRF): the set of questions that collects data in a study. You build forms in Study Designer with Form Designer, OpenClinica's built-in, no-code form builder, or with the Form Template, an Excel spreadsheet in the XLSForm format. This article explains where forms fit in a study, which tool to use, and the steps from a first draft to live data entry.

 

Start here if you are new to OpenClinica, then follow the links to the article for the tool you choose.


 

Where forms fit in a study

 

In OpenClinica, you build a study in Study Designer. A study is organized into events, and each event contains the forms that are completed at that point. To add events and forms, see Events & Forms.

 

Use this table to see how the levels of a study fit together, from the whole study down to a single item.

LevelWhat it isExample
StudyThe protocol you are building, with its own Test and Production environments.ABC-123 Phase II
EventA point where data is collected, such as a study visit or time point. Visit Based events follow the study schedule. Common events, such as an adverse event log, can happen at any time. Either type can be marked Repeating.Screening, Week 4, Adverse Events
FormA case report form (CRF). The same form can be used in more than one event.Vital Signs
Item GroupA set of items stored together. Item Groups organize the data in extracts and reports, much like a dataset or domain, such as a Clinical Data Acquisition Standards Harmonization (CDASH) or Study Data Tabulation Model (SDTM) domain.VS
ItemOne question or data field on a form.Systolic blood pressure

 

For naming conventions for Item Names and OIDs, see Item Names and OIDs.


 

OpenClinica terms for familiar clinical concepts

 

If you have built CRFs in another electronic data capture (EDC) system, most concepts carry over under different names. Use this table to find the OpenClinica name for a term you already know.

If you know it asIn OpenClinica it isWhere to read more
CRF or eCRFFormWhere forms fit in a study
Visit or folderEventEvents & Forms
Log formRepeating Common EventEvents & Forms
Field, variable, or data pointItemItem Types and Appearance Reference
Variable nameItem NameBuild a Form in Form Designer
Variable label or short labelShort Display NameBuild a Form in Form Designer
Dataset, domain, or panelItem GroupBuild a Form in Form Designer
GroupLayout GroupBuild a Form in Form Designer
Codelist, codelist items, choice list, response set, field choices, controlled terminologyResponse options, choicesBuild a Form in Form Designer
Log form, log lines or repeating sectionRepeating groupBuild a Form in Form Designer
Skip logic or branching logic or dynamicsRelevant LogicForm Logic
Edit check or validation ruleValidation Criteria, ConstraintForm Logic
Derived variableCalculate itemForm Logic
ePRO (electronic patient-reported outcome) or eCOA (electronic clinical outcome assessment) formParticipant-facing form, eCOA formSection in this article: What happens when an edit check or required item fails?
CRF version or amendmentForm versionVersions and Changing Forms After Go-Live
Annotated CRF (aCRF)Annotated CRF, downloaded from Study RunnerBuild a Form with the Form Template
Cascading dropdownsCascading select, choice filteringBuild a Form with the Form Template
Study versionPublish History RevisionPublish History

 

Should I use Form Designer or the Form Template?

 

In OpenClinica, use Form Designer to build your forms. Form Designer is an editor inside OpenClinica where you add questions, choose settings from menus, and preview the form as you go. See Build a Form in Form Designer.

 

For the following features, you need to edit your form in the Form Template, an Excel spreadsheet in the XLSForm format with one row per question:

  • Hard edit checks, which block invalid values entirely.
  • Hard required items, which must be answered before the form can be marked complete.
  • Custom required messages, shown when a required question is left blank.
  • Cascading selects, which filter one question's choices based on an earlier answer.
  • Crossform references, which optimize the performance of a form that uses cross-form logic.
  • Shared choice lists, where several questions use the same list of response options.
  • Custom annotations on the annotated CRF.
  • Editing many items at once, or reviewing the whole form in a spreadsheet.
  • Bulk upload of form translations

 

To add these features, download your form as a Form Template, edit it in Excel, and upload it again. See Build a Form with the Form Template.


 

From first draft to live data entry

 

Follow these steps in OpenClinica to take a form from a first draft to live data entry.

  1. In Study Designer, add an event, then click + Add a form and enter the form's name. Click + to add the form.
  2. You can also add a form that already exists in the study or in the library. See Events & Forms.
  3. Build the form. On the form card, click Design to open Form Designer, or click Upload to load a completed Form Template. For a step-by-step example, see Build Your First Form in Form Designer or Build Your First Form with the Form Template.
  4. Save your work. In Form Designer, click Save Draft. An asterisk (*) on the button means that you have unsaved changes.
  5. Click Preview to check the form as a data entry user will see it.
  6. Add the form to the study. A Form Designer draft becomes a version when you choose Add to Study from the draft's menu. An uploaded template becomes a version as soon as it is uploaded.
  7. Click Publish and publish the study to the Test environment. See Publishing Your Study.
  8. Test data entry in Test, including your edit checks and skip logic.
  9. Fix any problems in Study Designer, and repeat publish and test steps, as necessary.
  10. Publish the study to Production.
⚠️ Warning: Watch out for overwriting form versions that have not yet been published to Production. When you add a Form Designer draft to the study, or upload a Form Template, with the same version number as an existing version, it replaces that version. Change the version number first, and discard drafts you no longer need. See Versions and Changing Forms After Go-Live.

 

Plan Item Names and Item Groups carefully before your first publish. Some changes, such as moving an item to a different Item Group or changing its data type, are not allowed in later versions. See Versions and Changing Forms After Go-Live.

✅ Tip: If you are not yet sure how to build your forms, build test forms or a test study first to settle the data types, Item Groups, and Item Names. Then build the final forms, so that their object identifiers (OIDs) are the ones you want.

 

What happens when an edit check or required item fails?

 

In OpenClinica, edit checks (Validation Criteria) and required items can be soft (the default) or hard (strict). Use this table to see what site staff see in each case.

CheckWhat site staff see
Validation, soft (default)The value is saved and the question is marked in red with your message. The user can update the data before a query is raised. If errors remain when the user closes or completes the form, OpenClinica offers to add a query automatically for each one.
Validation, hard (strict)The value is rejected with an Invalid Value pop-up. The user cannot mark the form complete until it is fixed.
Required, soft (default)The user can close the form without answering. If a required item is still unanswered when the user closes or completes the form, OpenClinica offers to add a query for each unanswered required item.
Required, hard (strict)An answer cannot be cleared, and the form cannot be marked complete until the item is answered.
ℹ️ Note: An item's checks are either all soft or all hard. One item cannot have a mix of hard and soft checks.

 

ℹ️ Note: Participants cannot override checks. On Participant-facing forms, such as ePRO or eCOA forms, every edit check and required item works as a hard check: an invalid value is rejected, and every required question must be answered before the form can be closed.

 

Hard checks can only be set up in the Form Template, by entering strict in the bind::oc:constraint-type or bind::oc:required-type column. See Build a Form with the Form Template.


 

Good practice before you start

 

Follow these practices when you plan forms in OpenClinica.

  • Keep forms to a manageable size. Long forms with a lot of logic load more slowly, especially on mobile devices. OpenClinica recommends no more than 100 to 200 items on a form, and no more than 50 on a participant-facing form.
  • Reuse what exists. Study admins can open the Library from the Study Designer header. To reuse a whole form, select it from the library in the + Add a form dialog. After the form is created, you can also add item groups or items from the library within Form Designer. See Using the Content Library.
  • Use one form in several events instead of making copies. A version uploaded to a form is applied to the same form in every event, as long as the form card in each event has the same title.
  • Decide your Item Names and Item Groups before the first publish, using only letters, numbers, and underscores. Item Names are case-sensitive, so choose one capitalization convention, such as all lowercase or all uppercase, and use it for every name. Then you don't have to remember how you capitalized a name when you refer to it in form logic.
✅ Tip: Keep the number of repeats in a repeating group under 10, because forms with many repeats load more slowly. You cannot limit how many repeats users add, but you can avoid designs that lead to dozens of repeats. To capture a long list of repeating entries, use a form in a repeating common event, with one event occurrence per entry, instead of a repeating group on a form in a non-repeating common event.

 

Key Terms

 

These are the main OpenClinica terms used in this article.

 

Form: a case report form (CRF), or electronic case report form (eCRF).

 

Event: a visit or time point in the study schedule, such as Screening or Week 4.

 

Item: one question or data field on a form.

 

Item Group: the dataset or domain an item is stored in, such as a CDASH or SDTM domain.

 

Form Designer: OpenClinica's built-in, no-code form builder.

 

Form Template: an Excel spreadsheet in the XLSForm format that defines a form.

 

Query: a data clarification request on a value.

 

Participant-facing form: a form completed by the participant, such as an ePRO or eCOA form.


 

Frequently Asked Questions

 

What is the difference between Form Designer and the Form Template in OpenClinica?

 

In OpenClinica, Form Designer is a no-code editor where you add questions, choose settings from menus, and preview the form as you build it. The Form Template is an Excel spreadsheet in the XLSForm format that you upload. Use Form Designer for most forms, and the Form Template for features such as hard edit checks and cascading selects.

 

Can I convert a Form Designer form into a Form Template in OpenClinica?

 

Yes. In OpenClinica Study Designer, open the menu of a form version and choose Download. You get a zip file with the Form Template spreadsheet and any media files; a draft's Download option gives the spreadsheet only. Edit the spreadsheet in Excel to add Form Template features, such as hard edit checks, then upload it to the form again.

 

What is the difference between a soft and a hard edit check in OpenClinica?

 

In OpenClinica, a soft edit check is the default: the value is saved, the question is marked in red, and staff can add a query to explain it. A hard edit check rejects the value with an Invalid Value message, and the form cannot be marked complete until it is fixed. You set up hard checks in the Form Template.

 

Can I use the same eCRF in more than one event in OpenClinica?

 

Yes. In OpenClinica Study Designer, add the existing form to each event instead of making copies. A version uploaded to the form is applied to the same form in every event, so you keep one form definition for the whole study. To add a form to an event, or to copy a form from the library, see Events & Forms.

 

How many questions should an eCRF have in OpenClinica?

 

OpenClinica recommends no more than 100 to 200 items on a form, and no more than 50 items on a participant-facing form, such as an ePRO form. Each item is one question or data field. Long forms with a lot of logic load more slowly in OpenClinica, especially on mobile devices, so keep forms to a manageable size.

 

Can participants override an edit check on an ePRO form in OpenClinica?

 

No. In OpenClinica, participants cannot override checks on Participant-facing forms, such as ePRO or eCOA forms. Every edit check and required item works as a hard check: an invalid value is rejected, and every required question must be answered before the participant can close the form. Site staff can add a query to a soft check instead.


 

Articles in this series

 

These OpenClinica articles cover each part of building forms.


Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article