Using the Form Template - OpenClinica Reference Guide

The form template is a .xls spreadsheet (compatible with most modern spreadsheet programs: Microsoft Word, Open Office, Numbers, etc.) that can be used to create form definitions in OpenClinica. It is best practice to download the latest form template from OpenClinica (see steps below). The form template can also be found here: form_template.

Note: Form creation is usually easiest using the drag-and-drop Form Designer, but sometimes it is helpful to use the Form Template for forms with more form logic or specific features. See Using Form Designer for information on Form Designer.
As a general rule, the more complicated the form, and its logic, the more likely you’ll have to use Form Template. While Form Designer accommodates skip logic (on relevant fields) and validation criteria (constraints), it does not support features such as cascading selects, hard edit checks, etc.

Definitions

Original Form Template: The blank spreadsheet file downloaded from OpenClinica.
Form Template: A pre-formatted spreadsheet downloaded from OpenClinica. This could be blank for a new form, or a form you download to edit or copy an exiting form that would already rows filled in.
Form Definition File: A completed spreadsheet uploaded, or ready to load, into OpenClinica.

Good Advice: Keep in mind that loading times for end-users are affected by the number of items on the form and the amount of form logic you use, OpenClinica recommends having no more than 100-200 items on a form and no more than 50 items on a Participate form, specifically when it is likely to be accessed from a mobile device.

The XLS Spreadsheet Contains Five Sheets:

Settings
Choices
Survey
Cross-Checking Examples
Other Examples

The first three are the primary pages (Settings, Choices, and Survey sheets) you will utilize.

Quick-Start Guide

To Download the Form Template:

Click the Download Form Template button in the header bar of Study Designer.

To Create the Form:

Open the downloaded template.
Enter a name for the form in the form_title column.
Create a unique form id in the column form_id that will be used to identify your form internally (i.e., will not be visible to end-users).

To Add an Item to the Form:

Click the survey tab to move to the survey spreadsheet.
Enter the type of item you want in the type column (For example, text, integer, date, etc.).
Enter the item text in the label column.
Enter a unique alphanumeric string for the item in the name column.
Enter text into the label column that will be displayed on the form as the question text.

If your item type is select_one or select_multiple, you must enter choices.

To Enter Choices for Select One or Select Multiple items:

Click the choices tab in the Form Template spreadsheet.
Enter the text for the option in the label column.
Enter a unique alphanumeric string for the option in the name column. Do not include commas, spaces, or other non-alphanumeric characters in the choice name.
Enter the unique id you entered for the question on the Survey tab (in the name column) to link options in the list_name column.
Continue to add options as needed (by repeating steps 2-4).
Click the survey tab in the Form Template spreadsheet.
In the type column next to select_one or select_multiple, enter the list name from the choices sheet (For example, if the list name is YN, the type cell contents would be select_one YN)

Important: The spacing and underscores in select_one [listname] and select_multiple [listname] need to be exact.

To Create a Group of Items:

Click the survey tab in the form template.
Enter begin group in the type column at the top of all the items you want to put into a group.
Enter end group in the type column at the bottom of all of the items you want to put into a group.
In the bind::oc:itemgroup column, across from begin group and end group, enter an internal name for the group of items.

Note: If you want to make a repeating group, instead of begin group and end group, enter begin repeat and end repeat.

Best Practice: In the bind::oc:itemgroup column, you are using repeating groups, which must be kept separate, it is ideal to keep items in the same group. These groups do not have to correspond to the begin/end groups. Keeping items in the same group allows for better data visualization in Insight because participant data is displayed on tables by item group, not by form.

To Upload a Form Template in Study Designer:

Click the name of the Form in Study Designer.
Click the Upload button.
Select the Form Template/Form Definition File you want to upload for that given form.
Click the open button in the dialogue box.

Note: You can download a blank copy of the form template from within study designer (as shown above), or you can download a Form Definition File for several existing forms in the Form Library (CDASH) and modify it to suit your needs.

For helpful hints in completing the form template, hover your mouse over a column heading to read how its used, and be sure to read the last two worksheets (Cross-Checking Examples and Other Examples) for documentation on creating edit checks and other advanced template features.

Form Template Exclusive Features

Annotated CRFs

Annotated CRFs are useful for statisticians because they specify where in the system the data was taken from. For example, an annotated CRF might specify the dataset where the data exists.
Annotated CRFs are also a requirement for FDA data submissions and CDISC Standards.

Cascading Selects

Cascading Selects (or Choice Filters) are a way of organizing hierarchical questions and filtering possible choices based on the prior selection. For Example, You Could Use Cascading Selects for the Following Set of Questions:

Type of Cancer
Subtype of Cancer
Specific Cancer

When a participant responds to Type of Cancer, the choices listed for Subtype of Cancer are filtered based on that response. The responses for Specific Cancer will then by filtered by the Subtype of Cancer response. Responses for select_one and select_multiple questions can be filtered based on values of any items on the form.

To Add a Cascading Select:

On the choices sheet, create columns for each filter you will use. For example, filter1 and filter2.
Enter a value in a filter column to assign the choice in that row to a specific filter group. For example, filter1 might have 4 filter groups that contain different sets of choices. Use the numbers 1 through 4 to assign each choice to a distinct filter group.
On the survey sheet, add a choice_filter column.
In the choice_filter column, enter an expression for an item that must be true for a choice for that item in order to show that choice. Filter values are referred to by the title of the filter column. For example, filter1 = ${cascade1} would show a choice only if the value for that choice in column filter1 were equal to the value of item cascade1. If item cascade1 were 1, only choices with filter1 = 1 would be displayed on the form.

Crossform References

Crossform References optimize loading forms by specifying the events or forms that the system needs to reference for cross-checks. Instead of the system loading all of a participant’s information, it only loads the information necessary for the cross-check.

Add the necessary OIDs in the crossform_references column of the settings sheet. See “Crossform References” below.

Referencing Long Lists

The choices worksheet of the form template restricts the combination of labels and names to a maximum of 4,000 characters. If you have a long list of choices to reference in a form, you can maintain that list in a separate CSV file where the number of characters is not restricted.

Best Practice: OpenClinica recommends that any items that reference long lists are defined with minimal autocomplete in the appearance column. In the form, this filters list choices in the dropdown list as you type.

E.g. instead of uploading a normal Form Definition File with a medications list, the medications were entered into a separate spreadsheet and saved as a CSV file named medication_list.csv. This file has more than 14,000 rows of entries.

Note: To reflect any changes in the list of choices made in the .csv file, you must upload it again. If this occurs on a study that has been published to the Production environment, you must also update the version of the form on the settings page of the Form Definition File.

Repeat Count

If you enter begin repeat and end repeat in the type column, you can use the repeat_count column to specify the number of times the group of questions can be answered. If you specify the number of repeats available to the user, they cannot add or remove any of the repeating groups.

To Add a Repeat Count:

Click the survey tab in the form template.
Add a repeat_count column.
In the repeat_count column, across from begin_repeat and end_repeat, enter the number of repeats to allow.

Select_One From File

You can upload a CSV file with the Form Template for items that have a long list of choices that you can create with various external spreadsheet programs (consult the program’s documentation for assistance with this step).

To Reference the CSV File in the Form Template:

In the form template, on the survey sheet, enter select_one_from_file filename.csv in the type column. For example, if the name of the CSV file is painlocation, enter select_one_from_file painlocation.csv.

To Upload a Form Template with a CSV File:

In Study Designer, upload the Form Template and the CSV file at the same time by selecting both files (PC: ctrl+click; Mac: cmd+click) and clicking open.

Languages and Translations

You can add multiple languages to your form by adding language columns to your XLS spreadsheet.

If you want French to be your default language, change the title in the label column to label::French (fr). Then, in the default_language column on the Settings tab, enter French (fr). You can define several other languages by adding columns in the choices and/or survey sheet, each with the title label::language.

You can define languages for items, including the following:

Survey Sheet:

label
hint
constraint_message
required_message
image (file name)
audio (file name)
video (file name)

Choices Sheet:

label
image (file name)

Settings Sheet:

default_language

Enter translated text for every field you want to be translated; otherwise, that field will only use the default language.

Note: The only text-based item you cannot define language(s) for is the Form Title.

If no default language is defined on the form and the user’s web browser language setting is a valid option for the form, the form initially loads using the user’s browser language selection. If there are additional languages for the form, they will be available to change between in the dropdown menu as needed.

It is best practice to always have a default language defined, even though it is not specifically required.

System-Level Language Packs:

The Study Runner interface (outside of your eCRFs) can also be displayed in multiple languages that have already been professionally translated. To have OpenClinica enable a language pack for your study, please reach out to your Customer Success Manager, or contact support.

The form’s user interface (buttons and text set by OpenClinica rather than configured on the form template) will only display in supported languages. Other languages will only display the text that was configured on the form template for that language and will otherwise display the user interface in English (en). For example, when using French (fr) as a language on the Form Template, the user interface remains in English (Validate, Return to Beginning, Go to End, etc.).

When a system-level language pack is installed for your study, the language presented to your users is based on their web-browser’s settings.

Limitations with Study Runner Translations (set at the Study level by OpenClinica):

Areas of Study Runner that display an Item Label or Brief Description (including custom columns in the Participant Matrix, Queries Table, and PDP common events tables, Data Review Table columns, and Item-Level SDV rows) will always display the Item Label or Brief Description only in the default language, regardless of the language a user is utilizing in a multi-language study.
Areas of Study Runner that display single select or multi-select item values as choice labels (same component list as the above bullet plus the Audit Log) will always display the choice labels in the same language regardless of the user’s browser’s language settings.

Image Maps

OpenClinica also has a feature that allows you to upload vector graphics (SVG images) and select areas in the image that correspond to responses to a query. Instead of selecting from a drop-down list, you can select an area in the image. For example, instead of looking through a list of potential pain locations to find the correct one, users can select the location on a picture of the human body.

To Set Up Image Links in an SVG File:

1. Open the spreadsheet for your form.
2. On the Survey tab, add a row with the following values in the specified columns:
  1. Type: Enter select_one listname, for example, select_one armregion
  2. Appearance: Enter image-map.
  3. Image: Enter the name of the SVG file you are using as your image map, for example, armregions.svg
3. In the Choices tab, add rows with the following values in the specified columns:
  1. List_name: Enter a name for your list of codes in each cell for the number of regions in your image.
  2. Label: Enter labels for each region you want to be able to select. These are the labels you see when you hover over a region in the image.
  3. Name: Enter an ID for each label. These are the path IDs you will use in Step 4.

1. Open the SVG file in a text editor. Next to <path, for each region, enter a path id you chose in step 3c, for example, id=path10 When you have added an id for each path, save the file.

In OpenClinica, click +Add a form on the event to which you want to add the image.
Enter a name for the form.
Select the form card, and click Upload.
Select BOTH the XLS file AND the SVG file at the same time, and click Open.
Once the image has loaded, click Preview. Hover over regions to view labels or click on a region to select it.

Custom Annotations

This feature allows custom annotations to appear alongside standard item annotations in Annotated Form and Annotated Casebook PDFs. Standard annotations are automatically included for all item configurations defined on the survey worksheet. Custom annotations can be added to items as needed. Custom annotations do not have any effect in OpenClinica other than to appear on Annotated Form and Annotated Casebook PDFs.

If you want to add a custom annotation, add a column to the Survey tab and enter the column heading text as “bind::oc:oc_annotation_CUSTOMANNOTATIONLABEL“; where “CUSTOMANNOTATIONLABEL” is the text you would like to be displayed on the form as the custom annotation label. It can only contain uppercase letters, lowercase letters, digits, hyphens, and underscores, but the first character must be a letter or digit. Underscores will be converted to spaces for display on the annotated form.

The text entered for a row in the bind::oc:oc_annotation_CUSTOMANNOTATIONLABEL will be the custom annotation text on the Annotated Form and Casebook. There is no restriction on the characters that can be used in custom annotation text.

Ex: If a column is added called “bind::oc:oc_annotation_Data_Manager_Comment” and an item has “Reused on follow-up form” in that column, then that item will have the following annotation “[Data Manager Comment: Reused on follow-up form]“

Each custom annotation can have text defined per item or be left unused per item as needed. If a custom annotation is not used for a particular item, the custom annotation will not be displayed on the annotated form for that item.

Multiple custom item annotations can be defined within a form definition spreadsheet. They will be displayed on the Annotated Form and Annotated Casebook PDFs in the order the custom annotation columns are listed on the survey worksheet.

Form Template Fields with No Form Designer Equivalent

Due to the nature of a form template, some fields will only exist in one or the other. Here are all the form template fields that don’t exist inside the form designer and any special instructions.

Namespace

The value in this field should remain as it is. If you inadvertently delete the value, it should be as follows (the quotes and spaces are required):

oc=”http://openclinica.org/xforms”
OpenClinica=”http://openclinica.com/odm”

Crossform References

As noted earlier you can use this column to decrease the form’s loading time by specifying a list of events to be used in the form’s cross-form logic. If the form does not use cross-form logic, then this column should be left blank in which case this column will have no effect.

If the form uses cross-form logic, and this is left blank, then all data for a given participant will be available for the form to access. This will ensure that any logic will be able to pull in the desired values, but it will add to the time it takes to open the form.

To improve form performance, you can include a comma-separated list of Event OIDs. Only data from these events will be accessible to the form’s cross-form logic. This can improve form loading times significantly. You must, however, ensure that all events referenced in the cross-form logic are listed here or the desired values will not be pulled in as expected. You can also include “current_event” in the list. That will allow the form to access data from the event occurrence it is in. This is useful for forms that are used in multiple events. It allows the form to access data that is relevant based on its event context when it is opened.

Example:
If you want to allow your form to access data from Baseline event (OID “SE_BASELINE”), Visit 2 event (OID “SE_VISIT2”), and the current event occurrence (“current_event”), you would put the following value in this cell: SE_BASELINE,SE_VISIT2,current_event

Note: If you enter an invalid value in this cell, it will act as if you hadn’t entered a value, thus all data for the current participant will be available for the form to access. This will ensure that the logic works as expected, but performance will not be optimized.

Required Message

If the item is required, you can include a message that explains why the answer is needed. This can include a helpful hint to the data entry user as to why the item is required such as noting that an item is a primary data point, or that an item is required due to a prior response. If this field is left blank on a required item, the default message, This field is required, will be used.

Required Type

This field determines whether a data entry user can override a required field and save the form as-is. To prevent this you must add a column to the survey sheet with the heading bind::oc::required-type and type strict on the field for that item. If left blank or not included, the user can override the requirement. For more information refer to the form logic section under “Hard Edit Checks”.

Image (Choices)

Allows you to display an image in your form. You must upload the valid image file (e.g., files with an extension of .png or .jpg) at the same time that you upload the Form Definition File or you can add it to a draft using the Upload Media & External Lists option. For example, Wong-Baker face images for pain scale choices.

Choice Filter

An expression for using filters for cascading selects (i.e. items are filtered based on responses to other items) see the section on Cascading Selects for more information.

List Name

The name of your code list. The same name is used for each value combination of a list (alphanumeric characters and underscores are permitted; no spaces). If you have a yes/no codelist and name it YN, there would be two rows referencing the same list_name:

list_name	label	name
YN	Yes	1
YN	No	2

Repeat Count

When added to a begin_repeat type, this allows you to specify an exact number of repeats available to users. If used, the option to add or remove entries is not available.

Constraint Type

Determines whether a data entry user can override the constraint. To prevent this you must add a column to the survey sheet with the heading bind::oc::constraint-type and type strict on the field for that item If left blank or not included, the user can override the requirement.