ℹ️ This page is for Data Managers responsible for study design.
In OpenClinica, the Form Template is an Excel spreadsheet in the XLSForm format that defines an electronic case report form (eCRF): a settings sheet for the whole form, a survey sheet with one row per question, and a choices sheet with the response options. You fill it in and upload it to Study Designer. This reference describes every sheet and column, and how to use the Form Template's advanced features, such as hard edit checks and cascading selects. Once you fill in the Form Template, it is called a Form Definition file: the completed spreadsheet that you upload to OpenClinica.
If you are not sure which tool to use, see Building Forms in OpenClinica: Start Here. New to the Form Template? Start with Build Your First Form with the Form Template, which walks you through building a simple form from start to finish.
Get the Template
In OpenClinica, download a blank Form Template, or download an existing form as a Form Template, from Study Designer.
- Blank template: click Form Template in the Study Designer header bar.
- An existing form: on the form in Study Designer, open a version's menu and choose Download. You get a zip file containing the spreadsheet and any media files. A draft's Download option gives the spreadsheet only.
The template opens in Excel and most other spreadsheet programs. Hover over a column heading to see help for that column. The last six sheets contain worked examples of advanced features: Cross-Form Examples, Custom Annotation Examples, Contact Info Examples, eConsent Examples, Hard Checks Examples, and Offline Forms Examples.
What sheets does the Form Template have?
The OpenClinica Form Template has these sheets. Use this table to find where each part of the form goes.
| Sheet | What it holds |
|---|---|
| settings | One row describing the whole form: title, version, style, and other form-level settings. |
| survey | One row per question, group, or note, in the order they appear on the form. |
| choices | The response options for Select One and Select Multiple questions, one row per option. |
| Cross-Form Examples, Custom Annotation Examples, Contact Info Examples, eConsent Examples, Hard Checks Examples, Offline Forms Examples | Reference examples. OpenClinica ignores these sheets. |
Settings Sheet Columns
The settings sheet of the OpenClinica Form Template has one row of values, in row 2. Use this table to see which columns are required and what each one does.
| Column | Required? | What it does | Values and rules |
|---|---|---|---|
| form_title | Optional | The form's title, shown at the top of the data entry page. | Letters, numbers, spaces, and special characters are allowed. |
| form_id | Optional | Not used. OpenClinica replaces this value with its own identifier when the form is uploaded. | If you enter a value, use letters, numbers, and underscores, with no spaces. |
| version | Required | Identifies this version of the form. | If blank, the upload fails with: The "version" column in the "settings" worksheet must have a value in row 2. Use the same value to overwrite a version in Test, or a new value to create a new version. |
| style | Optional | The form layout. | Blank, pages, theme-grid, or theme-grid pages. See Form Styles. |
| crossform_references | Optional | Limits which events a form's cross-form logic loads. | Comma-separated Event OIDs (object identifiers), and current_event for the current event. Leave blank if the form has no cross-form logic. See Crossform References. |
| namespaces | Required, already filled in | Technical setting. | Hidden by default. Do not change. The value is: oc="http://openclinica.org/xforms" , OpenClinica="http://openclinica.com/odm" |
| default_language | Optional | The form's primary language: the language of the label, hint, and message columns that have no language name. | Use a name and a code in parentheses, such as English (en). If the code is missing, the upload fails. If left blank, OpenClinica uses the first language column on the survey sheet as the primary language. See Translations. This column is not in the blank template. Add it manually when the form uses translations. |
Form Styles
The style column sets how the form is laid out. Use this table to choose the style that fits who completes the form.
| Value | Layout | How the form looks | Best for |
|---|---|---|---|
| Blank | Simple, single page | Each question is on its own row, all on one scrolling page. | Short forms and Participant-facing forms. |
| pages | Simple, multiple pages | Each question is on its own row. Each question, or each group of questions, appears on its own page. | Participant surveys, where one question at a time reduces mistakes. |
| theme-grid | Grid, single page | Questions in a group can sit side by side in columns. All groups appear on one page. | Site-staff forms with many short fields, such as vital signs. |
| theme-grid pages | Grid, multiple pages | Same as theme-grid, but each group appears on its own page. | Long site-staff forms divided into sections. |
Survey Sheet Columns
Each row on the survey sheet of the OpenClinica Form Template is one question, group, or note. Most forms need only the type, name, label, bind::oc:itemgroup, and required columns. Use this table to look up any column. The table lists the columns in the order they appear in the blank template. The last eight columns are not in the blank template; add them yourself when you need them.
| Column | What it does | Values and rules |
|---|---|---|
| type | The item type. | See Item Types and Appearance Reference. |
| name | The item's internal name, like a variable name. | Required. Must be unique within the form: no two items or groups on the same form can share a name. Letters, numbers, and underscores; must begin with a letter or underscore; up to 40 characters for new items. |
| label | The question text. | Supports simple formatting, such as bold and italics. See Format Question Text. |
| bind::oc:itemgroup | The Item Group the item belongs to: the dataset or domain it is stored in, such as a Clinical Data Acquisition Standards Harmonization (CDASH) domain. | Required for every item that collects data. Letters, numbers, and underscores, not starting with a number. All items in a repeating group must use the same value, and no item outside that group can use it. Leave blank on group rows and notes. |
| hint | Help text shown in italics under the question. | Optional. |
| appearance | How the item is displayed, and its width on Grid forms. | See Item Types and Appearance Reference. |
| bind::oc:briefdescription | Short display name for tables and listings. | Optional. Up to 40 characters. |
| bind::oc:description | Longer item definition for metadata and extracts. | Optional. Up to 3,999 characters. |
| relevant | Skip logic, also called branching logic: the item shows only when the expression is true. | See Form Logic. |
| required | Whether an answer is required. | yes, or an expression for a conditionally required item. |
| required_message | Message shown when a required item is empty. | Optional. Default message: This field is required. |
| constraint | Edit check, also called a validation rule: the value is valid only when the expression is true. | See Form Logic. |
| constraint_message | Message shown when the constraint fails. | Optional. Default message: Value not allowed. |
| default | A value filled in when the form first opens. | A constant or an expression. |
| calculation | An expression that computes the item's value. | Any item other than type calculate that has a calculation must be readonly, unless it has a trigger. |
| trigger | Recalculates only when the named item changes. | An item reference, such as ${weight}. |
| readonly | Users can see but not change the value. | yes, or blank. Not allowed on calculate items. |
| image | An image shown with the question, or the SVG file for an image map. | The file name. Upload the file with the spreadsheet. |
| repeat_count | How many times a repeating group repeats. | Only on begin repeat rows. If the count goes down, the last repeats are removed. |
| bind::oc:external | Fills the item from data outside the form. | clinicaldata (calculate items only), contactdata, identifier, or signature. Items with this column set cannot have an item group or descriptions. |
| bind::oc:required-type | Makes the requirement hard. | Only allowed on required items. Enter strict for a hard requirement: the answer cannot be cleared, and the form cannot be marked complete until the item is answered. Leave blank for a soft requirement: the user can close the form without answering, and OpenClinica offers to add a query for each unanswered required item when the form is marked complete. Column must be manually added. |
| bind::oc:constraint-type | Makes the edit check hard. | Only allowed on items with a constraint. Enter strict for a hard edit check: a value that fails the check is rejected, and the user cannot keep it by adding a query. Leave blank for a soft edit check: the value is saved and flagged, and the user can explain it with a query. Column must be manually added. |
| choice_filter | Filters the choices shown based on other form responses. | Column must be manually added. See the Cascading Selects section in this article. |
| instance::oc:contactdata | The type of personally identifiable information (PII) a contactdata item shows. | firstname, middlename, lastname, email, mobilenumber, streetaddress1, streetaddress2, city, state, country, postalcode, fulldob (date items only), secondaryid, hospitalnumber. Column must be manually added. Each value once per form. |
| instance::oc:identifier | Used only on Offline Capable forms, for the Participant ID item that adds offline data to a specific participant's record. See Using Offline Data Capture. | participantid Column must be manually added. |
| media::audio | An audio file played with the question. | The file name. Upload the file with the spreadsheet. Column must be manually added. |
| media::video | A video shown with the question. | The file name. Upload the file with the spreadsheet. Column must be manually added. |
| bind::oc:oc_annotation_LABEL | A custom annotation shown on the annotated CRF. LABEL is the annotation's name. | Column must be manually added. See the Custom Annotations section in this article. |
guidance_hint | Extra guidance text for an item. | Column must be manually added. |
Format Question Text
You can format text in the label and hint columns, and in the label column of the choices sheet. Use this table to see what to type for each format.
| Type this | Users see |
|---|---|
| Enter weight in *kilograms* | Enter weight in kilograms, with kilograms in italics. |
| Do **not** include weekends | Do not include weekends, with not in bold. |
| ***Stop*** if no consent | Stop if no consent, with Stop in bold italics. |
| # Medical History | Medical History as a large heading. Use one to six # characters; # is the largest. |
| <span style="color:#ff0000">Required</span> | Required in red. |
For more on question text and display options, see Item Types and Appearance Reference.
Choices Sheet Columns
Each row on the choices sheet of the OpenClinica Form Template is one response option. Use this table to fill in each column.
| Column | What it does | Values and rules |
|---|---|---|
| list_name | The name of the list. Every option in the same list uses the same list_name. | Letters, numbers, and underscores. Referenced from the survey sheet's type column, such as select_one yn. |
| label | The text users see. | Required for every option. |
| name | The value stored in the database, such as 1 for Yes. | Unique within the list. |
| image | An image shown with the option, such as a face on a pain scale. | The file name. Upload the file with the spreadsheet. |
| filter columns | Used by cascading selects. | Any column name, such as filter1. Column must be manually added. See the Cascading Selects section in this article. |
Advanced Features
These OpenClinica features are set up in the Form Template spreadsheet.
Hard Edit Checks and Hard Required Items
By default, edit checks and required items are soft for site staff: users can keep a value that fails a check, and explain it with a query (a data clarification request). Enter strict in bind::oc:constraint-type or bind::oc:required-type to make the check hard. These two columns are not in the blank template; add them to the survey sheet manually.
- Hard edit check: a value that fails the constraint is rejected with an Invalid Value message and the field returns to its previous value. A query cannot override it, and the form cannot be marked complete until it is fixed.
- Hard required item: an answer cannot be cleared, and the form cannot be marked complete until the item is answered.
Cascading Selects
Cascading selects filter one question's choices based on an earlier answer, for example Type of cancer, then Subtype.
- On the choices sheet, add a filter column, such as filter1. For each option in the dependent list, enter the value of the earlier answer it belongs to.
- On the survey sheet, add a choice_filter column.
- In the dependent question's row, enter an expression that compares the filter column with the earlier answer, such as filter1 = ${cancer_type}.
Example choices sheet:
| list_name | name | label | filter1 |
|---|---|---|---|
| cancer_type | breast | Breast | |
| cancer_type | lung | Lung | |
| cancer_subtype | ductal | Ductal carcinoma | breast |
| cancer_subtype | lobular | Lobular carcinoma | breast |
| cancer_subtype | nsclc | Non-small cell lung cancer | lung |
| cancer_subtype | sclc | Small cell lung cancer | lung |
Example survey sheet (other columns not shown):
| type | name | label | choice_filter |
|---|---|---|---|
| select_one cancer_type | cancer_type | Type of cancer | |
| select_one cancer_subtype | cancer_subtype | Subtype | filter1 = ${cancer_type} |
When the user answers Lung to Type of cancer, the Subtype question shows only Non-small cell lung cancer and Small cell lung cancer.
Crossform References
Forms with cross-form logic load the participant's data from other events. By default, data from every event is loaded, which can slow the form down. In the settings sheet's crossform_references column, list only the events the logic needs, as Event OIDs separated by commas. Add current_event for the event the form is in.
Example: SE_BASELINE,SE_VISIT2,current_event
If any event OID in the list is invalid, OpenClinica ignores the whole list and loads data from every event. The logic still works, but the form loads more slowly.
Use these rules to decide what to list:
- Logic that reads from another event: list that event's OID. Every occurrence of that event is then available to the logic.
- Logic that reads only from the current occurrence of the event the form is in: list current_event. This loads less than the event's OID, which makes every occurrence available. If the event has only one occurrence, current_event and the event's OID work the same way.
- Logic that uses a value from the current event, such as its repeat key or an answer on another form in the same event, to read from a different event: list both, for example SE_VISIT2,current_event. List everything the expression reads from the participant's record, except the values on the form that is open.
- Logic that reads only the username or user role: list current_event. This user information is always available, so listing the smallest scope keeps the load as small as possible.
Custom Annotations
Custom annotations add your own notes to the annotated case report form (aCRF), alongside the standard annotations. They have no other effect. This column is not in the blank template, so add it manually. Add a survey column named bind::oc:oc_annotation_LABEL, where LABEL is the annotation's name, and enter the annotation text in each item's row. For example, a column named bind::oc:oc_annotation_Data_Manager_Comment with the text "Reused on follow-up form" shows as [Data Manager Comment: Reused on follow-up form].
To see the annotations, download the annotated CRF: open the Manage Case Report Forms (CRFs) page in Study Runner and click Download Annotated CRF next to the form version.
Guidance Hints
A guidance_hint column adds extra guidance text to an item.
Long Choice Lists from a CSV File
If a list is too long for the choices sheet, keep it in a comma-separated values (CSV) file. On the survey sheet, enter select_one_from_file filename.csv in the type column, and upload the CSV with the spreadsheet. Use the minimal autocomplete appearance so users can type to filter the list. To change the list after the form is published to Production, upload the updated CSV with a new form version.
Image Maps
An image map lets users answer by clicking part of a picture, such as a region on a body diagram.
- In the scalable vector graphics (SVG) file, give each selectable region an id, such as id="left_arm".
- On the choices sheet, add one option per region. Use the region's id as the option name, and the text you want on hover as the label.
- On the survey sheet, set the item's type to select_one (or select_multiple) with that list, its appearance to image-map, and its image to the SVG file name.
- Upload the spreadsheet and the SVG file together.
Translations
Language columns are not in the blank template, so add them manually. Add a column for each language, named with the column, two colons, the language name, and its code in parentheses, such as label::Spanish (es) or hint::Spanish (es). You can translate these columns:
- survey sheet: label, hint, constraint_message, and required_message
- choices sheet: label and image
Any text left blank is blank for users of that language. The form title cannot be translated.
For how OpenClinica chooses the language each user sees, see Language Support.
Common Upload Errors
If a Form Template upload fails, OpenClinica shows a message for each problem it finds. For what each message means and how to fix it, see Common Form Template Upload Errors.
Key Terms
These are the main OpenClinica terms used in this article.
Form Template: an Excel spreadsheet in the XLSForm format that defines a form.
Form Definition file: a filled-in Form Template, ready to upload to OpenClinica.
Item Name: the variable name stored in data extracts, entered in the survey sheet's name column.
Item Group: the dataset or domain an item is stored in, entered in the bind::oc:itemgroup column.
strict: the value that makes an edit check or required item a hard check, so a query cannot override it.
Cascading select: a question whose choices are filtered by an earlier answer.
Crossform references: a list of the events that cross-form logic needs, which speeds up loading.
Frequently Asked Questions
Is the OpenClinica Form Template the same as XLSForm?
The OpenClinica Form Template is an Excel spreadsheet in the XLSForm format, with OpenClinica columns added, such as bind::oc:itemgroup and bind::oc:constraint-type. Not every standard XLSForm feature is supported: uploading a template with the geopoint, geotrace, geoshape, barcode, time, or dateTime type fails with an unsupported data type error.
How do I make a hard edit check in the OpenClinica Form Template?
In the OpenClinica Form Template, enter the edit check in the constraint column, then add a bind::oc:constraint-type column. Enter strict in the bind::oc:constraint-type column of the same row. A value that fails the check is rejected with an Invalid Value message, and a query cannot override it. Hard edit checks cannot be set up in Form Designer.
How do I fix "Element must be assigned to an Item Group" in OpenClinica?
This OpenClinica Form Template upload error means a question that collects data has no Item Group. Enter a value, such as VS, in that row's bind::oc:itemgroup column and upload again. Use letters, numbers, and underscores, not starting with a number. Leave the column blank only on group rows and notes.
Why does my OpenClinica Form Template upload fail with "invalid language labels"?
In the OpenClinica Form Template, every language column header and the default_language setting must name a language with a code in parentheses, such as label::Spanish (es) or English (en). If any one has a name without a code, the upload fails. Add the missing codes and upload the spreadsheet again.
Related Articles
These OpenClinica articles cover the rest of the form-building process.
- Building Forms in OpenClinica: Start Here: where forms fit in a study and which tool to use.
- Build Your First Form with the Form Template: a step-by-step tutorial that builds a Vital Signs form in Excel.
- Common Form Template Upload Errors: what each upload error message means and how to fix it.
- Build a Form in Form Designer: the no-code editor alternative.
- Item Types and Appearance Reference: every question type and display option, with Form Template values.
- Versions and Changing Forms After Go-Live: form versions and the changes allowed after a study goes live.
- Form Logic: skip logic, edit checks, required logic, and calculations.
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article