Study Designer

Study Designer contains a set of features that allow you to define, configure, and manage Events, Forms, Sites, Users, and other components for your study.

You must have a User Type of Administrator and a User Role of Data Manager to access Study Designer.

Forms appear on Form Cards under the title of the associated event. You can drag-and-drop events and forms to reorganize your study. Dragging a form from one event to another will automatically copy that form into the new event while dragging the entire event will reorder the event (including its associated forms) to its new location.

The header bar displays the status of your study, provides a link to the My Studies screen, and gives you access to the user menu.

You can use the buttons on the upper right side of the screen to access settings, Share your study, Publish your study, or Go to your study in Test or Production.

Icons

In Study Designer, one or multiple icons appear after the name of the Event.

IconEvent TypeDescriptionExample(s)
Visit-BasedAn event that is associated with a visit date. The event can be repeating or non-repeating.Week 2 Visit (non-repeating);
Monthly Follow-Up for Disease-Free Survival (repeating)
CommonAn event that is not necessarily associated with a visit date.Early Withdrawl or Termination (non-repeating);
Adverse Events (repeating)
RepeatingAn event that repeats in your study, either a known or unknown, number of times.
This icon will appear adjacent to one of the previous two when an event is a repeating event.
Concomitant Medications

Features Accessible from the Header Navigation:

  • Library Management: Data Managers who are Administrators can access the library from here. (See Content Library for more information)
  • Form Template: Click this link to download the Form Template.
  • Table Design: This feature allows you to add custom columns to the Participant Matrix and Queries Table.
  • Filter: This feature expands the right sidebar, which allows you to filter Forms by permission tags, labels and members.
  • Search: This feature expands the right sidebar, which allows you to enter text to search for Forms in the current study.
  • Multi-Select: This feature expands the right sidebar, which allows you to select multiple forms by permission tags, labels, and members.
  • Archive: This feature expands the right sidebar, which allows you to select Forms to copy or archive. You can also select by permission tags, labels, and members.

This document covers all of these features (excluding Library Management) in more detail.

Events

Definitions:

An Event is a group of Forms that are used in your Study. An event might or might not be connected to a real-world visit.

A Form or eCRF (electronic Case Report From) is a group of fields for collecting Participant data.

Examples:

An Event could be a follow-up visit that occurs during a study.

Form could be used to record a Participants vital signs, capture a patients informed consent, track drug accountability, etc.

Events and the Participant Details Screen

Events appear on the Participant Details Screen as follows:

Each Event Can be Defined as One of the Following Types:

  • Visit-Based: An Event that is scheduled to occur within the study and is associated with a visit date.

  • Common: An Event that isn’t necessarily associated with a visit but may occur any time throughout the study.

In a typical interventional clinical trial, most Events are defined as Visit-Based Events, such as: Week 2, Week 6, and Monthly Follow-up, in which the Week 2 visit occurs two weeks after the Baseline visit, the Week 6 visit occurs six weeks after Baseline, etc. These visits are associated with a schedule that is outlined in the study protocol, and each visit has a specific set of Forms that are collected.

Common Events are used to collect information that is not necessarily related to a scheduled visit date. For example, Adverse Event (AE), Concomitant Medication (ConMed), or Early Termination Events.

Common Events can be defined as either Repeating Events (e.g. AEs and ConMeds, since Participants might have more than one AE or ConMed) or Non-Repeating Events (e.g. Early Termination, since a Participant can only terminate once.)

To Enter Study Designer:

Click the Design button on the My Studies screen.

To Add an Event to a Study:

  1. Click +Add an Event.
  2. Enter a name for your Event.
  3. To edit details, click on the name of the Event.
  4. Enter values into fields, as needed.
  5. Click the Save button.

To Copy an Event:

  1. Click on the Menu button next to the name of the Event.
  2. Select Copy.

Note: When you copy an Event, any changes you make to one Event are automatically applied to the copies.

To Archive an Event:

  1. Click on the Menu button next to the name of the Event.
  2. Select Archive.

Note: Archiving an Event from within Study Designer removes the Event and all associated Forms from the study. If a study was previously published, the Event was archived, and the study was republished, that Event is no longer available to any users. However, archived Events can be restored at any time.

To Restore an Event:

  1. Click the Archived Items button in the header bar.
  2. Click the Restore button next to an Event you want to restore.

Note: Restoring an Event restores all its Forms. You can restore an Event with only a specific Form by clicking the Restore button next to the Form.

To Edit Settings for an Event:

  1. Click the name of the Event.
  2. Change settings as needed.

Warning: Once you have published your study to Production, you cannot change the Event to or from Repeating/Non-Repeating or Visit-Based/Common.

Forms

To build a form, you can either use the drag and drop Form Designer or an Excel-based Form Template.

If you use Form Designer, you can create questions manually or select pre-existing questions from the Content Library.

If you use the Form Template, you can either start with the empty Form Template, or download a Sample Form, which you can customize or use as is. 

You can also use both Form Designer and the Form Template. For example, it is possible to start building your form in Form Designer, download the form’s XLS template and make changes to it in Excel, upload the changed template, and make subsequent changes back in Form Designer.

Note: If you start with a Form Template, edit the Form in Form Designer, then try to download the XLS spreadsheet again, some formatting will be lost (but it will still be fully functional).

For more information on creating Forms, see Using Form Designer or Using the Form Template.

To Download the Form Template:

In Study Designer, click the Form Template button in the header to download the Form Template.

Best Practice:

If you have previously downloaded the Form Template, make sure to download it again to get the most recent version.

To Upload a Form:

  1. Click on the name of the Form.
  2. Click the Upload button to upload a Form.
  3. (Optional) Click the Preview button to preview a Form.

Note: If you are uploading external media, such as images, videos, etc. you must click Ctrl (Windows) or Command (Mac) and select both the spreadsheet and the file(s).

To Preview a Form:

Click the Preview button on the Form card to view and test your Form, including edit checks, conditional fields, and calculations.

Note: Cross-form logic does not function as it does in Study Runner (i.e. the published study). You cannot save data in Preview mode, and the Close and Complete buttons do not appear. Click the Validate button to check whether data you valid

If the Participate Module has been activated, and you select the Form Property of Participate Form, this option appears as Preview (as a Participant).

To Copy a Form to another Event:

  1. Click the name of the Form.
  2. Click on the Menu button in the corner of the Form.
  3. Select Copy To.

Note: When you copy a Form to another Event, any changes you make to one copy are automatically applied to the copies.

To Archive a Form:

  1. Click the name of the Form.
  2. Click on the Menu button in the corner of the Form.
  3. Select Archive.

Note: Archiving a Form removes the Form from the associated Event. The data remains in the database, but it is no longer considered part of a Participant’s active record and data cannot be extracted. If the event is restored, the data will once again be part of a Participant’s active record.

The same Form can be used for multiple Events. In this case, archiving the Form in one Event does not have any impact on the Form in another Event.

To Restore a Form:

  1. Click the Archived Items button in the header.
  2. Select Forms.
  3. Click the Restore button next to the Form you want to restore.

To Restore a Form Version:

  1. Click the Archived Items button in the header.
  2. Select Forms.
  3. Click the Restore button next to the Form you want to restore. 

Form Properties

Forms can be Hidden, Required, and/or a Participate Form.

IconForm PropertyDescriptionExample
HiddenThe Form is hidden at the site level but is accessible from the study level.This is usually used when you want to import data rather thanentering it directly in the user interface to prevent site users from viewing or changing data.
RequiredThe Form must be completed in order for the Event to be completed.A Participant would be required to complete a consent Form to participate in the study.
Participate FormAllows the Participant to enter their own data with the use of OpenClinica Participate. (This checkbox is not available if the Participate module has not been activated.)A Participant might be asked to complete a questionnaire to evaluate potential side effects of a new medication.
(No Icon)Allow Add AnotherAllows the user to add a new instance of a Form in a common repeating Event. If the user clicks the Add Another checkbox, when they click Close or Complete, another instance of the Form automatically appears.A user might need to document multiple Concommitant Medications.

To Set Form Properties:

Click the checkboxes on the Form Card.

Best Practice: Use Permission Tags instead of setting the Form to Hidden for more flexibility.

SDV Requirements

Forms may or may not require SDV (Source Data Verification), depending on the study protocol.

IconSDV RequirementDescription
(No Icon)Not ApplicableSDV is not applicable for this Form.
Not Required (Default)SDV is not required for the Form. SDV is not required for the study, but you can still perform SDV if you want. This is often used when 10% of Forms need to be SDVed.
Partial RequiredSome fields on the Form must be verified.
100% RequiredEvery field in the Form must be verified.

To Set SDV Requirements:

Click the drop-down menu next to SDV on the Form Card and select the requirement level you want to apply to the Form.

Drafts and Versions

When you initially upload a Form Template, your Form automatically becomes a version. This appears under Versions on the Form Card. 

You can make changes to the Form Template and upload new versions or overwrite the existing version.

When you create a Form in Form Designer and save it, it becomes a draft and appears under Drafts on the Form Card. You can make changes as needed, and if you have multiple drafts, the most recent draft is moved to the top of the list with the label, (latest).

When You Create a Draft, it Does Not:

  • Create a new version
  • Appear when you publish your study
  • Appear on the Audit Log

You can promote the draft to a version to include it in your study when you publish it.  

Warning: If you do not want the new Form to overwrite an existing Form, make sure to change the number in the Version number field on the Layout & Settings panel in Form Designer. 

Once a Form has been published to Production, it cannot be overwritten. You must create a new version, or an error appears.

Drafts

To Access the Drafts Menu:

Click the Menu button under Drafts to access a list of Version Options

To Add a Draft to Your Study/Make the Draft a Version:

  1. Click the Menu button next to the draft you want to add to your study/promote to a version.
  2. Select Add to Study.

To Edit the Draft in Form Designer:

  1. Click the Menu button next to the draft you want to edit in Form Designer.
  2. Select Design.

To Upload Media & External Lists: 

  1. Click the Menu button next to the draft you want to upload media and/or external lists to.
  2. Select Upload.

To Download the Draft:

  1. Click the Menu button next to the draft you want to download.
  2. Select Download.

Warning: If you upload the Form Template, edit it in Form Designer, and then download the form, the downloaded spreadsheet will be formatted differently from the original.

To Permanently Delete the Draft:

  1. Click the Menu button next to the draft you want to permanently delete.
  2. Select Discard.

Versions

To Access the Versions Menu:

Click the Menu button under Versions to access a list of Version Options.

To Edit the Version in Form Designer:

  1. Click the Menu button next to the version you want to edit in Form Designer.
  2. Select Design.

To Preview the Version:

  1. Click the Menu button next to the version you want to preview.
  2. Select Preview.

To Download the Version:

  1. Click the Menu button next to the version you want to download.
  2. Select Download.

Displaying Fields on the Participant Details Screen

If you are using a Common Event, you can select items from Forms within that Event to appear on the Participant Details screen.

Best Practice: Selecting items to appear on the Participant Details screen is optional, but it can be helpful because it allows you to see the selected item values without opening the Form.

For example, you might have an Adverse Event Form in a Repeating Common Event. You could select items from this form to create a well-organized list of all AEs. Users could then easily scan this list in order to identify AEs that need to be updated, reviewed, locked, etc. 

Prerequisites:

  • The Event must be a Common Event.
  • You must have uploaded a Form.
  • The Form must include at least one field that is not in a Repeating Group.

If Those Prerequisites Have Been Met:

  1. In Study Designer, click the name of the Form to open the Form card.
  2. In the fields to display on participant details page (optional) field, select items that you want to appear on the Participant Details screen from the list. Click and drag the fields to specify the order of the columns.

  1. Click the X to close the Form card.
  2. Click the Publish header button and select Test or Production.

Warning: Once you publish a study:

  • Change a Common Event to a Visit Based Event.
  • Change a Visit Based Event to a Common Event.
  • Change a Repeating Event to a Non-Repeating Event.
  1. Click the Go header button and select Test or Production.
  2. Click the Participant Matrix header button, or click on the Tasks menu and select Participant Matrix.
  3. Click the View button next to the Participant for whom you want to view the selected fields.

  1. Expand the Event header to view the table that displays the selected fields.

Defining Custom Column Headers on the Participant Details Screen:

You can control the column headers displayed in your custom columns on the Participant Details screen. If you include an item brief description for the selected Item in the Form spreadsheet or in Form Designer, that description appears as the column header for the custom column. Otherwise, the column header displays the items label.

Defining Custom Column Headers on the Participant Matrix and Queries Table:

The Table Design feature also allows you to add custom columns to two of the most important dashboards in Study Runner: the Participant Matrix and the Queries Table.

For example, you could add a column to these tables to make it easy for users to distinguish Participants in different Study arms or cohorts, or, you might add a column to the Participant Matrix to display the Screening Status, allowing users to easily filter out Participants who were not successfully screened.

To Add Custom Columns to the Participant Matrix or Queries Screen:

  1. Click the Table Design button to select fields that appear as custom columns in tables in Study Runner.

  1. Choose the data Item(s) you would like to display as custom columns on the Participant Matrix and/or Queries Table. You can only select non-repeating fields from non-repeating events. Selected fields appear in both the standard view of the Participant Matrix and Queries Table and when you click Show More.

If you include an item brief description for the selected Item in the Form spreadsheet or in Form Designer, that description appears as the column header for the custom column. Otherwise, the column header displays the items label.

The Participant Matrix With Custom Columns:

The Queries Table With Custom Columns:

Filters

To view all filter options, click the Filter icon in the header of the screen. Then, click the item or items you want to filter by. These include:

  • Labels
  • Members
  • Permission tags

To Remove a Filter:

Click the X to the right of the Filter is on button in the header of the screen.

Search

You can enter a search phrase to search for Forms in the study based on their title and/or description. Searching finds both active and archived Forms drafts and versions.

To Search Form Titles and Descriptions:

Click the Search button in the header of the screen.

Multi-Selection Mode

Multi-Selection mode allows you to work with multiple Forms. For example  you can copy them, archive them, assign permission tags, add labels, etc.

To Select all Forms:

  1. Click the Multi-selection button in the header in Study Designer.
  2. Click the Select All button on the right-hand sidebar.

The Select All button changes to the Unselect All button after selecting Forms.

To Unselect all Forms:

Click the Unselect All button on the right-hand sidebar.

To Copy the Selected Forms:

  1. Click the Multi-selection button in the header in Study Designer.
  2. Click the Select All button on the right-hand sidebar.
  3. Click the Copy Selection button.

To Archive the Selected Forms:

  1. Click the Multi-selection button in the header in Study Designer.
  2. Click the Select All button on the right-hand sidebar.
  3. Click the Archive selection button.

To Add Members to All Selected Forms:

  1. Click the Multi-selection button in the header in Study Designer.
  2. Click the Select All button on the right-hand sidebar.
  3. Click a label or labels to add to all selected Forms.

Copy & Archive Selection Mode:

The Copy Selection and Archive Selection buttons are located in the right-hand panel when the multi-selection mode is active.

Click the Archived Items header button to restore archived Events or Forms.

Collaboration Features

OpenClinica has built-in features to facilitate collaboration with colleagues while you build your Study. These include:

  • Design Activity
  • Labels
  • Checklists
  • Comments
  • Members

Activity Log

Definition: The Activity Log displays design-related actions that have been taken. It also displays the user who performed the action and when the action was performed.

Example: A user might check the Activity Log to see what recent actions have occurred.

The Activity Log displays a log of design-related actions on the expandable right-side panel. This makes it easy to see the changes that were made, the user who made the changes, and when the change occurred.

Actions that are logged include:

  • Adding/Removing Forms and Events
  • Updating Form and Event Properties
  • Moving/reordering Forms and Events
  • Modifying table design
  • Assigning labels and permissions
  • Posting comments
  • Publishing the study

Labels

Definition: A Label is a color or color with text that can be used to represent groups of Events or Forms. Labels can be used to help facilitate building your study but have no functional implications.

Example: You might use a label to distinguish Forms that apply to the Treatment group from those that apply to the Placebo group. You can add labels to Forms in order to organize them.

Labels can be created/updated from within the expandable right-side panel, any Form Card, or any Event Card.

To Create a Label from the Side Panel For a Form or Event:

  1. In Study Designer, click < on the right of the screen.
  2. Select a color or click the + button.
    1. (Optional) If you selected a color, enter a name for the label in the Name field.
    2. If you clicked the + button, enter a name for the label in the Name field, and select a color.
  3. Click the Create button.

To Create Label from the Study Card for a Form or Event:

  1. Click the name of the Form you want to add the label to.
  2. Click the + button under Labels.
  3. Select a color, click the Edit icon next to a color, or click the Create Label link.
    1. (Optional) If you selected a color, click the Edit button next to the color, enter a name for the label in the Name field, and click the Save button.
    2. If you clicked the Create Label link, enter a name for the label in the Name field, select a color, and click the Create button.

To Remove a Label from a Form or Event:

  1. Click the name of the Form you want to remove the label from.
  2. Click the label or the + button.
  3. Click the label you want to remove from the Form.

To Delete a Label from a Form or Event:

  1. Click the name of the Form you want to add the label to.
  2. Click the + button under Labels.
  3. Select a color, and click the Edit button next to a color.
  4. Click the Delete button.

Checklists

Definition: A Checklist is a list of Form-specific tasks.

Example: You might use a checklist to keep track of tasks related to completing the appropriate review/approval process to use a Form in your study. You can add a checklist to your Form to keep track of tasks.

To Create a Checklist for a Form:

  1. Click the name of the Form you want to create a checklist for.
  2. Click +Add a checklist.
  3. Enter a name for the checklist.
  4. Click the Save button.

To Add Items to a Checklist on a Form:

  1. Click the name of the Form with a checklist you want to add items to.
  2. Click +Add an item to checklist.
  3. Enter text to describe the list item.
  4. Click the Save button.
  5. The item appears automatically after you click Save. Repeat steps 1-4, as needed.

To Delete a Checklist from a Form:

  1. Click the name of the Form with a checklist you want to delete.
  2. Click the Delete button.

Note: This deletes the entire checklist. You cannot delete an individual checklist item. Instead, edit the item.

To Check or Uncheck an Item on the Checklist:

Click the checkbox next to the item.

Comments

Definition: A Comment is text that allows users in Study Designer to communicate with collaborators.

Example: You might add a comment to communicate a change you made to a Form in Study Designer. Comments appear in the Activity section of Events and Forms as well as Design Activity located in the side panel.

To Enter a Comment on a Form:

  1. Click the name of the Form or Event you want to comment on.
  2. Enter text in the Activity field.
  3. Click the Comment button.

Members

Definition: A Member is a user involved in designing the study who can be associated with specific Events and Forms. Adding or removing a member does not determine access to Forms; it is a list of users associated with the study.

Example: You might add a member to request that they review/update a Form in Study Designer. You can add members to a Form within a study if the user has previously accessed Study Designer.

To Add a Member to a Form:

  1. Click the name of a Form you want to add a member to.
  2. Click the + button.
  3. Select a name or multiple names from the dropdown list.

To Remove a Member from a Form:

  1. Click the name of a Form you want to remove the member on.
  2. Click the + button.
  3. Select the name or multiple names from the dropdown list.

Permission Tags

Data Managers can create and assign Permission Tags to Forms in Study Designer. These Permission Tags determine which User Roles can access data from specific Forms in Study Runner. You can assign access to Roles on the User Roles screen.

If a User Does Not Have Access to a Specific Form, They Cannot:

  • Extract data for that Form.
  • View queries associated with the specific Form.
  • View or edit that specific Form.
  • The user cannot view details associated with the specific Form in the Audit Log. Details from the Form appear as <Masked>.

To Create a Permission Tag:

  1. Click on the name of the Form for which you want to create a Permission Tag, or click < on the right side of the screen to open the panel.
  2. Click the + button under Permission Tag.
  3. Select Create Permission Tag.
  4. Enter a name for the tag. This is most likely the name of the Event, Form, or User Role.
  5. Leave the default Permission Tag color as is, or select a color for the Permission Tag.
  6. Click the Create button. This creates the Permission Tag but does not attach it to anything.

To Add a Permission Tag to a Form:

  1. After you have created the Permission Tag, click on the name of the Form for which you want to add the Permission Tag.
  2. Click the + button under Create Permission Tag.
  3. Click the Permission Tag you want to add to this Form.

A check appears next to the name of the Permission Tag, and the tag appears under Permission Tag.

To Remove the Permission Tag From this Form:

Click the Permission Tag in the dropdown list again.

Note: If you copy a Form to another Event, the associated Permission Tag is also copied but can easily be removed. You must publish your study after creating a Permission Tag for it to take effect.

To Assign Permission Tags to User Roles:

  1. After you have published the study, click the Settings (Gear) button on the My Studies screen or in Study Designer to go to the User Roles screen.
  2. On the User Roles screen, select Edit in the Actions column next to the User Role you want to assign Permission Tags to.

  1. Click the checkboxes next to the Permission Tags that represent permissions you want that user to have. To remove access to a specific Permission Tag for a User Role, click the checked checkbox to uncheck it.
  2. Follow steps 1-3 for each User Role you want to customize with Permission Tags.

When Assigning Tags to User Roles, Keep the Following in Mind:

  • All user roles have access to untagged Forms.
  • If you add a tag to a Form, only User Roles that have been assigned the Permission Tag can access the Form.
  • Users who could previously access the Form (because it was untagged) can no longer access that Form.

1.3.1 Using the Form Template

Definitions:

  • Form Template: The blank XLS spreadsheet as downloaded from Study Designer
  • Form Definition Spreadsheet: The completed XLS spreadsheet

Form creation is easiest using the drag-and-drop Form Designer, but sometimes it is necessary 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, use the Form Template for complicated Forms. While Form Designer accomodates skip logic (relevant fields) and validation criteria (constraints), it does not support features such as cascading selects, hard edit checks, etc.

Best Practice: Keep in mind that loading times are affected by the number of items on the form and the amount of Form logic you use, OpenClinica reccommends having 100-200 items on a form and no more than 50 on a Participate Form, specifically when accessed from a mobile device.

The Form Template is a pre-formatted XLS spreadsheet. 

The XLS Spreadsheet Contains Five Sheets:

  1. Settings
  2. Choices
  3. Survey
  4. Cross-Checking Examples
  5. Other Examples

The three main pages are the Settings, Choices, and Survey sheets.

QuickStart Guide

To Download the Form Template:

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

To Enter the Form Title:

  1. Open the downloaded Form Template.
  2. Enter a name for the Form in the name column.

To Add an Item to the Form:

  1. Click the survey tab in the Form Template spreadsheet.
  2. Enter the type of item you want in the type column. (For example, text, integer, decimal, date)
  3. Enter the item text in the label column.
  4. Enter a unique mnemonic for the item in the name column.

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

To Enter Choices for Select One or Select Multiple items:

  1. Click the choices tab in the Form Template spreadsheet.
  2. Enter the text for the option in the label column.
  3. Enter a unique mnemonic for the option in the name column.
  4. Enter an internal name for the list of options in the list name column.
  5. Continue to add options as needed.
  6. Click the survey tab in the Form Template spreadsheet.
  7. 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 column is select_one YN)

Note: The spacing and underscores in select_one listname and select_multiple listname need to be exact.

To Create a Group of Items:

  1. Click the survey tab in the Form Template spreadsheet.
  2. Enter begin group in the type column at the top of all the items you want to put into a group.
  3. Enter end group in the type column at the bottom of all of the items you want to put into a group.
  4. 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, with the exception of 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:

  1. Click the name of the Form in Study Designer.
  2. Click the Upload button.
  3. Select the Form Template.
  4. Click the Open button.

You can download a blank copy of the Form Template from within Study Designer and start building your Form there, or you can download the Form Definition Spreadsheet for an existing Form in the eCRF Library and modify it to suit your needs.

The Form Template is an XLS file, and contains documentation on how to create/configure your Form, but it is also in the table at the end of this page.

  • Hover over any column heading for a description of how to use that column within the Template.
  • Access the Cross-Checking Examples worksheet for documentation on creating Cross-Form and Cross-Event Edit Checks.

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. 

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 a question, the responses in the next question are filtered based on that response. 

To Add a Cascading Select:

  1. On the choices sheet, create columns for each filter. For example, filter 1 and filter 2
  2. For each filter, across from each choice, enter a number to represent the filter group. For example, filter 1 might have 4 filter groups that contain different choices. Use the numbers 1-4 to assign each item to a filter group.
  3. On the survey sheet, add a choice_filter column. 
  4. In the column, enter the name of the item you want to filter response for. For example, filter1 = ${cascade1}.

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 the 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.

Hard Edit Checks

Hard edit checks can be used to enforce stricter standards on data entry. Because they can make data entry more difficult for users, it is recommended that they be used only when strictly necessary. 

All checks that are not explicitly defined as hard edit checks are soft edit checks in all Forms except for Participate Forms. In that case, all edit checks are automatically hard edit checks.

Note: When a value is entered and it violates a hard check on an item, the value is rejected before it is stored, and the user will see a pop-up.

When a value is entered, and it causes a hard check to be violated on a different item, the value entered is saved as normal. In this case, the user will see an error message displayed on the item with the hard check, and it will have an orange background (distinct from the soft red background used for soft check error messages).

A user cannot navigate forward in the form or mark the form complete while a hard check error message is present.

A user can add a manual query or choose to add an autoquery to a hard check item in order to close the form. However, the query will not hide the hard check error message.

Special care must be taken when using relevant logic (hide/show) for an item with a hard required check. Once an item has a value, a hard required check will not allow the item to be cleared. 

Because of this, the item’s hard required logic must indicate that the item is required only when the item’s relevant logic is met. If this practice is not followed, the user may get into a state where they cannot clear an item even though that is the only way to make the data consistent with the relevant logic. 

For example, if the item (or the group it is in) has relevant logic ${yn_item} = 1, then the hard required logic must also include ${yn_item} = 1 to ensure that the form works as intended. That will enforce the hard required check when the item is relevant, but will not enforce the check when the item is not relevant.To Make a 

Hard Edit Check for a Required Item:

  1. Click the survey tab in the Form Template spreadsheet.
  2. Add a column with the header bind::oc:requiredtype.
  3. Enter strict.

To Make a Hard Edit Check for a Constraint:

  1. Click the survey tab in the Form Template spreadsheet.
  2. Add a column with the header bind::oc:constrainttype.
  3. Enter strict.

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 an OpenClinica Form, you can maintain that list in a separate CSV file so that 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.

Instead of uploading a normal Form Definition Spreadsheet, 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.

Best Practice: If you make any changes to the list of choices, you must upload the CSV file 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 Template.

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:

  1. Click the survey tab in the Form Template.
  2. Add a repeat_count column.
  3. In the repeat_count column, across from begin_repeat and end_repeat, enter the number of repeats to allow.

Select_One From File

For items with a long list of choices, you can upload a CSV file with the Form Template.

You can create the CSV file in any spreadsheet program.

To Create a CSV File:

  1. Open any spreadsheet program.
  2. Make columns for label and name.
  3. Enter a list of choices.
  4. Select File.
  5. Select Save As.
  6. Select .CSV.

To Reference the CSV File in the Form Template:

On the Form Template, on the survey sheet, enter select_one_from_filename.csv in the type column. For example, if the name of the CSV file is painlocation, enter select_one_from_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 pressing ctrl and selecting both files.

Translations

You can add multiple languages to your form by adding columns to your XLS spreadsheet. If you want English to be your default language, change the title in the label column to label::English. Then add the column default_language, and enter English. You can define several other languages by adding columns in the choices and/or survey sheet, each with the title label::language

Enter translated text for every field you want to be translated; otherwise that field will use the default 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)

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

This Form has columns for label::Greek and label::Deutsche.

Image Maps

Study Designer 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. On 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 (3c), for example, id=path10 When you have added an id for each path, save the file.

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

Form Template and Form Designer Fields

Click the images to enlarge them.

FieldForm DesignerForm Template
Form Title
The form title appears at the top of the data entry page.
You can use alphanumeric characters, special characters (e.g. & # $ ^ _), and spacesYou can use alphanumeric characters, special characters (e.g. & # $ ^ _), and spaces.
Form ID
A unique identifier used as an internal reference when the form is uploaded.

This value is not visible to end-users.
Alphanumeric characters and underscores are permitted; no spaces.
Alphanumeric characters and underscores are permitted; no spaces.
Form Version
A unique identifier for an iteration of a given form (including changes to items, form logic, etc.).
You must change the version number if you want to create a new version of your form. Otherwise, the form overwrites the existing version. In the TEST environment, you cannot overwrite the Type or Item Group for an item or move an item in or out of a repeating group.

Saving your Form as a draft does not create a new version, but you can later promote a draft to a version using the Add to Study menu option on the Form card in Study Designer.
In the Test environment you can overwrite versions for changes to anything except the following features (these require a new form or a new item name):

  • Data type (the type column of the survey sheet)
  • Item group (the bind::oc:itemgroup column of the survey sheet)
  • Moving an item into or out of a repeating group


In the Production environment you must have a unique version identifier each time you upload a modification to the form.
Form Style
This specifies the layout and appearance of the form, primarily dealing with how the items are displayed (each question on a separate line, or a grid, and whether on a single page or multiple pages by groups).
There are four styles to choose from:

  • Simple - single page: Items appear in rows on a single page.

  • Simple - multiple pages: Items appear in rows with the other items in their groups on, each group on a separate page.

  • Grid - single page: Items appear together as a group but can have multiple questions appearing in the same row as columns; this is defined in the individual question settings.

  • Grid - multiple pages: The same as Grid - single page but each group of items will be displayed on its own page.


Note: If you group items together and click the "Show all questions in this group on the same screen" check box, items in the group appear on the same page, overriding a multiple pages setting.
You can leave this column blank or select from three options:

If left blank: Each question is on a separate line on the same page. [Simple - single page]

  • pages:One question or group of questions per page, with each question on a separate line. [Simple - multiple pages]

  • theme-grid: All groups of questions will appear on a single page, with all items displayed in table format. [Grid - multiple pages]

  • pages theme-grid: One question or group of questions per page with all items displayed in table format. [Grid - single page]


  • Note: When using Form Template, question groups (referenced above) are defined on the survey worksheet. When combined with the field-list option of the appearance column on the survey worksheet, you can control the display of questions and the structure of grids. See the entry on appearance below for more information.
NamespacesN/AThe 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 ReferencesN/AYou can use this column to decrease form 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 this case, the 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

You could also leave the cell blank, and your cross-form logic would work as expected, but the form would likely have slower performance.

Note: \If you enter an invalid value in this cell, 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.
Question Text/LabelThis is the text that appears in the Form for an item/question.
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
Enter Question Hint/HintInformative text that appears on the Form to help the user.


For example, “Please provide weight in kilograms.”

Hints appear in italics under the question label.
Informative text displayed on the form to help the user.

For example, Please provide weight in kilograms.

Hints display in italics under the question label.
Item Name/NameThe internal name of the item, as used in the database. This is used to generate the item object identifier (OID)This does not appear during data entry. Alphanumeric characters and underscores are allowed.
The unique name of the item. This is not displayed during data entry, but is how the data is referenced in the database.

Allows alphanumeric characters and underscores; spaces are not allowed. It is recommended that only lowercase letters, digits, and underscores are used in item names.

Once an item name is defined in this spreadsheet and the form is uploaded into OpenClinica, the name should not be changed to use different letter case when the form is uploaded again.

For example, if item1 is part of the first form upload, this name should not be changed to ITEM1 or Item1 when the form is subsequently uploaded. Any change from/to upper/lower case in an item name will result in a form or publish error.
Item GroupThe internal name of the group that the item is in, as used in the database. This is used to generate the item object identifier (OID). Alphanumeric characters and underscores are allowed; spaces are not allowed.
The name of the group to which you are assigning the item in the underlying database. This becomes the item group object identifier (OID).

Alphanumeric characters and underscores are allowed; spaces are not allowed. It is recommended that only lowercase letters, digits, and underscores are used in itemgroup names.

The itemgroup name does not have to correspond to the begin/end group names defined in the type column.

Begin group/repeat, end group/repeat, and note types should not have a value in the bind::oc:itemgroup cell.

All items in a repeating group must have the same itemgroup name. That itemgroup name cannot be used by other items that are outside that repeating group.

Once an itemgroup name is defined in this spreadsheet and the form is uploaded into OpenClinica, the itemgroup name should not be changed to use different letter case when the form is uploaded again.

For example, if group1 is part of the first form upload, this should not be changed to GROUP1 or Group1 when the form is subsequently uploaded. Any change from/to upper/lower case in an itemgroup name will result in a form or publish error.
TypeThe data type of the item (e.g. select one, select multiple, etc.)

  • Single-select: Allows the user to select one response from a list defined in the Form. Enter options in the Item Details.

  • Single-select (external list): Not available in Form Designer.

  • Multi-select: Allows the user to select one or more responses from a list defined in the Form. Enter options in the Item Details.

  • Text: Allows the user to enter a text value. Select the text icon. Text is up to 3,999 characters.

  • Integer: Allows the user to enter an integer value. Select the integer icon.

  • Decimal: Allows the user to enter a decimal value. Select the decimal icon.

  • Calculate: Calculates a value and does not display it to the user by default. Select the calculate icon.

  • Date: Allows the user to enter a date value. Select the date icon.

  • Note: Displays a message to the user without collecting a value. Select the note icon.

  • File: Allows the user to attach a file. Select the file icon.

  • Image: Allows the user to attach a .png or .gif file. Select the image icon.

  • Audio: Allows the user to attach an audio file. Select the audio icon.

  • Video: Allows the user to attach a video file. Select the video icon.

  • Layout Group (non-repeating): Allows users to group items together to alter the layout of the Form. Select one or more items and click the Group button.

  • Layout Group (repeating): Allows user to group items together to alter the layout of the Form and allow the user to enter values for the items multiple times, if necessary. Select one or more items and click the Group button. Then click the Settings (Gear) icon for the group and click the Repeat this group if necessary check box.


The data type of the item (e.g. select one, select multiple, etc.)

  • Single-select: Allows the user to select one response from a list defined in the Form. On the survey sheet, enter select_one xxxxx in the type column, and enter the same xxxxx in the name column. On the choices sheet, define options in the label and name columns.

  • Single-select (external list): Allows the user to select one response from a list defined in a CSV file. On the survey sheet, enter select_one_from_file xxxxx.csv in the type column, and enter the same xxxxx in the name column. This is ideal for long lists.

  • Multi-select: Allows the user to select one or more responses from a list defined in the Form. On the survey sheet, type select_multiple xxxxx in the type column, and enter the same xxxxx in the name column. On the choices sheet, define options in the label and name columns.

  • Text: Allows the user to enter a text value. On the survey sheet, enter text in the type column. Text is up to 3,999 characters.

  • Integer: Allows the user to enter an integer value. On the survey sheet, enter integer in the type column.

  • Decimal: Allows the user to enter a decimal value. On the survey sheet, enter decimal in the type column.

  • Calculate: Calculates a value and does not display it to the user by default. On the survey sheet, enter calculate in the type column. Use a type of note to display the answer.

  • Date: Allows the user to enter a date value. On the survey sheet, enter date in the type column.

  • Note:Displays a message to the user without collecting a value. On the survey sheet, enter note in the type column.

  • File: Allows the user to attach a file. On the survey sheet, enter file in the type column.
  • Image: Allows the user to attach a .png or .gif file. On the survey sheet, enter image in the type column.

  • Audio: Allows the user to attach an audio file. On the survey sheet, enter audio in the type column.

  • Video: Allows the user to attach a video file. On the survey sheet, enter video in the type column.

  • Layout Group (non-repeating): Allows users to group items together to alter the layout of the Form. On the survey sheet, enter begin group in the type column to indicate the beginning of a group of items and enter end group in the type column to indicate the end of the group of items.

  • Layout Group (repeating): Allows user to group items together to alter the layout of the Form and allow the user to enter values for the items multiple times, if necessary. On the survey sheet, enter begin repeat in the type column to indicate the beginning of a repeated group of items and enter end repeat in the type column to indicate the end of a repeated group of items.


Item Brief DescriptionA short description of the item that can be used to reference it in tables.

This description can be up to 40 characters. You cannot use special characters.

If this is not defined for an item in a table, the Item Name appears instead.
A short description of the item that can be used to reference it in tables.

This description can be up to 40 characters. You cannot use special characters.

If this is not defined for an item in a table, the Item Name appears instead.
Item DescriptionA long description of the item that can be used to define the data that the item/question contains. This is not displayed on the Form during data data entry. The text can be up to 3,999 characters. You cannot use special characters. The description is included in some data extract formats.
A long description of the item that can be used to define the data that the item/question contains. This is not displayed on the Form during data data entry. The text can be up to 3,999 characters. You cannot use special characters. The description is included in some data extract formats.
AppearanceThis determines how each item appears based on its Type. Items do not have a specific appearance by default. This setting is optional.

Note: the type,other indicates that instead of selecting the option, other, you can enter the appearance directly in the field. other also appears as an option for the item types indicated.

You can specify width for any item. (See Width)

Single select / Multi-select

  • default: Allows the user to select one or multiple responses.

  • minimal: Displays answer choices in a drop-down menu rather than the default display of radio buttons (for select_one and select_multiple) or check boxes (for select_multiple)

  • columns or columns no-buttons: Arranges answer choices horizontally in columns based on screen size (Displays radio buttons or check boxes unless you specify no-buttons, which displays text or images.)

  • columns-pack or columns-pack no-buttons: Arranges image answer choices side-by-side, close together (Displays radio buttons or check boxes unless you specify no-buttons, which displays text or images.)

  • columns-n or no-buttons: Arranges image answer choices in column Format with n columns (n <= 10) (Displays radio buttons or check boxes unless you specify no-buttons, which displays text or images.)

  • likert: Displays answer choices as a Likert scale (This is not available for select_multiple items.)

  • image-map: Displays an image (must be uploaded with the Form); allows user to select by clicking part of the image (e.g., a select_multiple specific parts on a body map). Only files with an extension of .svg are permitted, and the file name must be listed in the image column for the item

  • autocomplete:Displays options that match the information you enter as you type.

  • other: Select other and enter another appearance or define the column width.


text

  • default: Allows the user to enter a single line of text.

  • multiline: Allows the user to enter text in a text box multiple lines long (word wrap).

  • other: Select other and enter another appearance or define the column width.


integer

  • default: Allows the user to enter a whole number.

  • other: Enter another appearance or define the column width.

  • analog scale: Allows the user to input an integer using a Visual Analogue Scale. Select the appropriate option for how you want to display the scale: analog horizontal, analog horizontal no-ticks, analog vertical, analog vertical no-ticks, and analog-scale vertical show-scale. The scale is always 0-100. In Form Designer, type this into the Appearance field.


decimal

  • default: Allows the user to enter a decimal number.

  • other: Enter another appearance or define the column width.


calculate

  • default: This occurs internally, so it does not have an appearance. You can use the note type to display the result.


Date

  • default: Allows the user to enter a full date: day, month, and year.

  • month-year: Allows the user to enter a partial date: month and year only.

  • year: Allows the user to enter a partial date: year only.

  • other: Select other and enter another appearance or define the column width.


note

  • default: Displays a note.

  • other: Enter another appearance or define the column width.


file

  • default: Allows the user to upload a file.

  • other: Enter another appearance or define the column width.

image

  • default: Allows the user to upload an image. A preview appears.

  • draw: Allows the user to draw a picture on the screen, using the mouse or a touch screen

  • annotate: Allows the user to upload an image and then draw on it, using the mouse or a touch screen

  • signature: Allows the user to draw a signature on the screen using the mouse or a touch screen. This is not a 21 CFR Part 11-compliant signature.

  • other: Select other and enter another appearance or define the column width.


audio

  • default: Allows the user to upload an audio file. A preview appears.

  • other: Enter another appearance or define the column width.


video

  • default: Allows the user to upload a video file. A preview appears.

  • other: Enter another appearance or define the column width.


Layout groups

  • default: Allows the user to group items without altering how they are displayed.

  • field-list: Displays an entire group of questions together on one page. In Form Designer, check the box next to the Show all questions in this group on the same screen.

  • table-list: Displays a common list of labels as a top row, and then each field in the group displays columns of radio buttons or check boxes.



Note: Items with no label or hint are treated as background calculations.
This means you can set the data type of a background calculation item as needed. For example, you can have an integer type item with a calculation but no label or hint. It does not appear on the form and performs a background calculation.

This determines how each item appears based on its Type. Items do not have a specific appearance by default. This setting is optional.

Note: the type,other indicates that instead of selecting the option, other, you can enter the appearance directly in the field. other also appears as an option for the item types indicated.

You can specify width for any item. (See Width)

Single select / Multi-select

  • default: Allows the user to select one or multiple responses.

  • minimal: Displays answer choices in a drop-down menu rather than the default display of radio buttons (for select_one and select_multiple) or check boxes (for select_multiple)

  • columns or columns no-buttons: Arranges answer choices horizontally in columns based on screen size (Displays radio buttons or check boxes unless you specify no-buttons, which displays text or images.)

  • columns-pack or columns-pack no-buttons: Arranges image answer choices side-by-side, close together (Displays radio buttons or check boxes unless you specify no-buttons, which displays text or images.)

  • columns-n or no-buttons: Arranges image answer choices in column Format with n columns (n <= 10) (Displays radio buttons or check boxes unless you specify no-buttons, which displays text or images.)

  • likert: Displays answer choices as a Likert scale (This is not available for select_multiple items.)

  • image-map: Displays an image (must be uploaded with the Form); allows user to select by clicking part of the image (e.g., a select_multiple specific parts on a body map). Only files with an extension of .svg are permitted, and the file name must be listed in the image column for the item

  • autocomplete:Displays options that match the information you enter as you type.

  • other: Select other and enter another appearance or define the column width.


text

  • default: Allows the user to enter a single line of text.

  • multiline: Allows the user to enter text in a text box multiple lines long (word wrap).

  • other: Select other and enter another appearance or define the column width.


integer

  • default: Allows the user to enter a whole number.

  • other: Enter another appearance or define the column width.

  • analog scale: Allows the user to input an integer using a Visual Analogue Scale. Select the appropriate option for how you want to display the scale: analog horizontal, analog horizontal no-ticks, analog vertical, analog vertical no-ticks and analog-scale vertical show-scale. The scale is always 0-100. In Form Designer, type this into the Appearance field.


decimal

  • default: Allows the user to enter a decimal number.

  • other: Enter another appearance or define the column width.


calculate

  • default: This occurs internally, so it does not have an appearance. You can use the note type to display the result.


Date

  • default: Allows the user to enter a full date: day, month, and year.

  • month-year: Allows the user to enter a partial date: month and year only.

  • year: Allows the user to enter a partial date: year only.

  • other: Select other and enter another appearance or define the column width.


note

  • default: Displays a note.

  • other: Enter another appearance or define the column width.


file

  • default: Allows the user to upload a file.

  • other: Enter another appearance or define the column width.

image

  • default: Allows the user to upload an image. A preview appears.

  • draw: Allows the user to draw a picture on the screen, using the mouse or a touch screen

  • annotate: Allows the user to upload an image and then draw on it, using the mouse or a touch screen

  • signature: Allows the user to draw a signature on the screen using the mouse or a touch screen. This is not a 21 CFR Part 11-compliant signature.

  • other: Select other and enter another appearance or define the column width.


audio

  • default: Allows the user to upload an audio file. A preview appears.

  • other: Enter another appearance or define the column width.


video

  • default: Allows the user to upload a video file. A preview appears.

  • other: Enter another appearance or define the column width.


Layout groups

  • default: Allows the user to group items without altering how they are displayed.

  • field-list: Displays an entire group of questions together on one page. In Form Designer, check the box next to the Show all questions in this group on the same screen.

  • table-list: Displays a common list of labels as a top row, and then each field in the group displays columns of radio buttons or check boxes.


Note: Items with no label or hint are treated as background calculations.
This means you can set the data type of a background calculation item as needed. For example, you can have an integer type item with a calculation but no label or hint. It does not appear on the form and performs a background calculation.
WidthFor an item or group of items on a grid form, you can control how many columns appear on each row by specifying the width w#.

If you specified a width of w6 for a layout group, it takes up the entire width of the grid.

If you specified w1 for a single item in the group, there would be one small column (1) and another large column (5).
For an item or group of items on a grid form, you can control how many columns appear on each row by specifying the width w#.

If you specified a width of w6 for a layout group, it takes up the entire width of the grid.

If you specified w1 for a single item in the group, there would be one small column (1) and another large column (5).
RequiredThis specifies whether a user is required to enter a response to the item to proceed with data entry.

Select Always, Never, or Conditional to specify whether/when a response to this item/question is required. If you select Conditional, you must enter a conditional value.
This specifies whether a user is required to enter a response to the item to proceed with data entry.

For required fields, type yes in the required column on the survey sheet. For conditionally required fields, enter a condition, as defined in the relevant column of the survey sheet.

For example, if Number of packs per day is required if Does the subject smoke? is answered yes, enter:

${smoke} = 1

Note: This column supports the syntax as defined in the calculation, constraint, or relevant columns of this worksheet. Refer to those column comments for additional examples.
Required MessageN/AIf the item is required, you can include a message that explains why the answer is needed.

If no message is entered here, the default message, This field is required, will be used.

If the form would be easier for the data entry user to fill out with a different message (for example, noting that an item is a primary data point that cannot be left blank or that an item is required due to a prior response), it can be defined in this column.
Required TypeN/AThis determines whether you can override the requirement. To do this, you must add a column to the survey sheet and type strict. If left blank or not included, the user can override the requirement.
Use External ValueThis item is a value used for logic or calculations.

clinicaldata is used for cross-Form, cross-event, or event level calculations.

contactdata displays contact data on a form.

If you enter contactdata, you must add a column called instance::oc:contactdata. That column must contain one of the following values to indicate which contact information it is collecting: firstname, lastname, email, mobilenumber, secondaryid.
This item is a value used for logic or calculations.

clinicaldata is used for cross-Form, cross-event, or event level calculations.

contactdata displays contact data on a form.

If you enter contactdata, you must add a column called instance::oc:contactdata. That column must contain one of the following values to indicate which contact information it is collecting: firstname, lastname, email, mobilenumber, secondaryid.
Read OnlyThis specifies that you cannot enter data for an item. This can be used for the types of text, calculations, etc.
This specifies that you cannot enter data for an item. This can be used for the types of text, calculations, etc.
CalculationAn expression used to calculate a value, usually using the values of preceding questions on the current Form. This can also be used for Cross-form calculations.

. is used to represent the current field's value.

${name} is used to reference a different item value on this Form, where name is the name of the other item.

You can use parentheses.

The following operators can be used:

  • Addition: +

  • Subtraction: -

  • Multiplication: *

  • Division: div

  • Equal: =

  • Not Equal: !=

  • Less than: <

  • Less than or equal to: <=

  • Greater than: >

  • Greater than or equal to: >=>/li>
    And: and

  • Or: or


For example, to calculate Mean Arterial blood Pressure (MAP) based on the items systolic and diastolic:

(systolic + (2*diastolic)) div 3

Calculations cannot be used for items with type of note.

If calculation is used for any type except calculate, that field must have Read Only set to yes.
An expression used to calculate a value, usually using the values of preceding questions on the current Form. This can also be used for Cross-form calculations.

. is used to represent the current field's value.

${name} is used to reference a different item value on this Form, where name is the name of the other item.

You can use parentheses.

The following operators can be used:

  • Addition: +

  • Subtraction: -

  • Multiplication: *

  • Division: div

  • Equal: =

  • Not Equal: !=

  • Less than: <

  • Less than or equal to: <=

  • Greater than: >

  • Greater than or equal to: >=>/li>
    And: and

  • Or: or


For example, to calculate Mean Arterial blood Pressure (MAP) based on the items systolic and diastolic:

(systolic + (2*diastolic)) div 3

Calculations cannot be used for items with type of note.

If calculation is used for any type except calculate, that field must have Read Only set to yes.
ImageN/AAllows 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 spreadsheet or you can add it to a draft using the Upload Media & External Lists option.
Choice FilterN/AAn expression for using filters for cascading selects (i.e. items are filtered based on responses to other items.)
Response Text/LabelThe question text to be displayed on the data entry form. This field allows alphanumeric characters.

Add a line break where you want using Ctrl-Enter or Ctrl-Alt-Enter (Windows) Option+Enter (Mac).

Styling prompts can be added to format your text as follows:

*text* displays as italics

**text** displays as bold

***text*** displays as bold italics

Increase font size by preceding the text with one to six hash tags. # makes the text the largest possible size, ## makes the text the smallest possible size. Sizes that display may vary for note vs. item vs. group labels.

Colors can be added as follows:

text for red text. You can use the hex code for the color of your choice. (You can look up hex codes by searching for css codes on the internet.)
The question text to be displayed on the data entry form. This field allows alphanumeric characters.

Add a line break where you want using Ctrl-Enter or Ctrl-Alt-Enter (Windows) Option+Enter (Mac).

Styling prompts can be added to format your text as follows:

*text* displays as italics

**text** displays as bold

***text*** displays as bold italics

Increase font size by preceding the text with one to six hash tags. # makes the text the largest possible size, ## makes the text the smallest possible size. Sizes that display may vary for note vs. item vs. group labels.

Colors can be added as follows:

text for red text. You can use the hex code for the color of your choice. (You can look up hex codes by searching for css codes on the internet.)
Value/NameThe unique code value stored in the database that corresponds to each answer choice (e.g. 1=Yes).

These codes are generated automatically but can be changed.
The unique code value stored in the database that corresponds to each answer choice (e.g. 1=Yes).
Image (Choice)N/AProvide an image file name (e.g. a file with an extension of .png or .jpg) that can be used as a response option. For example, Wong-Baker face images for pain scale choices. The image file must be uploaded at the same time that the Form Definition spreadsheet is uploaded into OpenClinica.
Filter ColumnN/AThe response values to filter by for cascading selects
List NameN/AThe 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
Item Name/NameThe unique internal name of the layout group used in the database. This is not displayed during data entry. Alphanumeric characters and underscores are allowed.
The unique internal name of the layout group used in the database. This is not displayed during data entry. Alphanumeric characters and underscores are allowed.
Show All Questions in this Group on the Same Screen/AppearanceClick this check box to make all items appear on the same screen (regardless of your layout selection.)
N/A
Repeat this group if NecessaryThis specifies that the group of items should be repeated.

Click this check box to make the selected group of questions a repeating group.
This uses begin repeat and end repeat in the Type column to specify that the group of items should be repeated.
Repeat CountN/AWhen 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.
Skip Logic / RelevantThis is a condition under which an item is skipped.

Enter a condition under which this item/question appears or is required.
This is a condition under which an item is skipped (as defined in the relevant column).

The item or group is only displayed if the provided expression evaluates to TRUE.

Use the following syntax:

${other question name} = value (for a numeric value)

or

${other question name} = 'value' (for a character value)

If the lead-in question uses a code list defined in the choices worksheet, use what is in the name column for that code list as the value.

For example, if you have two questions: Does the subject smoke? (item name = smoke) and How many packs per day? (item name=packs), the second question should only display if the answer to the first question is Yes.

If the first question (smoke) uses a code list defined in the choices worksheet as:

list_name label name
YN 1 Yes
YN 2 No

The relevant syntax for How many packs per day would be:

${smoke} = 1

For multi_select items, use the following syntax:

selected(${question name},value) (for a numeric value)

selected(${question name},'value') (for a character string)

Note: This column supports the syntax as defined in the required, calculations, or relevant columns.
Validation Criteria / ConstraintThis is a condition under which an a response is considered invalid.

Validation Criteria prevents users from entering invalid data. (e.g. "a Participant's pulse must be >=60 and <=100.")
Note: You can also manually add skip logic or validation logic in XLS Form Code.

This is a condition under which an a response is considered invalid (as defined in the constraint column).


Validation Criteria determines whether data is valid.

This allows for edit checks, which you can define as soft checks or hard checks.

If the expression provided in this cell is FALSE, the constraint_message displays.

For example, if this item value must be between 10 and 60, enter the following (in expressions, . (dot) represents the current item value):

. >= 10 and . <= 60

To reference other item values, use the following syntax:

${item_name} operator value

Use and/or logic as needed. For example:

${sysbp} >=130 and . >= 10 and . <= 60

You can also compare date fields against today().

For example, to display a message if the date of an adverse event (AEDATE) is in the future, the constraint on the AEDATE field would be:

.<=today()

Note: This column supports the syntax as defined in the required, calculations, or relevant columns.
Constraint MessageA message stating that data is invalid and/or explaining why it is invalid (e.g. "Pulse is outside normal range.")

If you provide a constraint, you can include a message that explains why the answer provided is not acceptable.

The message displays if the constraint expression is FALSE.

For example, If you had the following constraint on the Pulse item:

.>= 60 and .<=100

and a constraint_message of:

Pulse is outside of the normal range.

If someone entered a Pulse of 40,

Pulse is outside of the normal range.

would display on the form.
A message stating that data is invalid and/or explaining why it is invalid (e.g. "Pulse is outside normal range.")

If you provide a constraint, you can include a message that explains why the answer provided is not acceptable.

The message displays if the constraint expression is FALSE.

For example, If you had the following constraint on the Pulse item:

.>= 60 and .<=100

and a constraint_message of:

Pulse is outside of the normal range.

If someone entered a Pulse of 40,

Pulse is outside of the normal range.

would display on the form.
Constraint TypeN/Abind::oc:constraint-type

Determines whether you can override the constraint. To do this, you must add a column to the survey sheet and type strict. If left blank or not included, the user can override the requirement.
Contact DataDisplays contact data on Form.

In the Use as External Value field, select contactdata. Save your draft and exit. Then re-enter Form Designer, and select the types of contact data you want to display.
bind::oc:contactdata

Displays contact data on Form.

1.3.2 Events & Forms

Definitions:

An Event is a group of Forms that are used in your Study. An event might or might not be connected to a real-world visit.

A Form or eCRF (electronic Case Report From) is a group of fields for collecting Participant data.

Examples:

An Event could be a follow-up visit that occurs during a study.

Form could be used to record a Participants vital signs, capture a patients informed consent, track drug accountability, etc.

Study Designer contains a set of features that allow you to define, configure, and manage Events for your Study.

Events

 Each Event can be Defined as One of the Following Types:

  • Visit-Based: An Event that is scheduled to occur within the study and is associated with a visit date.

  • Common: An Event that isn’t necessarily associated with a visit but may occur any time throughout the study.

In a typical clinical trial, most Events are defined as Visit-Based Events, such as: Week 2, Week 6, and Monthly Follow-up, in which the Week 2 visit occurs two weeks after the Baseline visit, the Week 6 visit occurs six weeks after Baseline, etc. These visits are associated with a schedule that is outlined in the Study protocol, and each visit has a specific set of Forms that are collected.

Common Events are used to collect information that is not necessarily related to a scheduled visit date. For example, Adverse Event (AE), Concomitant Medication (ConMed), or Early Termination Events.

Common Events can be defined as either Repeating Events (e.g. AEs and ConMeds, since Participants might have more than one AE or ConMed) or Non-Repeating Events (e.g. Early Termination, since a Participant can only terminate once.)

Icons

In Study Designer, one or multiple icons appear after the name of the Event.

IconEvent TypeDescriptionExample(s)
Visit-BasedAn event that is associated with a visit date. The event can be repeating or non-repeating.Week 2 Visit (non-repeating);
Monthly Follow-Up for Disease-Free Survival (repeating)
CommonAn event that is not necessarily associated with a visit date.Early Withdrawl or Termination (non-repeating);
Adverse Events (repeating)
RepeatingAn event that repeats in your study, either a known or unknown, number of times.
This icon will appear adjacent to one of the previous two when an event is a repeating event.
Concomitant Medications

To Add an Event to a Study:

  1. Click +Add an Event.
  2. Enter a name for your Event.
  3. To edit details, click on the name of the Event.
  4. Enter values into fields, as needed.
  5. Click the Save button.

To Edit Settings for an Event/Form:

  1. Click the name of the Event.
  2. Change settings as needed.

Warning: Once you have moved your study to Production, you cannot change the Event to Repeating/Non-Repeating or Visit-Based/Common.

To Copy an Event:

  1. Click on the Menu button next to the name of the Event.
  2. Select Copy.

Note: When you copy an Event, any changes you make to one Event is applied to the copy.

To Archive an Event:

  1. Click on the Menu button next to the name of the Event.
  2. Select Archive.

Note: Archiving an Event removes the Event and all associated Forms from the study. If a study was previously published, the Event was archived, and the study was republished, that Event is no longer available within the study. However, archived Events can be restored at any time. If data was entered prior to the Event being archived, when a user views a Form in the Event This event has been archived appears at the top of the Form.

To Restore an Event:

  1. Click the Archived Items button in the header bar.
  2. Click the Restore button next to an Event you want to restore.

Note: Restoring an Event restores all its Forms. You can restore an Event with only a specific Form by clicking the Restore button next to the Form.

Forms

You can use Form Designer, a drag-and-drop interface that allows you to add questions and other item types to your Form, or you can use the Form Template, a pre-formatted XLS spreadsheet that allows you to enter data for your Form.

If you use Form Designer, you can add questions manually or select questions from the Content Library.

If you use the Form Template, you can either start with a blank Form Template and add data, or download a Form from Samples Forms, which you can either edit or use as is. 

You can also use both Form Designer and the Form Template. 

Warning: If you use both, be aware that if you start with a Form Template, edit the Form in Form Designer, and then try to download the XLS spreadsheet again, it will be formatted differently from the original.

For more information on creating Forms, see Using Form Designer or Using the Form Template.

To Download the Form Template:

In Study Designer, click the Form Template button in the header to download the Form Template.

Best Practice: If you have previously downloaded the Form Template, make sure to download it again to get the most recent version.

To Upload a Form Definition Spreadsheet:

  1. Click the Form card.
  2. Click the Upload button to upload a Form.
  3. (Optional) Click the Preview button to preview a Form.

To Enter Form Designer:

  1. Click the Form Card.
  2. Click the Design button.

To Preview a Form:

Click the Preview button on the Form card to view and test your Form, including edit checks, conditional fields, and calculations.

Note: Cross-form logic does not function as it does in Study Runner (i.e. the published study). You cannot save data in Preview mode, and the Close and Complete buttons do not appear.

If the Participate Module has been activated, and you select the Form Property of Participate Form, this option appears as Preview (as a Participant).

To Copy a Form to another Event:

  1. Click the Form card.
  2. Click the Menu button in the corner of the Form.
  3. Select Copy To.

To Archive a Form:

  1. Click the Form card.
  2. Click the Menu button in the corner of the Form.
  3. Select Archive.

Note: Archiving a Form removes the Form from the associated Event. The same Form can be used for multiple Events. In this case, archiving the Form in one Event does not have any impact on the Form in another Event. You can view archived forms in the study but they are no longer available for edit. Data in archived forms is not included in extracts

To Restore a Form:

  1. Click the Archived Items button in the header.
  2. Select Forms.
  3. Click the Restore button next to the Form you want to restore.

To Restore a Form Version:

  1. Click the Archived Items button in the header.
  2. Select Forms.
  3. Click the Restore button next to the Form version you want to restore. 

Form Properties

Forms can be Hidden, Required, and/or a Participate Form.

IconForm PropertyDescriptionExample
HiddenThe Form is hidden at the site level but is accessible from the study level.This is usually used when you want to import data rather thanentering it directly in the user interface to prevent site users from viewing or changing data.
RequiredThe Form must be completed in order for the Event to be completed.A Participant would be required to complete a consent Form to participate in the study.
Participate FormAllows the Participant to enter their own data with the use of OpenClinica Participate. (This checkbox is not available if the Participate module has not been activated.)A Participant might be asked to complete a questionnaire to evaluate potential side effects of a new medication.
(No Icon)Allow Add AnotherAllows the user to add a new instance of a Form in a common repeating Event. If the user clicks the Add Another checkbox, when they click Close or Complete, another instance of the Form automatically appears.A user might need to document multiple Concommitant Medications.

To Set Form Properties:

Click the checkboxes on the Form Card.

Best Practice:

Use Permission Tags instead of setting the Form to Hidden for more flexibility.

SDV Requirements

Forms may or may not require SDV (Source Data Verification), depending on the study protocol.

IconSDV RequirementDescription
(No Icon)Not ApplicableSDV is not applicable for this Form.
Not Required (Default)SDV is not required for the Form. SDV is not required for the study, but you can still perform SDV if you want. This is often used when 10% of Forms need to be SDVed.
Partial RequiredSome fields on the Form must be verified.
100% RequiredEvery field in the Form must be verified.

To Set SDV Requirements:

Click the drop-down menu next to SDV on the Form Card and select the requirement level you want to apply to the Form.

Form Drafts and Versions

When you initially upload a Form Template, your Form automatically becomes a version. This appears under Versions on the Form Card. 

You can make changes to the Form Template and upload new versions or overwrite the existing version.

When you create a Form in Form Designer and save it, it becomes a draft and appears under Drafts on the Form Card. You can make changes as needed, and if you have multiple drafts, the most recent draft is moved to the top of the list with the label, (latest).

When You Create a Draft, it Does Not:

  • Create a new version
  • Appear when you publish your study
  • Appear in the Activity Log

You can promote the draft to a version to include it in your study when you publish it.  

Warning: If you do not want the new Form to overwrite an existing Form, make sure to change the number in the Version number field on the Layout & Settings panel in Form Designer. 

Once a Form has been published to Production, it cannot be overwritten. You must create a new version, or an error appears.

Drafts

To Access the Drafts Menu:

Click the Menu button under Drafts to access a list of Version Options

To Add a Draft to Your Study/Make the Draft a Version:

  1. Click the Menu button next to the draft you want to add to your study/promote to a version.
  2. Select Add to Study.

To Edit the Draft in Form Designer:

  1. Click the Menu button next to the draft you want to edit in Form Designer.
  2. Select Design.

To Upload Media & External Lists: 

  1. Click the Menu button next to the draft you want to upload media and/or external lists to.
  2. Select Upload.

To Download the Draft:

  1. Click the Menu button next to the draft you want to download.
  2. Select Download.

Warning: If you upload the Form Template, edit it in Form Designer, and then download the form, the spreadsheet will be formatted differently from the original.

To Permanently Delete the Draft:

  1. Click the Menu button next to the draft you want to permanently delete.
  2. Select Discard.

Versions

To Access the Versions Menu:

Click the Menu button under Versions to access a list of Version Options.

To Edit the Version in Form Designer:

  1. Click the Menu button next to the version you want to edit in Form Designer.
  2. Select Design.

To Preview the Version:

  1. Click the Menu button next to the version you want to preview.
  2. Select Preview.

To Download the Version:

  1. Click the Menu button next to the version you want to download.
  2. Select Download.

1.3.3 Using Form Designer

Designing Forms is easy with Form Designer. You can still upload a Form Template spreadsheet (which is required for some of the more complex functions) but with Form Designer, you can create a form right in the user interface. See Using the Form Template for information about using the spreadsheet method of building forms.

Note: You can also upload a Form Template and then make changes in Form Designer. However, if you do this and try to download the form template again, you will loose some formatting inside the spreadsheet file (but it will still be fully functional).

Quick Start

1. Enter Form Designer:

  1. Click the Design button under your study card on the My Studies screen.
  2. To add a new Form, click +Add a Form. If you want to use an existing Form, go to the next step.
  3. Click the Form Card.
  4. Click the Design button to enter Form Designer.

2a.  Add an Item to the Form:

  1. Click the + button.
  2. Enter the text of your question.
  3. Click +Add Question.
  4. Select the icon for the type of response you want for the question.
  5. Customize your question settings, skip logic, and validation criteria as needed. For multiple choice questions, replace Option 1, Option 2, etc. with your choices.
  6. Repeat as needed.

2b.  Create a Group of Items:

  1. Click the item to select it. A blue outline appears to indicate that the item is selected.
  2. Click the Create group with selected questions button.
  3. Click the button within the group to add a new item or drag and drop an item into the group.
  4. Repeat as needed.

Note: You can also hold the Ctrl button, select multiple items, and then click the Create group with selected questions button. If you start to drag something and then decide not to move it, click the Esc button.

3.  Save Your Work

Click Save Draft to save your Form.

4.  Preview Your Form 

Click the Preview icon to preview your Form.

5.  Exit Form Designer

Click the  X to exit Form Designer.

6.  Add the Form to Your Study

  1. Click the Menu icon next to your draft.
  2. Select Add to Study.

Form Designer Details

Layouts

A Layout determines the appearance of a Form, specifically, how items appear on the Form.

You Can Specify a Layout to Display:

  • A single item per page or multiple items per page
  • Each item in a separate line or items in a grid

To Select a Layout:

Click Layout & Settings.

New Forms are set to Grid – multiple pages by default. Grids are ideal for adding multiple items in a single line.

Best Practices: 

  • In general, the Simple style is best for participant-facing Forms. The Grid style is useful for Forms with a lot of information and can deliver a better user experience for research professionals.
  • If you are not sure how many pages you want the Form to have, consider using the multiple page layout, as you can specify the number of pages  (including a single page) while the single page layout restricts you to one page.

Layout Options:

  • Simple – single page: Items appear in rows on a single page. In the Form Definition spreadsheet, this is configured by leaving the Style column blank.
  • Simple – multiple pages: Items appear in rows with each item on a separate page. In the Form Definition spreadsheet, this is configured by entering pages in the Style column.
  • Grid – single page: Items appear in columns on a single page. In the Form Definition spreadsheet, this is configured by entering theme-grid in the Style column.
  • Grid – multiple pages: Items appear in columns with each on a separate page (default). In the Form Definition spreadsheet, this is configured by entering pages theme-grid in the Style column.

Icons

The following icons appear on in the upper-left corner of the Form Designer screen:

IconAction
Preview Form
Expand/Collapse Questions
Create Group with Selected Questions
Delete Selected Items
Duplicate Selected Questions

The following icons appear on the right-hand side of each item:

IconAction
View/Change Question Settings

Note: You can also click this icon to expand/collapse settings
Delete Question

Note: This action cannot be undone
Duplicate Question
Add Question to Library

Layout Groups

Layout groups are a set of items that are grouped together on a Form. This feature is optional, and you can decide to include/exclude layout groups based on how you want the Form to look. These should not be confused with item groups, which are internal groups used in the database and data extracts.

To group items together, select each item on the top left item type icon, and then click the Group button. Once a group has been created, you can drag-and-drop items into that group.

To use group settings, click the Settings (Gear) button in the group header.

Within Group Settings, You Can:

  • Make items in the group appear on the same page
  • Specify the number of columns of items in the group
  • Create a repeating group
  • Define skip logic for the entire group

Content Library

Use the Content Library to add pre-made items to your forms. Instead of creating the same item each time you want to add it to a form, save the item or group of items in the Content Library to add it to the form instantly. For more information, see: Content Library.

Preview

Click the Preview button to preview your form.

Versions and Drafts

Click the Save Draft button in the upper right-hand corner to save your Form. This does not:

  • Create a new version
  • Include the draft when you publish your study
  • Appear on the Activity Log

Your updated design appears on your Form card in Study Designer under Drafts. Your draft is labelled (latest), and if you have multiple drafts, it is moved to the top of the list.

To Create Multiple Drafts:

  1. Open the Form in Form Designer. 
  2. Click Layout & Settings, and change the value in the Version number field.
  3. Click Save Draft.
  4. Repeat the process for each draft.

To Discard a Draft:

Click the Menu button next to the draft you want to delete, and selecting Discard.

Note: Discarded drafts are not retrievable. 

To Save a New Version:

  1. Click Layout & Settings, and change the number in the Version number field.
  2. Click Save Draft.
  3. Exit Form Designer.
  4. Click the Menu icon next to the draft you want to make a version.
  5. Select Add to Study. Your Form becomes a version, and is no longer displayed in the Drafts section of the Form Card in Study Designer. This version is included when you publish your study.

To Overwrite an Existing Version:

  1. Do not change the version number.
  2. Click Save Draft.
  3. Exit Form Designer.
  4. Click the Menu icon next to the draft you want to make a version.
  5. Select Add to Study. Your pre-existing Form version is replaced by your new version, and is no longer displayed in the Drafts section of the Form Card in Study Designer. This version is included when you publish your study.

Note: If you want to make a new version of a Form (and not overwrite an existing Form), make sure to change the version number in the Layout & Settings panel.

Form Designer Limitations

Currently, Form Designer does not support all of the functionality that is available in OpenClinica Forms. Instead, use the Form Template to take advantage of these features. Specifically:

  • You cannot use cross-form logic in Form Designer.
  • You can add edit checks in Form Designer but hard edit checks must be defined in the Form Template.
  • There is no functionality for cascading selects (i.e. you cannot restrict the list of options available in the next item based on the previous selection. You can still add conditional fields to determine whether the next item appears at all.)

Form Designer and Form Template Fields

Click the images to enlarge them.

FieldForm DesignerForm Template
Form Title
The form title appears at the top of the data entry page.
You can use alphanumeric characters, special characters (e.g. & # $ ^ _), and spacesYou can use alphanumeric characters, special characters (e.g. & # $ ^ _), and spaces.
Form ID
A unique identifier used as an internal reference when the form is uploaded.

This value is not visible to end-users.
Alphanumeric characters and underscores are permitted; no spaces.
Alphanumeric characters and underscores are permitted; no spaces.
Form Version
A unique identifier for an iteration of a given form (including changes to items, form logic, etc.).
You must change the version number if you want to create a new version of your form. Otherwise, the form overwrites the existing version. In the TEST environment, you cannot overwrite the Type or Item Group for an item or move an item in or out of a repeating group.

Saving your Form as a draft does not create a new version, but you can later promote a draft to a version using the Add to Study menu option on the Form card in Study Designer.
In the Test environment you can overwrite versions for changes to anything except the following features (these require a new form or a new item name):

  • Data type (the type column of the survey sheet)
  • Item group (the bind::oc:itemgroup column of the survey sheet)
  • Moving an item into or out of a repeating group


In the Production environment you must have a unique version identifier each time you upload a modification to the form.
Form Style
This specifies the layout and appearance of the form, primarily dealing with how the items are displayed (each question on a separate line, or a grid, and whether on a single page or multiple pages by groups).
There are four styles to choose from:

  • Simple - single page: Items appear in rows on a single page.

  • Simple - multiple pages: Items appear in rows with the other items in their groups on, each group on a separate page.

  • Grid - single page: Items appear together as a group but can have multiple questions appearing in the same row as columns; this is defined in the individual question settings.

  • Grid - multiple pages: The same as Grid - single page but each group of items will be displayed on its own page.


Note: If you group items together and click the "Show all questions in this group on the same screen" check box, items in the group appear on the same page, overriding a multiple pages setting.
You can leave this column blank or select from three options:

If left blank: Each question is on a separate line on the same page. [Simple - single page]

  • pages:One question or group of questions per page, with each question on a separate line. [Simple - multiple pages]

  • theme-grid: All groups of questions will appear on a single page, with all items displayed in table format. [Grid - multiple pages]

  • pages theme-grid: One question or group of questions per page with all items displayed in table format. [Grid - single page]


  • Note: When using Form Template, question groups (referenced above) are defined on the survey worksheet. When combined with the field-list option of the appearance column on the survey worksheet, you can control the display of questions and the structure of grids. See the entry on appearance below for more information.
NamespacesN/AThe 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 ReferencesN/AYou can use this column to decrease form 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 this case, the 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

You could also leave the cell blank, and your cross-form logic would work as expected, but the form would likely have slower performance.

Note: \If you enter an invalid value in this cell, 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.
Question Text/LabelThis is the text that appears in the Form for an item/question.
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
Enter Question Hint/HintInformative text that appears on the Form to help the user.


For example, “Please provide weight in kilograms.”

Hints appear in italics under the question label.
Informative text displayed on the form to help the user.

For example, Please provide weight in kilograms.

Hints display in italics under the question label.
Item Name/NameThe internal name of the item, as used in the database. This is used to generate the item object identifier (OID)This does not appear during data entry. Alphanumeric characters and underscores are allowed.
The unique name of the item. This is not displayed during data entry, but is how the data is referenced in the database.

Allows alphanumeric characters and underscores; spaces are not allowed. It is recommended that only lowercase letters, digits, and underscores are used in item names.

Once an item name is defined in this spreadsheet and the form is uploaded into OpenClinica, the name should not be changed to use different letter case when the form is uploaded again.

For example, if item1 is part of the first form upload, this name should not be changed to ITEM1 or Item1 when the form is subsequently uploaded. Any change from/to upper/lower case in an item name will result in a form or publish error.
Item GroupThe internal name of the group that the item is in, as used in the database. This is used to generate the item object identifier (OID). Alphanumeric characters and underscores are allowed; spaces are not allowed.
The name of the group to which you are assigning the item in the underlying database. This becomes the item group object identifier (OID).

Alphanumeric characters and underscores are allowed; spaces are not allowed. It is recommended that only lowercase letters, digits, and underscores are used in itemgroup names.

The itemgroup name does not have to correspond to the begin/end group names defined in the type column.

Begin group/repeat, end group/repeat, and note types should not have a value in the bind::oc:itemgroup cell.

All items in a repeating group must have the same itemgroup name. That itemgroup name cannot be used by other items that are outside that repeating group.

Once an itemgroup name is defined in this spreadsheet and the form is uploaded into OpenClinica, the itemgroup name should not be changed to use different letter case when the form is uploaded again.

For example, if group1 is part of the first form upload, this should not be changed to GROUP1 or Group1 when the form is subsequently uploaded. Any change from/to upper/lower case in an itemgroup name will result in a form or publish error.
TypeThe data type of the item (e.g. select one, select multiple, etc.)

  • Single-select: Allows the user to select one response from a list defined in the Form. Enter options in the Item Details.

  • Single-select (external list): Not available in Form Designer.

  • Multi-select: Allows the user to select one or more responses from a list defined in the Form. Enter options in the Item Details.

  • Text: Allows the user to enter a text value. Select the text icon. Text is up to 3,999 characters.

  • Integer: Allows the user to enter an integer value. Select the integer icon.

  • Decimal: Allows the user to enter a decimal value. Select the decimal icon.

  • Calculate: Calculates a value and does not display it to the user by default. Select the calculate icon.

  • Date: Allows the user to enter a date value. Select the date icon.

  • Note: Displays a message to the user without collecting a value. Select the note icon.

  • File: Allows the user to attach a file. Select the file icon.

  • Image: Allows the user to attach a .png or .gif file. Select the image icon.

  • Audio: Allows the user to attach an audio file. Select the audio icon.

  • Video: Allows the user to attach a video file. Select the video icon.

  • Layout Group (non-repeating): Allows users to group items together to alter the layout of the Form. Select one or more items and click the Group button.

  • Layout Group (repeating): Allows user to group items together to alter the layout of the Form and allow the user to enter values for the items multiple times, if necessary. Select one or more items and click the Group button. Then click the Settings (Gear) icon for the group and click the Repeat this group if necessary check box.


The data type of the item (e.g. select one, select multiple, etc.)

  • Single-select: Allows the user to select one response from a list defined in the Form. On the survey sheet, enter select_one xxxxx in the type column, and enter the same xxxxx in the name column. On the choices sheet, define options in the label and name columns.

  • Single-select (external list): Allows the user to select one response from a list defined in a CSV file. On the survey sheet, enter select_one_from_file xxxxx.csv in the type column, and enter the same xxxxx in the name column. This is ideal for long lists.

  • Multi-select: Allows the user to select one or more responses from a list defined in the Form. On the survey sheet, type select_multiple xxxxx in the type column, and enter the same xxxxx in the name column. On the choices sheet, define options in the label and name columns.

  • Text: Allows the user to enter a text value. On the survey sheet, enter text in the type column. Text is up to 3,999 characters.

  • Integer: Allows the user to enter an integer value. On the survey sheet, enter integer in the type column.

  • Decimal: Allows the user to enter a decimal value. On the survey sheet, enter decimal in the type column.

  • Calculate: Calculates a value and does not display it to the user by default. On the survey sheet, enter calculate in the type column. Use a type of note to display the answer.

  • Date: Allows the user to enter a date value. On the survey sheet, enter date in the type column.

  • Note:Displays a message to the user without collecting a value. On the survey sheet, enter note in the type column.

  • File: Allows the user to attach a file. On the survey sheet, enter file in the type column.
  • Image: Allows the user to attach a .png or .gif file. On the survey sheet, enter image in the type column.

  • Audio: Allows the user to attach an audio file. On the survey sheet, enter audio in the type column.

  • Video: Allows the user to attach a video file. On the survey sheet, enter video in the type column.

  • Layout Group (non-repeating): Allows users to group items together to alter the layout of the Form. On the survey sheet, enter begin group in the type column to indicate the beginning of a group of items and enter end group in the type column to indicate the end of the group of items.

  • Layout Group (repeating): Allows user to group items together to alter the layout of the Form and allow the user to enter values for the items multiple times, if necessary. On the survey sheet, enter begin repeat in the type column to indicate the beginning of a repeated group of items and enter end repeat in the type column to indicate the end of a repeated group of items.


Item Brief DescriptionA short description of the item that can be used to reference it in tables.

This description can be up to 40 characters. You cannot use special characters.

If this is not defined for an item in a table, the Item Name appears instead.
A short description of the item that can be used to reference it in tables.

This description can be up to 40 characters. You cannot use special characters.

If this is not defined for an item in a table, the Item Name appears instead.
Item DescriptionA long description of the item that can be used to define the data that the item/question contains. This is not displayed on the Form during data data entry. The text can be up to 3,999 characters. You cannot use special characters. The description is included in some data extract formats.
A long description of the item that can be used to define the data that the item/question contains. This is not displayed on the Form during data data entry. The text can be up to 3,999 characters. You cannot use special characters. The description is included in some data extract formats.
AppearanceThis determines how each item appears based on its Type. Items do not have a specific appearance by default. This setting is optional.

Note: the type,other indicates that instead of selecting the option, other, you can enter the appearance directly in the field. other also appears as an option for the item types indicated.

You can specify width for any item. (See Width)

Single select / Multi-select

  • default: Allows the user to select one or multiple responses.

  • minimal: Displays answer choices in a drop-down menu rather than the default display of radio buttons (for select_one and select_multiple) or check boxes (for select_multiple)

  • columns or columns no-buttons: Arranges answer choices horizontally in columns based on screen size (Displays radio buttons or check boxes unless you specify no-buttons, which displays text or images.)

  • columns-pack or columns-pack no-buttons: Arranges image answer choices side-by-side, close together (Displays radio buttons or check boxes unless you specify no-buttons, which displays text or images.)

  • columns-n or no-buttons: Arranges image answer choices in column Format with n columns (n <= 10) (Displays radio buttons or check boxes unless you specify no-buttons, which displays text or images.)

  • likert: Displays answer choices as a Likert scale (This is not available for select_multiple items.)

  • image-map: Displays an image (must be uploaded with the Form); allows user to select by clicking part of the image (e.g., a select_multiple specific parts on a body map). Only files with an extension of .svg are permitted, and the file name must be listed in the image column for the item

  • autocomplete:Displays options that match the information you enter as you type.

  • other: Select other and enter another appearance or define the column width.


text

  • default: Allows the user to enter a single line of text.

  • multiline: Allows the user to enter text in a text box multiple lines long (word wrap).

  • other: Select other and enter another appearance or define the column width.


integer

  • default: Allows the user to enter a whole number.

  • other: Enter another appearance or define the column width.

  • analog scale: Allows the user to input an integer using a Visual Analogue Scale. Select the appropriate option for how you want to display the scale: analog horizontal, analog horizontal no-ticks, analog vertical, analog vertical no-ticks, and analog-scale vertical show-scale. The scale is always 0-100. In Form Designer, type this into the Appearance field.


decimal

  • default: Allows the user to enter a decimal number.

  • other: Enter another appearance or define the column width.


calculate

  • default: This occurs internally, so it does not have an appearance. You can use the note type to display the result.


Date

  • default: Allows the user to enter a full date: day, month, and year.

  • month-year: Allows the user to enter a partial date: month and year only.

  • year: Allows the user to enter a partial date: year only.

  • other: Select other and enter another appearance or define the column width.


note

  • default: Displays a note.

  • other: Enter another appearance or define the column width.


file

  • default: Allows the user to upload a file.

  • other: Enter another appearance or define the column width.

image

  • default: Allows the user to upload an image. A preview appears.

  • draw: Allows the user to draw a picture on the screen, using the mouse or a touch screen

  • annotate: Allows the user to upload an image and then draw on it, using the mouse or a touch screen

  • signature: Allows the user to draw a signature on the screen using the mouse or a touch screen. This is not a 21 CFR Part 11-compliant signature.

  • other: Select other and enter another appearance or define the column width.


audio

  • default: Allows the user to upload an audio file. A preview appears.

  • other: Enter another appearance or define the column width.


video

  • default: Allows the user to upload a video file. A preview appears.

  • other: Enter another appearance or define the column width.


Layout groups

  • default: Allows the user to group items without altering how they are displayed.

  • field-list: Displays an entire group of questions together on one page. In Form Designer, check the box next to the Show all questions in this group on the same screen.

  • table-list: Displays a common list of labels as a top row, and then each field in the group displays columns of radio buttons or check boxes.



Note: Items with no label or hint are treated as background calculations.
This means you can set the data type of a background calculation item as needed. For example, you can have an integer type item with a calculation but no label or hint. It does not appear on the form and performs a background calculation.

This determines how each item appears based on its Type. Items do not have a specific appearance by default. This setting is optional.

Note: the type,other indicates that instead of selecting the option, other, you can enter the appearance directly in the field. other also appears as an option for the item types indicated.

You can specify width for any item. (See Width)

Single select / Multi-select

  • default: Allows the user to select one or multiple responses.

  • minimal: Displays answer choices in a drop-down menu rather than the default display of radio buttons (for select_one and select_multiple) or check boxes (for select_multiple)

  • columns or columns no-buttons: Arranges answer choices horizontally in columns based on screen size (Displays radio buttons or check boxes unless you specify no-buttons, which displays text or images.)

  • columns-pack or columns-pack no-buttons: Arranges image answer choices side-by-side, close together (Displays radio buttons or check boxes unless you specify no-buttons, which displays text or images.)

  • columns-n or no-buttons: Arranges image answer choices in column Format with n columns (n <= 10) (Displays radio buttons or check boxes unless you specify no-buttons, which displays text or images.)

  • likert: Displays answer choices as a Likert scale (This is not available for select_multiple items.)

  • image-map: Displays an image (must be uploaded with the Form); allows user to select by clicking part of the image (e.g., a select_multiple specific parts on a body map). Only files with an extension of .svg are permitted, and the file name must be listed in the image column for the item

  • autocomplete:Displays options that match the information you enter as you type.

  • other: Select other and enter another appearance or define the column width.


text

  • default: Allows the user to enter a single line of text.

  • multiline: Allows the user to enter text in a text box multiple lines long (word wrap).

  • other: Select other and enter another appearance or define the column width.


integer

  • default: Allows the user to enter a whole number.

  • other: Enter another appearance or define the column width.

  • analog scale: Allows the user to input an integer using a Visual Analogue Scale. Select the appropriate option for how you want to display the scale: analog horizontal, analog horizontal no-ticks, analog vertical, analog vertical no-ticks and analog-scale vertical show-scale. The scale is always 0-100. In Form Designer, type this into the Appearance field.


decimal

  • default: Allows the user to enter a decimal number.

  • other: Enter another appearance or define the column width.


calculate

  • default: This occurs internally, so it does not have an appearance. You can use the note type to display the result.


Date

  • default: Allows the user to enter a full date: day, month, and year.

  • month-year: Allows the user to enter a partial date: month and year only.

  • year: Allows the user to enter a partial date: year only.

  • other: Select other and enter another appearance or define the column width.


note

  • default: Displays a note.

  • other: Enter another appearance or define the column width.


file

  • default: Allows the user to upload a file.

  • other: Enter another appearance or define the column width.

image

  • default: Allows the user to upload an image. A preview appears.

  • draw: Allows the user to draw a picture on the screen, using the mouse or a touch screen

  • annotate: Allows the user to upload an image and then draw on it, using the mouse or a touch screen

  • signature: Allows the user to draw a signature on the screen using the mouse or a touch screen. This is not a 21 CFR Part 11-compliant signature.

  • other: Select other and enter another appearance or define the column width.


audio

  • default: Allows the user to upload an audio file. A preview appears.

  • other: Enter another appearance or define the column width.


video

  • default: Allows the user to upload a video file. A preview appears.

  • other: Enter another appearance or define the column width.


Layout groups

  • default: Allows the user to group items without altering how they are displayed.

  • field-list: Displays an entire group of questions together on one page. In Form Designer, check the box next to the Show all questions in this group on the same screen.

  • table-list: Displays a common list of labels as a top row, and then each field in the group displays columns of radio buttons or check boxes.


Note: Items with no label or hint are treated as background calculations.
This means you can set the data type of a background calculation item as needed. For example, you can have an integer type item with a calculation but no label or hint. It does not appear on the form and performs a background calculation.
WidthFor an item or group of items on a grid form, you can control how many columns appear on each row by specifying the width w#.

If you specified a width of w6 for a layout group, it takes up the entire width of the grid.

If you specified w1 for a single item in the group, there would be one small column (1) and another large column (5).
For an item or group of items on a grid form, you can control how many columns appear on each row by specifying the width w#.

If you specified a width of w6 for a layout group, it takes up the entire width of the grid.

If you specified w1 for a single item in the group, there would be one small column (1) and another large column (5).
RequiredThis specifies whether a user is required to enter a response to the item to proceed with data entry.

Select Always, Never, or Conditional to specify whether/when a response to this item/question is required. If you select Conditional, you must enter a conditional value.
This specifies whether a user is required to enter a response to the item to proceed with data entry.

For required fields, type yes in the required column on the survey sheet. For conditionally required fields, enter a condition, as defined in the relevant column of the survey sheet.

For example, if Number of packs per day is required if Does the subject smoke? is answered yes, enter:

${smoke} = 1

Note: This column supports the syntax as defined in the calculation, constraint, or relevant columns of this worksheet. Refer to those column comments for additional examples.
Required MessageN/AIf the item is required, you can include a message that explains why the answer is needed.

If no message is entered here, the default message, This field is required, will be used.

If the form would be easier for the data entry user to fill out with a different message (for example, noting that an item is a primary data point that cannot be left blank or that an item is required due to a prior response), it can be defined in this column.
Required TypeN/AThis determines whether you can override the requirement. To do this, you must add a column to the survey sheet and type strict. If left blank or not included, the user can override the requirement.
Use External ValueThis item is a value used for logic or calculations.

clinicaldata is used for cross-Form, cross-event, or event level calculations.

contactdata displays contact data on a form.

If you enter contactdata, you must add a column called instance::oc:contactdata. That column must contain one of the following values to indicate which contact information it is collecting: firstname, lastname, email, mobilenumber, secondaryid.
This item is a value used for logic or calculations.

clinicaldata is used for cross-Form, cross-event, or event level calculations.

contactdata displays contact data on a form.

If you enter contactdata, you must add a column called instance::oc:contactdata. That column must contain one of the following values to indicate which contact information it is collecting: firstname, lastname, email, mobilenumber, secondaryid.
Read OnlyThis specifies that you cannot enter data for an item. This can be used for the types of text, calculations, etc.
This specifies that you cannot enter data for an item. This can be used for the types of text, calculations, etc.
CalculationAn expression used to calculate a value, usually using the values of preceding questions on the current Form. This can also be used for Cross-form calculations.

. is used to represent the current field's value.

${name} is used to reference a different item value on this Form, where name is the name of the other item.

You can use parentheses.

The following operators can be used:

  • Addition: +

  • Subtraction: -

  • Multiplication: *

  • Division: div

  • Equal: =

  • Not Equal: !=

  • Less than: <

  • Less than or equal to: <=

  • Greater than: >

  • Greater than or equal to: >=>/li>
    And: and

  • Or: or


For example, to calculate Mean Arterial blood Pressure (MAP) based on the items systolic and diastolic:

(systolic + (2*diastolic)) div 3

Calculations cannot be used for items with type of note.

If calculation is used for any type except calculate, that field must have Read Only set to yes.
An expression used to calculate a value, usually using the values of preceding questions on the current Form. This can also be used for Cross-form calculations.

. is used to represent the current field's value.

${name} is used to reference a different item value on this Form, where name is the name of the other item.

You can use parentheses.

The following operators can be used:

  • Addition: +

  • Subtraction: -

  • Multiplication: *

  • Division: div

  • Equal: =

  • Not Equal: !=

  • Less than: <

  • Less than or equal to: <=

  • Greater than: >

  • Greater than or equal to: >=>/li>
    And: and

  • Or: or


For example, to calculate Mean Arterial blood Pressure (MAP) based on the items systolic and diastolic:

(systolic + (2*diastolic)) div 3

Calculations cannot be used for items with type of note.

If calculation is used for any type except calculate, that field must have Read Only set to yes.
ImageN/AAllows 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 spreadsheet or you can add it to a draft using the Upload Media & External Lists option.
Choice FilterN/AAn expression for using filters for cascading selects (i.e. items are filtered based on responses to other items.)
Response Text/LabelThe question text to be displayed on the data entry form. This field allows alphanumeric characters.

Add a line break where you want using Ctrl-Enter or Ctrl-Alt-Enter (Windows) Option+Enter (Mac).

Styling prompts can be added to format your text as follows:

*text* displays as italics

**text** displays as bold

***text*** displays as bold italics

Increase font size by preceding the text with one to six hash tags. # makes the text the largest possible size, ## makes the text the smallest possible size. Sizes that display may vary for note vs. item vs. group labels.

Colors can be added as follows:

text for red text. You can use the hex code for the color of your choice. (You can look up hex codes by searching for css codes on the internet.)
The question text to be displayed on the data entry form. This field allows alphanumeric characters.

Add a line break where you want using Ctrl-Enter or Ctrl-Alt-Enter (Windows) Option+Enter (Mac).

Styling prompts can be added to format your text as follows:

*text* displays as italics

**text** displays as bold

***text*** displays as bold italics

Increase font size by preceding the text with one to six hash tags. # makes the text the largest possible size, ## makes the text the smallest possible size. Sizes that display may vary for note vs. item vs. group labels.

Colors can be added as follows:

text for red text. You can use the hex code for the color of your choice. (You can look up hex codes by searching for css codes on the internet.)
Value/NameThe unique code value stored in the database that corresponds to each answer choice (e.g. 1=Yes).

These codes are generated automatically but can be changed.
The unique code value stored in the database that corresponds to each answer choice (e.g. 1=Yes).
Image (Choice)N/AProvide an image file name (e.g. a file with an extension of .png or .jpg) that can be used as a response option. For example, Wong-Baker face images for pain scale choices. The image file must be uploaded at the same time that the Form Definition spreadsheet is uploaded into OpenClinica.
Filter ColumnN/AThe response values to filter by for cascading selects
List NameN/AThe 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
Item Name/NameThe unique internal name of the layout group used in the database. This is not displayed during data entry. Alphanumeric characters and underscores are allowed.
The unique internal name of the layout group used in the database. This is not displayed during data entry. Alphanumeric characters and underscores are allowed.
Show All Questions in this Group on the Same Screen/AppearanceClick this check box to make all items appear on the same screen (regardless of your layout selection.)
N/A
Repeat this group if NecessaryThis specifies that the group of items should be repeated.

Click this check box to make the selected group of questions a repeating group.
This uses begin repeat and end repeat in the Type column to specify that the group of items should be repeated.
Repeat CountN/AWhen 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.
Skip Logic / RelevantThis is a condition under which an item is skipped.

Enter a condition under which this item/question appears or is required.
This is a condition under which an item is skipped (as defined in the relevant column).

The item or group is only displayed if the provided expression evaluates to TRUE.

Use the following syntax:

${other question name} = value (for a numeric value)

or

${other question name} = 'value' (for a character value)

If the lead-in question uses a code list defined in the choices worksheet, use what is in the name column for that code list as the value.

For example, if you have two questions: Does the subject smoke? (item name = smoke) and How many packs per day? (item name=packs), the second question should only display if the answer to the first question is Yes.

If the first question (smoke) uses a code list defined in the choices worksheet as:

list_name label name
YN 1 Yes
YN 2 No

The relevant syntax for How many packs per day would be:

${smoke} = 1

For multi_select items, use the following syntax:

selected(${question name},value) (for a numeric value)

selected(${question name},'value') (for a character string)

Note: This column supports the syntax as defined in the required, calculations, or relevant columns.
Validation Criteria / ConstraintThis is a condition under which an a response is considered invalid.

Validation Criteria prevents users from entering invalid data. (e.g. "a Participant's pulse must be >=60 and <=100.")
Note: You can also manually add skip logic or validation logic in XLS Form Code.

This is a condition under which an a response is considered invalid (as defined in the constraint column).


Validation Criteria determines whether data is valid.

This allows for edit checks, which you can define as soft checks or hard checks.

If the expression provided in this cell is FALSE, the constraint_message displays.

For example, if this item value must be between 10 and 60, enter the following (in expressions, . (dot) represents the current item value):

. >= 10 and . <= 60

To reference other item values, use the following syntax:

${item_name} operator value

Use and/or logic as needed. For example:

${sysbp} >=130 and . >= 10 and . <= 60

You can also compare date fields against today().

For example, to display a message if the date of an adverse event (AEDATE) is in the future, the constraint on the AEDATE field would be:

.<=today()

Note: This column supports the syntax as defined in the required, calculations, or relevant columns.
Constraint MessageA message stating that data is invalid and/or explaining why it is invalid (e.g. "Pulse is outside normal range.")

If you provide a constraint, you can include a message that explains why the answer provided is not acceptable.

The message displays if the constraint expression is FALSE.

For example, If you had the following constraint on the Pulse item:

.>= 60 and .<=100

and a constraint_message of:

Pulse is outside of the normal range.

If someone entered a Pulse of 40,

Pulse is outside of the normal range.

would display on the form.
A message stating that data is invalid and/or explaining why it is invalid (e.g. "Pulse is outside normal range.")

If you provide a constraint, you can include a message that explains why the answer provided is not acceptable.

The message displays if the constraint expression is FALSE.

For example, If you had the following constraint on the Pulse item:

.>= 60 and .<=100

and a constraint_message of:

Pulse is outside of the normal range.

If someone entered a Pulse of 40,

Pulse is outside of the normal range.

would display on the form.
Constraint TypeN/Abind::oc:constraint-type

Determines whether you can override the constraint. To do this, you must add a column to the survey sheet and type strict. If left blank or not included, the user can override the requirement.
Contact DataDisplays contact data on Form.

In the Use as External Value field, select contactdata. Save your draft and exit. Then re-enter Form Designer, and select the types of contact data you want to display.
bind::oc:contactdata

Displays contact data on Form.

1.3.4 Form Logic

Form logic includes:

  • calculations
  • cross-form logic
  • skip logic
  • constraints

Syntax

DescriptionSyntax
The current item’s value.
The value of another item${itemname}

Conditions

Values can be an item reference or the literal value of an item (e.g. yes or 1).

Note: You can use either the single quote or double quote, but the former is usually preferred for clarity. You would use the double quote if the string contained a single quote. If you want this condition to work with multiple choices, use the formula twice with and/or.

DescriptionSyntax
Numeric Value${itemname} = value
Character Value${itemname} = 'value'
${itemname} = "value"
Null Value${itemname} = ''
Multiple Select Numeric Value(s)selected(${itemname}, choicename)
Multiple Select Character Value(s)selected(${itemname}, 'choicename')

Operators

DescriptionSyntax
Addition+
Subtraction-
Multiplication*
Divisiondiv
Modulus (remainder)mod
Equal=
Not Equal!=
Less Than<
Less Than or Equal to<=
Greater Than>
Greater Than or Equal to>=
Order of Operations( )
Combine Alland
Combine Eitheror

Functions

DescriptionSyntax
Addsum
Conditionalif
Negationnot(expression)
Round Numberround
Concatenateconcat
Random Numberrandom
Substringsubstr
Powerpow

Calculations

Enter the formula from the Syntax column in the Calculation field (Form Designer) or the Calculate column (Form Template). Replace the items in brackets with the names of your own items.

CalculatesKeySyntax
BMI (adjusting for Metric or Imperial, and rounding to 2 decimal digits)weight = weight in lbs or kgs

height = height in cm or in

wh_units = weight and height units (1 for cm and kgs, 2 for in and lbs)
round(if(${wh_units}= 2 and ${weight}! = ''and ${height} != '', 703 * ${weight} div (pow(${height}, 2)), if(${wh_units} = 1 and ${weight} != '' and ${height} != '', 10000 * ${weight} div (pow(${height}, 2)), 0)), 2)
Calculates Mean Arterial Blood Pressure (MAP)systolic = systolic blood pressure

diastolic = systolic blood pressure
(systolic + (2 * diastolic)) div 3

Required

Enter the formula from the Syntax column in the field that appears when you select Conditional in the Required field (Form Designer) or the Required column (Form Template). Replace the items in brackets with the names of your own items.

DescriptionSyntax
Cancer Type${cancerdiagnosis} = yes

Skip Logic/Relevant

Enter the formula from the Syntax column in the field that appears when you select Skip Logic and click the ${} Manually enter your skip logic in XLSForm Code button (Form Designer) or the Relevant column (Form Template). Replace the items in brackets with the names of your own items.

Skip Logic/RelvantSyntax
Does Participant Smoke?${smoke} = yes

Validation Criteria/Constraint

Enter the formula from the Syntax column in the Constraint field (Form Designer) or the Constraint column (Form Template). Replace the items in brackets with the names of your own items.

Validation Criteria/ConstraintSyntax
No Future Dates.
Age Must be Between 1 and 100${age} > 1 and ${age} < 100
Must not exceed 100 charactersstring-length(.)<=100
Must be in 24-Hour Format (HH:MM)regex(., ’([01][0-9]|2[0-3]):[0-5][0-9]‘) and string-length(.) = 5

Advanced Form Logic

Hard Edit Checks (Form Template)

Hard edit checks are exclusive to the Form Template and can be used to enforce stricter standards on data entry. Because they can make data entry more difficult for users, it is recommended that they be used only when strictly necessary. 

All checks that are not explicitly defined as hard edit checks are soft edit checks in all Forms except for Participate Forms. In that case, all edit checks are automatically hard edit checks.

When a value is entered and it violates a hard check on an item, the value is rejected before it is stored, and the user will see a pop-up.

When a value is entered, and it causes a hard check to be violated on a different item, the value entered is saved as normal. In this case, the user will see an error message displayed on the item with the hard check, and it will have an orange background (distinct from the soft red background used for soft check error messages).

A user cannot navigate forward in the form or mark the form complete while a hard check error message is present.

A user can add a manual query or choose to add an autoquery to a hard check item in order to close the form. However, the query will not hide the hard check error message.

Special care must be taken when using relevant logic (hide/show) for an item with a hard required check. Once an item has a value, a hard required check will not allow the item to be cleared. 

Because of this, the item’s hard required logic must indicate that the item is required only when the item’s relevant logic is met. If this practice is not followed, the user may get into a state where they cannot clear an item even though that is the only way to make the data consistent with the relevant logic. 

For example, if the item (or the group it is in) has relevant logic ${yn_item} = 1, then the hard required logic must also include ${yn_item} = 1 to ensure that the form works as intended. That will enforce the hard required check when the item is relevant, but will not enforce the check when the item is not relevant.

To Make a Hard Edit Check for a Required Item:

  1. Click the survey tab in the Form Template spreadsheet.
  2. Add a column with the header bind::oc:requiredtype.
  3. Enter strict.

To Make a Hard Edit Check for a Constraint:

  1. Click the survey tab in the Form Template spreadsheet.
  2. Add a column with the header bind::oc:constrainttype.
  3. Enter strict.

Participant Contact Data

This feature is intended to supplement collection of contact information through the Participant Details screen. It allows this data to be captured, displayed, and updated directly on a form, including by Participants accessing the form using the Participate module. Contact data collected on a form is not stored with the rest of the form data but rather with the contact information to enforce access limits by user role.

In the Form Template:

  1. Create a text item in your form.
  2. in the bind::oc:external cell for that newly added item, select contactdata from the drop-down list.
  3. Add a column called instance::oc:contactdata. Enter one of the following values.
    • firstname – to collect first name
    • lastname – to collect last name
    • email – to collect email address
    • mobilenumber – to collect mobile phone number
    • secondaryid – to collect an alternate ID
  4. The constraint, constraint message, and constraint type (strict, see hard checks section) will automatically be set by the system to ensure data collected meets system requirements.
  5. The item must not have a value entered in the bind::oc:itemgroup column.
  6. You can define any label, hint, relevant, and required that you want for the item.

In Form Designer:

  1. In Form Designer, click the + button to add an item.
  2. Enter a name for the item.
  3. Select Text.
  4. In the Use External Value field, select contactdata.
  5. In the Contact Data Type field that appears, select:
    • firstname – to collect first name
    • lastname – to collect last name
    • email – to collect email address
    • mobilenumber – to collect mobile phone number
    • secondaryid – to collect an alternate ID
  6. If there is content in the Item Group field or the field has Validation Criteria, delete it.

Note: Only Clinical Research Coordinator, Investigator, and Participant users will be able to open a Form using a contactdata item or see data from it in extracts.

Items with contact data and items with other data should not be mixed on the same form due to these access limitations.

Mobile phone number is stored internally along with country code (for example +123 456789012345). Once a value has been collected, on either the form or from the Participant Details screen, it will be displayed in that format with country code (including +1 before US phone numbers). The form will permit phone number entry in either the +, country code, space,and number format or as strictly a 10-digit number that is assumed to be for country code +1.

Cross-Checks (Form Template)

Referencing item values across forms and/or events

Reference the following examples when checking data across events, Forms, repeating occurrences in a single event, or repeating occurrences in separate events. 

There are also examples for how to check specific values captured when a user adds a new Participant. 

The following steps apply all of the examples below, unless otherwise stated:

  1. Create an item with a type of calculate.
  2. In the bind::oc:external cell, for that newly added calculate field, select clinicaldata from the drop-down list.
  3. In the calculation cell for the new calculate item, copy and paste the appropriate sample text from the examples below, and replace the bold, italicized text with the OIDs (or object names) from your study. 
  4. Reference the new calculate field (as defined above) in any of the following cells to use the externally referenced value for display or in a logic expression:  
    • label
    • hint
    • calculation
    • constraint
    • required
    • relevant
  1. (Optional) To optimize performance, configure the crossform_references column on the survey sheet to include only the events that are needed for the cross-form logic on your form. Cross-form logic will work without this step, but the form will load more slowly. Simply enter a comma separated list of the Event OIDs used in your logic. Include “current_event” in the list if any logic on the form uses “[@OpenClinica:Current=’Yes’]”. 

For example, you would enter “SE_BASELINE,SE_VISIT2,current_event” if your form uses cross-form logic containing the Events, “SE_BASELINE”, “SE_VISIT2”, and “[@OpenClinica:Current=’Yes’]”. 

Notes:

  • Even if your logic references an Event by name instead of OID, you must include the Event OID in the list.
  • If you use any of the examples that reference OIDs, the study must first be published in order to generate OIDs. You can publish the study to Test, then locate and reference the OIDs as needed, and include those OIDs in the calculation field as indicated below.
  • You can reference object names instead of OIDs, but if the object name changes, you must update the calculation to include the updated object name. OIDs do not change for objects, so it is easier to maintain forms that include references to OIDs.
  • You can create any single calculation by using a combination of OIDs and object names.

Cross-check data against an item value in another event. Referencing the item value by item name

Add a calculate item. Include ‘clinicaldata’ in the bind::oc:external cell and add the following to the calculation cell, replacing the bold, italicized text with your specific object names:

instance(‘clinicaldata’)/ODM/ClinicalData/SubjectData/StudyEventData[@OpenClinica:EventName=’Event Name Here‘]/FormData[@OpenClinica:FormName=’Form Name Here‘]/ItemGroupData[@OpenClinica:ItemGroupName=’Item Group Name Here‘]/ItemData[@OpenClinica:ItemName=’Item Name Here‘]/@Value

Cross-check data against an item value in another event. Referencing the item value by OID

Add a calculate item. Include ‘clinicaldata’ in the bind::oc:external cell and add the following to the calculation cell, replacing the bold, italicized text with your specific OIDs:

instance(‘clinicaldata’)/ODM/ClinicalData/SubjectData/StudyEventData[@StudyEventOID=’Event OID Here‘]/FormData[@FormOID=’Form OID Here‘]/ItemGroupData[@ItemGroupOID=’Item Group OID Here‘]/ItemData[@ItemOID=’Item OID Here’]/@Value

Cross-check data against an item value in a different form that is in the same event as this form

Add a calculate item. Include ‘clinicaldata’ in the bind::oc:external cell and add the following to the calculation cell, replacing the bold, italicized text with your specific OIDs:

instance(‘clinicaldata’)/ODM/ClinicalData/SubjectData/StudyEventData[@OpenClinica:Current=’Yes’]/FormData[@FormOID=’Form OID Here‘]/ItemGroupData[@ItemGroupOID=’Item Group OID Here‘]/ItemData[@ItemOID=’Item OID Here‘]/@Value

Cross-check data against an item value in a specific repeat/row of a repeating group

Add a calculate item. Include ‘clinicaldata’ in the bind::oc:external cell and add the following to the calculation cell, replacing the bold, italicized text with your specific OIDs:

instance(‘clinicaldata’)/ODM/ClinicalData/SubjectData/StudyEventData[@StudyEventOID=’Event OID Here‘]/FormData[@FormOID=’Form OID Here‘]/ItemGroupData[@ItemGroupOID=’Item Group OID Here‘][Repeat Number Here]/ItemData[@ItemOID=’Item OID Here‘]/@Value

Cross-check data against a value from a specific event occurrence in a repeating event

Add a calculate item. Include ‘clinicaldata’ in the bind::oc:external cell and add the following to the calculation cell, replacing the bold, italicized text with your specific OIDs:

instance(‘clinicaldata’)/ODM/ClinicalData/SubjectData/StudyEventData[@StudyEventOID=’Event OID Here‘][Event Repeat Number Here]/FormData[@FormOID=’Form OID Here‘]/ItemGroupData[@ItemGroupOID=’Item Group OID Here‘]/ItemData[@ItemOID=’Item OID Here‘]/@Value

Cross-check data against the event start date for the current event

Add a calculate item. Include ‘clinicaldata’ in the bind::oc:external cell and add the following text to the calculation cell:

instance(‘clinicaldata’)/ODM/ClinicalData/SubjectData/StudyEventData[@OpenClinica:Current=’Yes’]/@OpenClinica:StartDate

Cross-check data against the event start date in a different event

You can add a calculate item to your form to store the User Role or Username of the current user. You can then control which note items that user can see on a form by referencing that calculate item in the relevant cell for the note item.

For example, you may have a note item on your form that provides instructions to the Monitor regarding what items must be verified for a form that only requires partial verification.

It is not necessary for any other user roles to see that note, so you can conditionally display the note to Monitors only. 

To do this, follow the steps below:

  1. Use the instructions below to Lookup User Role. 
  2. Include the note item with instructions for SDV. 
  3. In the relevant cell for the note item, reference the calculate item that now stores the current user’s role or username. 

For example, ${currentrole}=”Monitor” (where currentrole is the name of the calculate item you created)

Note: Only the standard roles are available for reference. If you created a custom role of “Junior Monitor” based on the Monitor role, this only references the standard Monitor role. In the future, custom role names will be available for reference as well.

Lookup User Role

Add a calculate item. Include ‘clinicaldata’ in the bind::oc:external cell and add the following text to the calculation cell:

instance(‘clinicaldata’)/ODM/ClinicalData/UserInfo/@OpenClinica:UserRole

Lookup Username

Add a calculate item. Include ‘clinicaldata’ in the bind::oc:external cell and add the following text to the calculation cell:

instance(‘clinicaldata’)/ODM/ClinicalData/UserInfo/@OpenClinica:UserName

Lookup Participant ID

Add a calculate item. Include ‘clinicaldata’ in the bind::oc:external cell and add the following text to the calculation cell:

instance(‘clinicaldata’)/ODM/ClinicalData/SubjectData/@OpenClinica:StudySubjectID

1.3.5 Functions

Functions can be used to validate syntax, calculate values, transform data, and control workflow. 

Much of the content below is borrowed and adapted under the Creative Commons license from Get ODK. Note: OpenClinica does not support every function listed on the Get ODK website. The functions below have been validated and tested in OpenClinica.

General functions
Functions for repeating data structures
Date and time functions
Math functions and number handling
String functions
Calculations


General Functions

Description:Evaluates expression, if the expression is true it returns or executes the then statement, if the expression evaluates to false it returns/executes the else statement.
Syntax:if(expression, then, else)
Example:if(${ae_death} = ‘yes’, ‘SAE’, if(${ae_hospital} = 'yes', 'SAE', if(...))) 

This nested if statement will eventually cascade through the entire SAE criteria list to see if any were answered 'Yes', and if so it will return 'SAE', if not then it will move to the next criteria and so-on. The last statement should return 'false' or similar negative value.

Description:Returns the value defined by expression if the question's value is empty. Otherwise, returns the current value of the question.

This can be used to ensure that a random number is only generated once, or to store the first value entered for a question in a way that is retrievable even if the response is changed later.

Syntax:once(expression)
Example:once(today())
When used in a calculation, returns the current date on form load. If an expression is in a calculation, constraint, or required condition, it is evaluated when the item becomes relevant and the item is not empty. Typically used in calculations.Could also be used in relevant conditions or constraints, but in these cases its usually more clear to use as if() statement. For example:

Instead of using once(), you could also if(. !='', today(), .). If it's not empty, do expression. Otherwise, leave unchanged.

 

Description:Checks whether string2 appears in string1, where string1 is a space-separated list of values. Either or both could be item references instead of hard-coded string literals.
Syntax:selected(string1, string2)
Example:selected(${diagnoses}, 'cancer')
Returns true if “cancer” was selected from a set of diagnoses. Otherwise, returns false.

not(selected(., 'c') or selected(., 'd'))
Returns true if the user did not choose c or d from the current item.

Note: Can be used as a shortcut for writing many or clauses. For example, selected('a b c d e', .) is a shortcut for ". = 'a' or . = 'b' or ' = 'c' or . = 'd' or . = 'e'." This could be useful in if() statements, relevant logic, etc.

Description:Returns the number of choices selected in a multiple choice question.
Syntax:count-selected(select_multiple_item_name)
Example:count-selected(${days_sick})
Returns the number of days the subject was sick (e.g. from a set of choices ${days_sick} such as Mon, Tue, Wed, etc.).  Taking a space separated string and telling you how many of a given value exist. Can also be used to count the total number of selection choices in a space separated lists. If you concatenate strings together with a space, or join repeating data with a space, in a calculate item, this function would return the total number of items in that string.


Functions for Repeating Data Structures

Description:Returns the largest member of nodeset.

Only works on sets of numbers. Empty values (that is, variables referencing unanswered questions) are actually empty strings, and will not be automatically converted to zero (0). Learn more about Null Values in Form Logic.

Syntax:max(nodeset)
Example:In the below example, the calculation max(${child_age}) would return the largest age of all the ages in the repeating item group.

If you wanted to see if one of the children was, say 5 years old, you could use the join or concatenate function to produce a string of all the responses, then use this string as the argument for the selected function.

typenamelabelcalculation
begin_repeatchild_questionsQuestions about child 
textchild_nameChild's name 
integerchild_ageChild's age 
end_repeat   
calculateage_of_oldest_child max(${child_age})

Description:Returns the smallest member of nodeset. 

Only works on sets of numbers. Empty values (that is, variables referencing unanswered questions) are actually empty strings, and will not be automatically converted to zero (0). Learn more about Null Values in Form Logic.

Syntax:min(nodeset)
Example:In the below example, the calculation min(${child_age}) would return the lowest age of all the ages in the repeating item group.
typenamelabelcalculation
begin_repeatchild_questionsQuestions about child 
textchild_nameChild's name 
integerchild_ageChild's age 
end_repeat   
calculateage_of_youngest_child min(${child_age})

Description:Returns the sum of the members of nodeset. Can be used to tally responses to a repeated select question.
Syntax:sum(nodeset)
Example:The below example uses this function to tally the number of meal preference.
typenamelabelcalculation
begin_repeatguest_detailsGuest details 
textguest_nameGuest name 
select_one meal_optionsmeal_preferenceMeal preference 
calculatechkn if(${meal_preference} = 'chicken', 1, 0 )
calculatefsh if(${meal_preference} = 'fish', 1, 0 )
calculateveg if(${meal_preference} = 'vegetarian', 1, 0 )
end_repeat   
calculatechkn_count sum(${chkn})
calculatefsh_count sum(${fsh})
calculateveg_count sum(${veg})

Description:Returns the sum of the members of nodeset. Can be used to tally responses to a repeated select question.
Syntax:count(nodeset)
Example:The below example asks the user for the number of family members, then uses the count function to ensure follow-up questions are asked once per each family member.
typenamelabelrepeat_countcalculation
noteperson_list_notePlease list the names of the people in your household.  
begin_repeatpersonMember of household  
textnameName  
end_repeat    
begin_repeatperson_detailsDetailscount(${person}) 
calculatecurrent_name  indexed-repeat(${name}, ${person}, position(..))
datemember_bdayBirthday of ${current_name}  
end_repeat    

Description:Returns the number of non-empty members of nodeset.
Syntax:count-non-empty(nodeset)
Example:count-non-empty(${bp_sys})
Returns the number of times systolic blood pressure was blank, where ${bp_sys} captures systolic blood pressure inside a repeating group.

If a user adds a repeating group occurrence but does not put data into any of its fields, the count() function would increase by 1, but the count-non-empty() function would not increase.

Description:Returns a particular iteration of a repeating value. 
Syntax:indexed-repeat(item_name, repeating_group_name, iteration)

item_name is the variable you want to retrieve
repeating_group is the name of the repeating group containing the item_name
iteration is the repetition number for the item_name

Example:indexed-repeat(${bp_diastolic}, ${bp_rg}, ${bp_number})

When used as a calculation, returns the diastolic pressure from a specific repeat instance, where:

  • ${bp_diastolic} is the value by the diastolic pressure captured across one or more repetitions
  • ${bp_rg} is the name of the repeating group that collects multiple blood pressure values
  • ${bp_number} is an integer indicating which repetition of the blood pressure to return

Description:Returns an integer equal to the position of the current node within the node defined by xpath. The first entry has a position of 1, second entry 2, and so on. 

Most often this is used in the form position(..) to identify the current iteration within a repeating group.

Syntax:position(xpath)
Example:position(..)
When used as a calculation inside a repeating group, will return the current repeat iteration. Could be used to assign a number for each repetition. In the example below, the first repeating group captures the names of each household member. The second repeating group asks for the birthdate for each household member entered in the first group. This shows how position() can be used with indexed-repeat().
typenamelabelrepeat_countcalculation
begin_repeat  
calculatemed_num  position(..)
textnamePlease enter the name of medication # ${med_num)  
end_repeat    

 


String functions

Description:Concatenates one or more arguments into a single string.

If any arg is a nodeset, the values within the set are concatenated into a string.

Syntax:concat(arg1, arg2, arg3...)
Example:concat(${yyyy},'-',${mm},'-',${dd})
Combines year, month, and day (each captured separately) into a single item formatted YYYY-MM-DD.

concat(${temp},' ⁰C')
Combines temperature value with units label (e.g. to display "37 ⁰C").

Description:Converts arg to a string.
Syntax:string(arg)
string references the item for which you wish to count characters

Description:Returns True if the string is an exact and complete match for the expression. Regular expressions provide a standardized way of validating the syntax of data entered.
Syntax:regex(string, expression)

string is the value you want to which you want to apply the regular expression
expression is the regular expression

Example:regex(., '([01][0-9]|2[0-3]):[0-5][0-9]') and string-length(.) = 5
When used as a constraint, ensures the user enters time in 24-hour format (HH:MM)

regex(., '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,4}')
When used as a constraint, ensures the user enters an email address in the format xxxx@xxxx.xxxxLearn more about how to construct regular expressions.

Description:Returns the substring of string beginning at the index start and extending to (but not including) index end (or to the termination of string, if end is not provided).
Syntax:substr(string, start, end)
string references the data item you wish to parse
start is the index number of the beginning character you want to include
end is the index number of the first character after start that you do NOT want to include

Members of string are zero-indexed, so the first character of the string has index value of 0, the second character an index value of 1, etc.

Example:substr(${date}, 0, 4)
Returns just the 4-digit year from a date field which has a format such as YYYY-MM-DD.

 

Description:Returns the substring of string before the first occurrence of the target substring.

If the target is not found, or string begins with the target substring, then this will return an empty string.

Syntax:substring-before(string, target)
string references the data item you wish to parse
target is the stopping point (up to which the system will return the partial string)
Example:substr-before(${kit_num}, ‘-’)
If the value of ${kit_num} is "123-ABC-XYZ", the function would return 123. Returns the string value before the first occurrence of the target.

Description:Returns the substring of string after the first occurrence of the target substring. If the target is not found this will return an empty string.
Syntax:substring-after(string, target)
string references the data item you wish to parse
target is the starting point, beyond which you want the system will return the remaining string
Example:substr-after(${kit_num}, ‘-’)
If the value of ${kit_num} is "112-ABC-XYZ", the function would return ABC-XYZ. Returns the string value after the first occurrence of the target. To return just XYZ, you could run this function two times, nested together. 

Description:Returns the number of characters in string.

If no value is passed in, returns the number of characters in the value of the question that this function call is tied to which can be useful in a constraint expression.

Syntax:string-length(string)
string references the item for which you wish to count characters
Example:substr(., string-length(.) - 4, string-length(.)) = ".pdf" or substr(., string-length(.) - 4, string-length(.)) = ".PDF"

Ensures only PDF files are uploaded when used as a constraint on a file field.

The substing function first gets the last 4 characters of the file name. Then it checks to see if the PDF file extension is all lowercase or uppercase.

 

Description:Returns a copy of a string where every occurrence of a specified character is replaced by a new character.
Syntax:translate(string, fromchars, tochars)

string is the item you want to translate
fromchars are the characters, if found within the string, you want to translate
tochars are the characters you want to translate to

If fromchars is longer than tochars then every occurrence of a character in fromchars that does not have a corresponding character in tochars will be removed from the string.

Example:translate(substr(., string-length(.) - 4, string-length(.)), 'pdf', 'PDF') = '.PDF'

When used as a constraint on a file field, ensures the files with a PDF extension are uploaded, regardless of the case in which the file extension is written.

The substing function first gets the last 4 characters of the file name. Then it checks to see if the PDF file extension is all lowercase or uppercase.

translate(${input_item}, 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') 
Would translate any lowercase letter into an uppercase letter for the string input_item.

OpenClinica reads in cross form data from a select_multiple item as a comma separated list. However, if you want to treat this as a select_multiple value on the form you read it into, it must be treated as a space separated list. For example, the following expression would convert these values into a space separated string upon reading it into the form:

translate(instance('clinicaldata')/ODM/ClinicalData/SubjectData/StudyEventData[@StudyEventOID='Event OID Here']/FormData[@FormOID='Form OID Here']/ItemGroupData[@OpenClinica:ItemGroupName='Item Group Name Here']/ItemData[@OpenClinica:ItemName='Item Name Here']/@Value, ',', ' ') 


Math functions and number handling

Description:
Syntax:not(expression)
Example:

Description:Truncates the fractional portion of a decimal number to return an integer.
Syntax:int(number)
Example:int(${age)

If ${age} = 24.6, would return the value 24.

Description:Converts arg to number value.

If arg is a string of digits, returns the number value.

If arg is True, returns 1. If arg is False, returns 0.

If arg cannot be converted, returns NaN (not a number).

Syntax:number(arg)
Example:round(${pi}, 4)

If ${pi} = 3.14159, would return 3.1416

Description:Rounds a decimal number to some number of decimal places.
Syntax:round(number, # places)
Example:round(${pi}, 4)

If ${pi} = 3.14159, would return 3.1416

Description:Returns a random number between 0.0 (inclusive) and 1.0 (exclusive).
Syntax:random()
Example:once(round(random()*3+1,0))

The above expression would return and integer of either 1, 2, or 3, and could thus be used to randomly assign participants to one of three groups.

The following logic could then be used to map the output of the above function to one of the three groups:

if(${rndm} = 1,'A', if(${rndm} = 2,'B', 'C'))

 

 

 


Date and Time

Description:Returns the current date without a time component.
Syntax:today()
Example:The expression . <= today() could be used in a constraint to ensure the date entered is not a future date.

Description:Converts time to a number representing a fractional day.
Syntax:decimal-time(time)
Example:For example, noon is 0.5 and 6:00 PM is 0.75.

Description:Converts time to a number representing a fractional day.
Syntax:decimal-time(time)
Example:For example,

decimal-time(12:00)

noon is 0.5 and 6:00 PM is 0.75.

Description:Returns date as a string formatted as defined by format.
Syntax:format-date(date, format)
Example:format-date(${date}, %Y’-’%b’-’%e)

If ${date} = 2028-11-06 would return 06-Nov-2028

Month and day abbreviations are language and locale specific. If form locale can be determined, that locale will be used. Otherwise, the device locale will be used.

 

 

%Y4-digit year
%y2-digit year
%m0-padded month
%nnumeric month
%bshort text month (Jan, Feb, Mar…)
%d0-padded day of month
%eday of month
%ashort text day (Sun, Mon, Tue…).

Description:Returns dateTime as a string formatted as defined by format.
Syntax:format-date-time(dateTime, format)
Example:

 

The identifiers list in format-date() are available, plus the following:

%H0-padded hour (24-hr time)
%hhour (24-hr time)
%M0-padded minute
%S0-padded second
%30-padded millisecond ticks.

Calculations

Description:Raises number to a power
Syntax:pow(number, power)
Example:pow(2,3) 

Returns the value 8.

Description:Returns the natural log of number.
Syntax:log(number)
Example:log(30) 

Returns 3.4011973816621555, the natural log of 30.

Description:Returns the base-10 log of number.
Syntax:log10(number)
Example:log10(30) 

Returns 1.4771212547196624, the base-10 log of 30.

Description:Returns the absolute value of number.
Syntax:abs(number)
Example:abs(-5.23) 

Returns 5.23.

Description:Returns the absolute value of number.
Syntax:abs(number)
Example:abs(-5.23) 

Returns 5.23.

1.3.6 Rules

Definition: A rule is a logical expression used to automate a task.

Examples:

  • A rule might be used to automatically schedule an event when the Enrollment event has a status of completed.
  • A rule might be used to notify participants about forms that are due when using OpenClinica Participate.

Data Managers can create rules to automatically schedule events (EventAction) or automatically send notifications by email or SMS (NotficationAction).

You can download the Rules Template and edit it to create a rule to perform either an EventAction or a NotificationAction.

Note: You can only write rules based on the statuses of Not Scheduled, Scheduled, Data Entry Started, Completed, Skipped, Stopped, Signed, and Locked. You cannot be written based on an event being Removed or Archived.

Despite the use of the new data model, with Statuses and Indepent Status Attributes, rules that use the old data model will still work correctly. 

Quick Start Guide

To Create a Rule:

Step 1: Access the Manage Rules screen.

  1. Click Tasks in the header bar of Runtime.
  2. Select Rules.

Step 2: To Download the Rules Template.

Click the Download Rules Template link at the top of the table.

Step 3: Open the Rules Template in an XML editor, such as Notepad ++ for Windows or TextWrangler for Mac.

Step 4: Find and record OIDs to reference Events and Forms.

  1. Click Tasks in the header bar of Study Runner, and select View Study.
  2. Click the Download the Study Metadata link at top of the screen and record OIDs, or scroll down on the screen and record OIDs from there.

See Locate Object Identifiers in a Study for more information on finding OIDs.

Step 5: In the Rules Template, delete any actions you do not want the rule to perform.

  • If you are making an EventAction rule, delete everything between the EventAction tags.
  • If you are making a NotificationAction rule, delete everything between the NotificationAction tags.

Step 6: Define the Target.

Any time a value changes, the rule evaluates the target. For example, you can use:

  • Event Status: SE_EVENTOID.STATUS
  • Event Start Date: SE_EVENTOID.STARTDATE

Step 7: Define an OID for the rule.

It must be entered in all capital letters. You can include numbers and underscores. It must be unique within the study and can only be 40 characters long.

(Optional): If you want the rule to run at a certain time, specify the time in 24-hour format.

Step 8: Enter the expression.

Expressions are the conditions that cause the rule to run.

Event Action: If you want the rule to run when the event reaches a certain status, specify all of the statuses as true or false.

NotificationAction: Specify the recipient(s), subject of the notification, and message next to the corresponding tags. You can include multiple email addresses separated by commas. To use this rule, Openclinica Participate must be actived.

Note: See syntax below, in the tables.

Step 9: Make sure all tags are closed, and save the file as an XML file.

Step 10: Click the Add Rules link at the top of the Manage Rules screen.

Step 11: Click Choose file, and select a file to upload. Then click the Continue button.

To View a Rule:

Click the View button next to the rule you want to view.

To Remove a Rule:

Click the Remove button next to the rule you want to remove.

To Download a Rule:

Click the Download button next to the rule you want to download.

To Test a Rule:

  1. Click the Test button next to the rule you want to test.

  1. Check that the Target, Rule Expression, and Actions are displayed correctly on the screen.
  2. Click the Validate & Test button.

  1. Specify test values for variables in your rule expression.
  2. Click the Validate & Test button again.
  3. Review the results of the test. On the left-hand sidebar under Alerts & Messages, you will see a statement about whether the test was valid or invalid. Scroll down to Verify results for more details.

Actions

IconActionDescription
ViewView the rule information, such as Target OID, Study Event Definition, CRF Name, etc.
RemoveRemove the rule
DownloadDownload the rule
TestTest to ensure that the rule works

Rule Components

Rule ComponentsDescription
RuleDefThe rule definition, which includes the rule OID, name, description, and expression. This defines the rule, which is then assigned (referenced) in the RuleRef.
RuleRefThe rule definition/expression being used by the assignment is referred to in the RuleRef. This is an OID for the particular RuleDef. Each RuleRef may have multiple ActionTypes.
RunOnFor all actions except EventAction, the parameter that defines when the ActionType will execute. The current phases include InitialDataEntry, DoubleDataEntry, AdministrativeEditing, and Batch.
RunOnStatusFor EventAction, the parameter that defines when the EventAction will execute. The current status values include not_scheduled, scheduled, data_entry_started, completed, skipped, and stopped.
RunOnScheduleThe Rule Def expression will be evaluated and triggered the first time it becomes true based on a change of event status or other component of the expression. The rule will also be evaluated daily at the set time and may trigger then if the expression is true.
TargetThe target is the item where an action will be fired. This is a single item in a CRF. When this item is encountered in the CRF and the user selects the Save button, the system will execute the actions associated with a rule.
ValueExpressionA calculation or other expression that defines what will be populated in the DestinationProperty (for an InsertAction) or EventDestination (for an EventAction).

Expressions

ExpressionDefinitionVariable Type
eqEqual toAny
neNot Equal toAny
ctContainsAny
gtGreater ThanNumber
gteGreater Than or Equal toNumber
ltLess ThanNumber
lteLess Than or Equal toNumber

Example:

SE.ENROLLMENT.STARTDATE eq completed

Conditional Operators

OperatorFunctionDescription
andAndVariables used with this operator should be of a boolean type
orOrVariables used with this operator should be of a boolean type

Example:

CURRENT_DATE -1 and SE.SCREENING.STATUS ne completed

Arithmetic Operators

OperatorFunctionDescription
+AdditionVariables used with this operator should be of a number type
-SubtractionVariables used with this operator should be of a number type
*MultiplicationVariables used with this operator should be of a number type
/DivisionVariables used with this operator should be of a number type

Example:

SE.ENROLLMENT.STARTDATE + 7

Dates within Rules: Equality and Relational Operators

ExpressionDefinitionFull Expression
eqEqual toITEM_OID eq 2008-12-12
neNot Equal toITEM_OID ne 2008-12-12
gtGreater ThanITEM_OID gt 2008-12-12
gteGreater Than or Equal toITEM_OID gte 2008-12-12
ltLess ThanITEM_OID lt 2008-12-12
lteLess Than or Equal toITEM_OID lte 2008-12-12

The format of the date included in an expression should be yyyy-MM-dd.

Example:

January 01, 2020 should be written as: 2020-01-01

You can also use _CURRENT_DATE to compare values against the current server date.

For example, with a NotificationAction, to notify Participants of a Form that must be completed on the next day, you could use an expression such as:

<Expression>SE_OID.STARTDATE eq (_CURRENT_DATE +1) and SE_OID.STATUS ne “complete”</Expression>

This would send a notification one day in advance of the expected form completion date as long as the form was not already completed by the Participant.

Notification Action Parameters

ParameterDescriptionToMessageSubject
${participant.firstname}The Participant First NameX
${participant.loginurl}The Participant URL with Automatical LoginX
${participant.url}The Participant URL without Automatic LoginX
${study.name}The Name of the Study, as Defined in OpenClinicaXX
${participant.accesscode}The Single-Use Code the Participant Must Use to Access OpenClinica ParticipateX
${event.name}The Name of the Event, as Specified in OpenClinicaXX
${participant}The Participant Contact Information, as Provided When the Participant was Connected to the Study. (This Could be a Mobile Number for SMS Notification, an Email Address, or Both; OpenClinica Automatically Sends the NotificationX
${participant.id}Participant IDXX
${site.id}Site IDXX
${site.name}Site NameXX
${study.id}Study IDXX
/nUse at the End of a Line for a LinebreakX

For example, the following rule will send a notification to any Participant who has an Event scheduled for the following day:

Notice that the Rule Expression uses _CURRENT_DATE and compares it to SE_INITIALTREATMENT.STARTDATE to determine that the Event is scheduled for the next day. (In other words, if TODAY is equal to the day BEFORE the visit and the status is not yet completed, send a notification.

If you want to send a reminder one day AFTER the visit, you would use _CURRENT_DATE eq SE_INITIALTREATMENT_STARTDATE +1, meaning that the rule will trigger if _CURRENT_DATE is one day AFTER the visit was scheduled and the status is not yet completed.)

1.3.7 Locating Object Identifiers in a Study

Unique Object Identifiers (OIDs) are created for each of the following objects in any given study:
  • Study
  • Site
  • Study Participant
  • Event
  • Form
  • Item Group (bind::oc:itemgroup as defined in your forms)
  • Item
You may need to reference these OIDs in the process of designing your study (when creating cross-checks in a form – see the last pages of the Form Template for more information, or when using Web Services.

To Find Your OIDs:

  1. Go to your study. OIDs are the same across environments, so you can go to either Test or Production.
  2. Select Tasks > View Study or click on your Study name in the upper left corner of the title bar.

There are two options for locating OIDs. You can either use the OpenClinica interface to drill down through each object or download the study metadata and locate the OIDs within the XML code. Both options are available on the Study Details page. Instructions for each option are detailed below.

Locate OIDs Using the OpenClinica Interface:

  1. In the Oveview section of the Study Details page, record the Study OID.
  2. In the Sites section, record the Site OID.
  3. In the Event Definitions section, record the Event OIDs.
  4. For the Event Definition whose Form OIDs you want, click the View icon.
  5. In the CRFs table, click the View icon for the CRF whose OIDs you want.
  6. In the View CRF Details table, record the OID for the Form.
  7. For the CRF version you want, click the metadata icon .
  8. In the View CRF Version Details page, record the OIDs for the Group(s) and Item(s) (in that order).

Locate OIDs in the Study XML File

If you are familiar with XML file structure, you can locate OIDs in the Study metadata file.

  1. On the Study Details screen, click the Download study metadata link.
  2. Open the Study metadata file in a browser or text editor.
  3. Scroll through the file to locate the OIDs.
  4. Continue to scroll through the metadata or collapse sections as needed to locate the Item Group and Item OIDs.

1.3.8 Content Library

You can use Library Management to save a question or block of questions that you can add to Forms later. This is useful for items you will use frequently, such as Vital Signs. Using the Library Management feature saves time because you do not have to recreate the same items for each Form.

The Library Management button appears in the header bar of Study Designer for users with a User Type of Administrator. This button does not appear for other users.

The Library is shared by all users with access to Library Management within the same customer domain. Items that users previously added to the library will be available in Library Management. Otherwise, Library Management will be empty.

You can use Library Management with Form Designer or the XLS Form Template.

To Enter Library Management:

Click the Library Management button in the header bar of Study Designer.

The Library Management screen displays all items.

Note: 

The version number applies only to items with a Type of Template.

Icons

The icons next to the name of the item vary based on the Type of the item. The number in the icon indicates the number of items (including item groups) on the Form.

IconItem TypeDescription
QuestionA single item
BlockMultiple items without a style or version number
TemplateA complete form template that can either be created/edited in the form design studio or uploaded with a form template.

The Action icons appear on the right-hand side of each item.

IconAction
Edit
Label
Clone
Download XLS
Manage Collection
Delete

Search

Enter text to search for an item.

Filter

You can select Question, Block, or Template to filter the screen to only show those types of items.

New

You can create a single question, a block of questions, or a full Form Template to add to the library.

To Create a Single Question, Block of Questions, or Form Template in Form Designer to Add to the Library:

  1. Click the New button in the upper left-hand corner of the Library Management Screen.
  2. Select Question.
  3. Click the + sign.
  4. Enter text for the question.
  5. Click +Add Question.
  6. Select a question type.
  7. (Optional) If you chose Single-Select or Multi-Select, enter options for the question.
  8. (Optional) Repeat steps 4-8 until you have added all of your questions.
  9. Click Create.

To Edit a Single Question, Block of Questions, or Form Template:

  1. Click the Edit icon next to the item you want to edit.
  2. Make changes in Form Designer.
  3. Click Save Changes.

To Delete an Item:

  1. Click the Delete icon next to the item you want to permanently delete.
  2. Click Delete to confirm that you want to permanently delete the item.

Labels

You can use labels to categorize items beyond collections. Labels appear on items when you click the Add from Library button in Form Designer.

To Add a Label to a Question, Block of Questions, or Full Form Template:

  1. Click the Label icon next to the item you want to label.
  2. Click Add Label(s).
  3. Enter text.
  4. Press the Enter key.

To Remove a Label from a Question, Block of Questions, or Full Form Template:

  1. Click the Label icon next to the item you want to remove the label from.
  2. Click the X next to the label you want to remove.

Clone

  1. Click the Clone icon next to the item you want to duplicate.
  2. Click Ok to confirm that you want to duplicate the item.

Download XLS

Click the Download XLS icon next to the item you want to download the XLS Form Template for.

Upload XLS

  1.  Click the Library Management button in the header bar of Study Designer.
  2. Click the New button in the upper left-hand corner.
  3. Select Upload.

Collections

To Create a Collection: 

  1. Click the Library Management button in the header bar of Study Designer.
  2. Click the New button in the upper left-hand corner.
  3. Select collection.
  4. Enter a name for the collection.
  5. Click CREATE COLLECTION.

To Rename a Collection:

  1. Click the new collection.
  2. Click the ellipses.
  3. Click Rename.

To Delete a Collection:

  1. Click the new collection.
  2. Click the ellipses.
  3. Click Delete.

To Add an Item to a Collection:

  1. Click the Manage Collection button next to an item you want to add to the collection.
  2. Select the collection you want to add the item to. If there are no available collections, the selection box will say None available.

Note: You can only add an item to a single collection. 

Use In Form Designer

Items from Library Management appear in Form Designer when you click Add from Library. You can Search the library or select from a list of items.

If relevant, items on the list display labels and the number of items in the block/template. You can also add items to the library while using Form Designer.

To Add an Existing Question, Block of Questions, or Template From the Library:

  1. Click Add from Library.
  2. Click the item you want to add, and move it onto the Form. You can drop the item when a box with a dotted outline appears to indicate where the item will be.

To Add a Question or Block of Questions to the Library:

Click Add Question to Library next to the item you want to add to the library.

To Return to the Library Management Screen:

Click Back to Library.

Use in XLS Form Template

To use an item from the library in an XLS Form Template, click the Download XLS icon next to the item you want to use.

Once you have downloaded the XLS Form Template, edit it or upload it without making changes.

You can also download/upload in Study Designer and then add the Form Template to the library.