Study Designer

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

To access Study Designer, click Design on the My Studies screen. You must have a User Role of Data Manager to access Study Designer. 

Forms appear as 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)
VisitAn 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 Withdrawal 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: Allows you to download the Form Template.
  • Table Design: Allows you to add custom columns to the Participant Matrix and Queries Table or define Data Review Tables.
  • Filter: Expands the right sidebar, which allows you to filter Forms by permission tags, labels and members.
  • Search: Expands the right sidebar, which allows you to enter text to search for Forms in the current study.
  • Multi-Select: Expands the right sidebar, which allows you to select multiple forms by permission tags, labels, and members.
  • Archive: 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 page covers all of these features (excluding Library Management) in more detail below.

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.

You can also use both Form Designer and the Form Template. For example, you can 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.

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.

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 select the form definition spreadsheet and press Ctrl (Windows) or Command (Mac) to select both the spreadsheet and the file(s) to upload at the same time.

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 Participate Form in the Participate Properties section, the Preview button 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. All of the preselected properties (Hide from site users, SDV, Participate Properties) also get migrated to the new form card. If the form is just typed in, only the form’s definition will match. None of the former card’s properties will cross to the new form card.

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. Archived forms will only display on a participant if the form has already been started. 

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

IconForm PropertyDescriptionExample
Hide from site usersThe 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 than entering 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.
(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.
Participate Form (Participate Property)Allows 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.
Public URL (Participate Property)Allows participants to self-register for a study. Configure forms to allow Public URL within Study Designer and then create the form URL within the Site Configurations page in Study Runner. (This checkbox is not available if the Participate module has not been activated.)This URL can be shared in a public forum, such as a subway advertisement, social media post, etc., which can help attract potential participants.
Offline Capable (Participate Property)Allows research staff to enter form data even if they do not have internet service available. Configure forms by selecting Public URL and Offline Capable in Study Designer and then create the form URL within the Site Configurations page in Study Runner.  (This checkbox is not available if the Participate module has not been activated. Additionally, the Public URL checkbox needs to be selected in order for the Offline Capable checkbox to appear.)This allows data to be gathered in remote locations that do not have access to the internet.

To Set Form Properties:

Click the checkboxes on the Form Card.

Best Practice: Use Permission Tags instead of setting the Form to Hide from site users for more flexibility.

SDV Requirements

Forms may or may not require Source Data Verification (SDV), depending on the study protocol. Data Managers and Administrators can specify the level of SDV requirement for each item on a form in Study Designer. Below is a table that displays basic definitions of each SDV Requirement.

IconSDV RequirementDescription
(No Icon)Not Applicable (Default)SDV is not applicable for this form.
Not RequiredSDV is not required for the form, but you can still perform SDV if you want. This is often used when 10% of Forms need to be SDVed. Each form record is verified or unverified all together, rather than item-by-item
Partial RequiredSome fields on the form must be verified. Each form record is verified or unverified all together, rather than item-by-item
100% RequiredEvery field in the form must be verified. Each form record is verified or unverified all together, rather than item-by-item
Item-LevelItem-Level SDV allows you to choose which items will be part of SDV by selecting Required, Optional, or Not Applicable for each individual item on a form. Item records will then be marked as Verified or Not Verified independently and will become unverified independently if their data changes on the form.
Item-Level (To be configured)This indicates Item-Level SDV was selected, but is not configured validly since all items are set to Not Applicable. Use the Configure SDV link on the Form card in Study Designer to set each item to Required, Optional, or Not Applicable. At least one item needs to be Required or Optional, otherwise change the form’s SDV Requirement to Not Applicable.

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.

Item-Level SDV allows you to specify which items on a form should be verified by setting each item as Required, Optional, or Not Applicable for SDV.

Not all forms will have all SDV Requirement options available. The SDV options are related to when the form was created and when it was published to Production in relation to the Stack 15 release (December 20th, 2021). The SDV options on forms are as follows:

  • Form first published to Production prior to Stack 15 release: Not Applicable, Not Required, Partial Required, 100% Required
  • Form created prior to Stack 15 release, but not yet published to Production: Not Applicable, Not Required, Partial Required, 100% Required, Item-Level
  • Form first published to Production after Stack 15 release with one of the following statuses – Not Required, Partial Required, 100% Required: Not Applicable, Not Required, Partial Required, 100% Required 
  • Form first published to Production after Stack 15 release with one of the following statuses – Not Applicable, Item-Level: Not Applicable, Item-Level 
  • Form created after Stack 15 release: Not Applicable, Item-Level
    • Individual items have the following SDV Requirement options: Required, Optional, or Not Applicable 
      • When first selecting Item-Level on a form, the item is set to Optional by default. Additional items that are added will default to Not Applicable.

Item-Level SDV Requirements:

  • Not Applicable: items cannot be verified
  • Optional: items can be verified
  • Required: items must be verified for the form to be fully verified and get Verified status

After choosing Item-Level SDV on a form, click the Configure SDV link to set each item to Required, Optional, or Not Applicable for SDV.

After selecting the appropriate SDV Requirement in the Update All To dropdown menu, click Apply to make the changes to all items on the form. You can also use the radio button next to each item to individually update the SDV Requirement.

Note: If you change a form’s SDV Requirement after it has been published, you will need to confirm that the SDV Requirement is correct for each site. Changing the SDV Requirement for a form to something other than “Item-Level” will change the requirement at the study level, but it will not change a site’s SDV Requirement if it is set to Item-Level. 

More information on SDV: Source Data Verification.

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, you cannot:

  • 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 item label.

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

Table Design also allows you to add custom columns to the Participant Matrix, the Queries Table, and the Data Review 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.

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, Queries Table, and/or the Data Review Table. You can only select non-repeating fields from non-repeating events.

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 item’s 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 bar. 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 a 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.

User Roles Page with descriptions of each role

  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.

2.2.1 Using the Form Template

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

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

Definitions

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

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

The XLS Spreadsheet Contains Five Sheets:

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

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

Quick-Start Guide

To Download the Form Template:

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

To Create the Form:

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

To Add an Item to the Form:

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

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

To Enter Choices for Select One or Select Multiple items:

  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 alphanumeric string for the option in the name column. Do not include commas, spaces, or other non-alphanumeric characters in the choice name.
  4. Enter the unique id you entered for the question on the Survey tab (in the name column) to link options in the list_name column.
  5. Continue to add options as needed (by repeating steps 2-4).
  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 cell contents would be select_one YN)

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

To Create a Group of Items:

  1. Click the survey tab in the form template.
  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, you are using repeating groups, which must be kept separate, it is ideal to keep items in the same group. These groups do not have to correspond to the begin/end groups. Keeping items in the same group allows for better data visualization in Insight because participant data is displayed on tables by item group, not by form.

To Upload a Form Template in Study Designer:

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

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

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

Form Template Exclusive Features

Annotated CRFs

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

Cascading Selects

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

  • Type of Cancer
  • Subtype of Cancer
  • Specific Cancer

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

To Add a Cascading Select:

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

Crossform References

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

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

Referencing Long Lists

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

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

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

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

Repeat Count

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

To Add a Repeat Count:

  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

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

To Reference the CSV File in the Form Template:

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

To Upload a Form Template with a CSV File:

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

Languages and Translations

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

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

 

You can define languages for items, including the following:

Survey Sheet:

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

Choices Sheet:

  • label
  • image (file name)

Settings Sheet:

  • default_language

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

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

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

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

System-Level Language Packs:

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

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

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

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

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

Image Maps

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

To Set Up Image Links in an SVG File:

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

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

  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 Fields with No Form Designer Equivalent

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

Namespace

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

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

Crossform References

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

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

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

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

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

Required Message

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

Required Type

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

Image (Choices)

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

Choice Filter

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

List Name

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

list_namelabelname
YNYes1
YNNo2

Repeat Count

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

Constraint Type

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

Form Template and Form Designer Fields

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, in the TEST environment, the new version overwrites the existing version except for changes to the item types, the item groups, or moving an item in or out of a repeating group. In the PRODUCTION environment, you can not overwrite a version of a form and must have a unique identifier for each version.

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.
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. On the choices sheet, enter the same xxxxx in the list_name column for each choice and 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. 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. On the choices sheet, enter the same xxxxx in the list_name column for each choice and 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.
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.
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).
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.
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.
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.

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

A Form could be used to record a participant’s vital signs, capture a patient’s 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, because a participant can only terminate once).

Event Icons

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

IconEvent TypeDescriptionExample(s)
VisitAn 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 Withdrawal 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

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

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 an event to Repeating/Non-Repeating or Visit/Common.

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.

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.

Restore an Event:

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

Note: Restoring an event restores all of its forms. You can restore an event with only a specific form by clicking Restore 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

Form Template – a pre-formatted XLS spreadsheet that allows you to define your form

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

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

Warning: If you use both, be aware that if you start with the 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.

Download the Form Template:

In Study Designer, click Form Template 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.

Upload a Form Definition:

  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.

Enter Form Designer:

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

Preview a Form:

Click Preview 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 Participate Form under Properties, this option appears as Preview (as a Participant).

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.

Archive a Form:

  1. Click the name of the form.
  2. Click on the Menu (hamburger) button in the corner of the form.
  3. Select Archive.

Archive a Form Version:

  1. Click the name of the form.
  2. Click on the Version Options Menu (hamburger) button next to the form version you wish to archive. Note: If the form version you have selected is set as the default form version, this option will not appear. Instead, select a different form version as default, or follow the instructions above to archive the entire form (if it has only one version).
  3. Select Archive.

Note: Archiving a form is different from archiving a form version. Archiving a form removes the form from the associated event.  Archived forms will be viewable in the study but no longer be editable. Data in archived forms is not included in extracts.  

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.

Archived forms can be restored at any time. If you archive or unarchive a form you need to publish your study for this to take effect.

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.

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

Form properties can be edited on the form card

IconForm PropertyDescriptionExample
Hide from site usersThe Form is hidden at the site level but is accessible from the study level.This is used when study users, but not site users, should see the form. This could include cases such as forms with data imported from another source or forms for review or adjudication.
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.
(No icon)Allow Add Another (Common repeating events)Allows 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.
Participate Form (Participate Property)Allows 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.
Public URL (Participate Property)Allows participants to self-register for a study. Configure forms to allow Public URL within Study Designer and then create the form URL within the Site Configurations page in Study Runner. (This checkbox is not available if the Participate module has not been activated.)This URL can be shared in a public forum, such as a subway advertisement, social media post, etc., which can help attract potential participants.
Offline Capable (Participate Property)Allows research staff to enter form data even if they do not have internet service available. Configure forms by selecting Public URL and Offline Capable in Study Designer and then create the form URL within the Site Configurations page in Study Runner.  (This checkbox is not available if the Participate module has not been activated. Additionally, the Public URL checkbox needs to be selected in order for the Offline Capable checkbox to appear.)This allows data to be gathered in remote locations that do not have access to the internet.

Set Form Properties:

Click the checkboxes on the Form Card.

Best Practice:

Use Permission Tags instead of setting the Form to Hide from site users for more flexibility.

SDV Requirements

Forms may or may not require Source Data Verification (SDV), depending on the study protocol. Data Managers and Administrators can specify the level of SDV requirement for each item on a form in Study Designer. Below is a table that displays basic definitions of each SDV Requirement.

IconSDV RequirementDescription
(No Icon)Not Applicable (Default)SDV is not applicable for this form.
Not RequiredSDV is not required for the form, but you can still perform SDV if you want. This is often used when 10% of forms need to be SDVed. Each form record is verified or unverified all together, rather than item-by-item
Partial RequiredSome fields on the form must be verified. Each form record is verified or unverified all together, rather than item-by-item
100% RequiredEvery field in the form must be verified. Each form record is verified or unverified all together, rather than item-by-item
Item-LevelItem-Level SDV allows you to choose which items will be part of SDV by selecting Required, Optional, or Not Applicable for each individual item on a form. Item records will then be marked as Verified or Not Verified independently and will become unverified independently if their data changes on the form.
Item-Level (To be configured)This indicates Item-Level SDV was selected, but is not configured validly since all items are set to Not Applicable. Use the Configure SDV link on the form card in Study Designer to set each item to Required, Optional, or Not Applicable. At least one item needs to be Required or Optional, otherwise change the form’s SDV Requirement to Not Applicable.

Not all forms will have all SDV Requirement options available. The SDV options are related to when the form was created and when it was published to Production in relation to the Stack 15 release (December 20th, 2021). The SDV options on forms are as follows:

  • Form first published to Production prior to Stack 15 release: Not Applicable, Not Required, Partial Required, 100% Required
  • Form created prior to Stack 15 release, but not yet published to Production: Not Applicable, Not Required, Partial Required, 100% Required, Item-Level
  • Form first published to Production after Stack 15 release with one of the following statuses – Not Required, Partial Required, 100% Required: Not Applicable, Not Required, Partial Required, 100% Required 
  • Form first published to Production after Stack 15 release with one of the following statuses – Not Applicable, Item-Level: Not Applicable, Item-Level 
  • Form created after Stack 15 release: Not Applicable, Item-Level
    • Individual items have the following SDV Requirement options: Required, Optional, or Not Applicable 
      • When first selecting Item-Level on a form, the item is set to Optional by default. Additional items that are added will default to Not Applicable.

Set SDV Requirements:

Click the SDV drop-down menu on the form card and select the requirement level you want to apply to the form. If Item-Level is the selected requirement, click the Configure SDV link to select which items will require SDV. 

Item-Level SDV Requirements:

  • Not Applicable: items cannot be verified
  • Optional: items can be verified
  • Required: items must be verified for the form to be fully verified and get Verified status

If all items will have the same SDV Requirement, click in the Update All To menu, select the appropriate requirement and click Apply. For any items that need a different requirement, select the SDV Requirement for the item’s row to update it. Then, return back to the form card.

Form Drafts and Versions

Form Versions will be pushed to Study Runner when you publish your study, form Drafts will not. Form Drafts are created when you build a form using Form Designer. When you are ready, you can promote a Draft to a Version to set it up for publishing. 

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. If the version specified on the Form Template’s settings tab is the same as an existing version on the form card, the system will overwrite that version upon upload. If the version specified on the Form Template’s settings tab is different, the system will create a new version of that form upon upload.

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 Audit Log

You can promote the draft to a version to include it in your study when you publish it. To promote a draft to a version: click the hamburger menu next to the draft you wish to promote and select Add to Study.

Warning: If you do not want the new form to overwrite an existing form:

  • In Form Designer: change the number in the Version number field on the Layout & Settings panel.
  • In the Form Template: update the Form Version on the template’s Settings tab.

Once a form has been published to Production, it cannot be overwritten. The system will require you to create a new version.

Drafts

Access the Drafts Menu:

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

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.

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.

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.

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.

Permanently Delete the Draft:

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

Versions

Access the Versions Menu:

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

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.

Preview the Version:

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

Download the Version:

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

2.2.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, in the TEST environment, the new version overwrites the existing version except for changes to the item types, the item groups, or moving an item in or out of a repeating group. In the PRODUCTION environment, you can not overwrite a version of a form and must have a unique identifier for each version.

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.
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. On the choices sheet, enter the same xxxxx in the list_name column for each choice and 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. 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. On the choices sheet, enter the same xxxxx in the list_name column for each choice and 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.
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.
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).
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.
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.
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.

2.2.4 Form Logic

Adding logic to your forms can help make them “smart” by improving the user experience, promoting cleaner data, and automating calculations.
Form logic includes:

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

When writing expressions for form logic it is necessary to use the correct syntax, including punctuation and spaces. Form logic is not case-sensitive.

Referencing Items

There are two ways to reference an item on your form within a logic expression. Values can either be an item reference (e.g. age) or the literal value of an item (e.g. yes or 1).

SyntaxDescriptionExample
.References the current item’s value.The expression .>= and .<=65 in an age field's constraint settings would verify that the value (age) entered is between 18 and 65.
${itemname}References the value of another item where itemname is the name of that item.The expression ${sex} = 'female' could be used in a skip logic setting on a pregnancy question to display the question only if the participant is female.

To use values from other forms see below.

Conditions

Note: You can use either single quotes or double quotes, but single quotes are generally preferred for clarity. You would use double quotes if the string already 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
String Value${itemname} = 'value'
${itemname} = "value"
Null Value [Empty String]${itemname} = ''
Multiple Select Numeric Value(s)selected(${itemname}, choicename)
Multiple Select Character Value(s)selected(${itemname}, 'choicename')

Operators & Boolean Logic

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>=
Manipulating the order of operations( )
All must be trueand
Any can be trueor

Boolean operators (and & or) return a value of either True or False. If you have a sequence of statements, all linked together with and, then to have a value of True every statement must be true; if even one is not true, then the whole expression’s value is False. With or, the threshold is much lower: only one of the statements needs to be true to evaluate to True (though any number can be true, as long as at least one is).

Parentheses control the order of operations of a statement and are often used even when not needed to clarify and to increase the readability of the code (e.g.(${enddate}-${startdate}) * 2). Lastly, modulus (mod) divides one number into another and returns the remainder. This has many uses well beyond the EDC realm, but one of the simplest examples is that many programs use it to tell when a number is even or odd (if mod 2 is 0 it’s even, 1 it’s odd), or to know if a number is equal to, or a multiple of, another number (in this case if mod-ing by say 7, any value that results in 0 would be a multiple of 7).

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)

Alternatively: round(if(${weight} != '' and ${height} != '', if(${wh_units} = 1, 10000 * ${weight} div(pow(${height}, 2)), 703 * ${weight} div(pow(${height}, 2))), 0))
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. Required conditions are only evaluated for items that are currently null (for example, no value has been entered).

DescriptionSyntax
Cancer Type shows if {cancerdiagnosis} is yes.${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

Relevant logic is ignored if the default column is populated for an item in a form. If an item has a default value, it populates when the form is opened or when a repeat is added regardless of whether the item is relevant or not. To avoid default values displaying before an item becomes relevant, use triggered calculations so the values don’t populate until the item becomes relevant, or use an if() statement. To use an if() statement in this case, use a default that has an if() statement that sets the value to null if the relevant condition is not met and sets it to the desired default if the relevant condition is met. 

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 the syntax column in brackets with the names of your own items. Constraint conditions are only evaluated for items that are currently non-null (for example, a value has been entered).

Validation Criteria/ConstraintSyntax
No Future Dates.<=today() [Please refer to https://docs.getodk.org/form-logic/#when-expressions-are-evaluated for an important caveat]
Age Must be Between 1 and 100 [Non-inclusive]${age} > 1 and ${age} < 100
Must not exceed 100 charactersstring-length(.)<=100
Must be in 24-Hour Format (HH:MM)regex(., '^(([0-1]{0,1}[0-9])|([2][0-3])):([0-5][0-9])$')

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 than soft edit checks. Because they can make data entry more difficult for users, it is recommended that they be used only when the benefits to data quality outweigh the difficulties for the study personnel.

All checks that are not explicitly defined as hard edit checks are soft edit checks in all forms. The exception to this rule are forms used in the Participate module in which 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 message. If the value entered causes a hard edit check to be violated on a different item (such as one already entered and saved that passed the validation criteria at the time) then the user will see an error message displayed on the item with the violated 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. The user can add a manual or automatic query to a hard check item to close the form. However, the query will not hide the hard check error message.

Important: 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 required hard check will not allow the item to be cleared. To avoid this, the item’s required logic must indicate that the item is required only when the item’s relevant logic is met. If this is not implemented properly, 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:required-type.
  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:constraint-type.
  3. Enter strict.

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 of 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
  5. (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 the test environment, then locate and reference the OIDs as needed (they do not change between the test & production environments), 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 CRA 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 noteitem, 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:externalcell 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

2.2.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. Review the full list of functions that have been validated and tested in OpenClinica in the OpenClinica Validated Functions Index.

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:number(${year})

if ${year} = "1995", then number(${year}) would return 1995

Description:Rounds a decimal number to some number of decimal places.
Syntax:round(number, # places)
Example:round(${pi}, 4)

If ${pi} = “3.14159”, then round(${pi}, 4) 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:Returns the current date and time with the timezone.
Syntax:now()
Example:For example, this can be used to set the current date and time as default.

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},‘%d-%b-%Y’)

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.

2.2.5.1 OpenClinica Validated Functions Index

All OpenClinica Validated Functions

String Functions
string(* arg)
concat(string arg*|node-set arg*)
join(string separator, node-set nodes*)
substr(string value, number start, number end?)
substring-before(string, string)
substring-after(string, string)
translate(string, string, string)
string-length(string arg)
normalize-space(string arg?)
contains(string haystack, string needle)
starts-with(string haystack, string needle)
ends-with(string haystack, string needle)
uuid(number?)
pulldata(string instance_id, string desired_element, string query_element, string query)

Boolean Functions
if(boolean condition, string then, string else)
coalesce(string arg1, string arg2)
once(string calc)
true()
false()
boolean(* arg)
boolean-from-string(string arg)
not(boolean arg)
regex(string value, string expression)

Number Functions
number(* arg)
random()
int(number arg)
sum(node-set arg)
max(node-set arg*)
min(node-set arg*)
round(number arg, number decimals?)
pow(number value, number power)
log(number arg)
log10(number arg)
abs(number arg)
sin(number arg)
cos(number arg)
tan(number arg)
asin(number arg)
acos(number arg)
atan(number arg)
atan2(number arg, number arg)
sqrt(number arg)
exp(number arg)
exp10(number arg)
pi()

Node-set Functions
count(node-set arg)
count-non-empty(node-set arg)
position(node arg?)
instance(string id)
current()
randomize(node-set arg, number seed)

Date and Time Functions
today()
now()
format-date(date value, string format)
format-date-time(dateTime value, string format)
date(* value)
decimal-date-time(dateTime value)
decimal-time(time value)

Select Functions
selected(string list, string value)
selected-at(string list, number index)
count-selected(node node)
jr:choice-name(node node, string value)

Repeat Functions
indexed-repeat(node-set arg, node-set repeat, number index)

 

Note: The asterisk (*) in these functions indicates that it can take arguments of multiple types (string, number, date, etc.).

2.2.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 (NotificationAction).

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 in the table below. You cannot be written based on an event being Removed or Archived.

Event StatusText for Rule (case sensitive)
Not Schedulednot_scheduled
Scheduledscheduled
Data Entry Starteddata_entry_started
Completedcompleted
Skippedskipped
Stoppedstopped
Signedsigned
Lockedlocked

Despite the use of the new data model, with Statuses and Independent 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 Study Runner.
  2. Select Rules.
    1. The Rules option does not display when logged in at the Site level. Change to Study level to see the Rules option.

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 the lines starting from <NotificationAction > to </NotificationAction> tags.
  • If you are making a NotificationAction rule, delete the lines starting from <EventAction> to </EventAction> 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 active.

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.
RunOnScheduleThis 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 hour and may trigger then if the expression is true.
Note: When minutes are documented in the scheduled time, they are ignored. For example, if a rule is defined to run at 17:30, it will be queued up for processing with all rules defined to run between 17:00 and 17:59. The system will start processing rules on the hour (00), but it may take longer to process all rules depending on factors such as complexity of rule logic and number of rules and participants in the study.
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.)

2.2.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
  • 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 (such as when using cross-form data in a form definition or when using Web Services).

Find Your OIDs:

There are three options for locating OIDs in OpenClinica. You can use the Data Dictionary in Study Designer, use the OpenClinica interface to drill down through each object, or download the study metadata and locate the OIDs within the XML metadata.

Using the Data Dictionary in Study Designer:

The Data Dictionary gives you form-specific information including form metadata, form properties, and item metadata (such as Item OID, Item Group Name, Item Group OID, Item Type, and Insight Table). The Data Dictionary is available via a link on each form card in Study Designer and can be downloaded as a CSV file to view outside of Study Designer.

  1. Open the form in Study Designer and click the Data Dictionary link.

  1. Review the information you need from this window, or click the Download icon to download the CSV file.

Note: Uploading the same version of a form multiple times can lead to some removed items not being present on any form version. These items with no versions are filtered out of the Data Dictionary by default but can be shown by selecting the Include items in no versions checkbox.

Using the OpenClinica Interface:

  1. Go to your study in either the Test or Production environment by using the Go menu (Study and Site OIDs will end in TEST or PROD depending on which environment you choose).
  2. Select Tasks ⇨ View Study or click on your study name in the upper left corner of the title bar.

  • The Overview section of the study details page displays the study’s OID.
    • S_BFBD2019(TEST) in the case shown.
  • The Sites section of the study details page shows the Site OID(s).
    • In the example above:
      • S_JT(TEST)
      • S_BCH for Boston Children’s Hospital
      • S_DF for Dana-Farber
      • S_WAL for Waltham
  • In the Event Definitions section, each event will have its corresponding OID.
    • SE_INFORMEDCONSENT as highlighted above in this example.
  1. To access the CRF OIDs, you will need to open the event definition. Click the View icon for the event you’re interested in. This will open the event definition screen as shown below.
  2. In the CRFs table, click the view icon for the CRF whose OIDs you want as highlighted in the image above for the first event.
  • In the View CRF Details table (above), record the OID for the Form.
    • Clicking the icon highlighted in the Actions column above will access the page for the CRF.
  1. For the CRF version you want, click the metadata icon (Item name link).
  • In the View CRF Version Details page, record the OIDs for the Group(s) and Item(s) (in that order).

Study XML File:

You can locate OIDs directly in the Study XML metadata file.

  1. On the Study Details screen, click the Download the 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.

2.2.8 Content Library

</p> <style>

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 those for vital signs or laboratory results. 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 Content 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 the library. Otherwise, the Library Management page will be empty.

You can use Library Management with Form Designer or the 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 templates (see type below).

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 and Filter

Enter text to search for an item.

You can filter the list by the type of item (Question, Block, or Template).

New

You can create a single question, a block of questions, or a full Form Template to add to the library.

To Create Content Library Items in Form Designer:

  1. Click the New button in the upper left-hand corner of the Library Management Screen.

For Questions or Blocks:

  1. Select Question.
  2. Click the + sign.
  3. Enter text for the question.
  4. Click +Add Question button.
  5. Select a question type.
  6. (Optional) Complete the question form as you normally would within form designer.
  7. (Optional) Repeat steps 3-8 until you have added all of your questions, adding multiple questions will create a block.
  8. Click Create.

For Form Templates:

  1. When you click the new button in step 1 select Template from the options
  2. Build a complete form as you would normally within the designer.
  3. Name your template and save.

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 the 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< strong>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 file for the item.

Upload XLS

  1. In the library management window, click the new button in the upper left-hand corner.
  2. Select Upload.
  3. Select the file name for the desired xls file.
    Note: this will automatically load as a template even if there is only a single question.

Collections

To Create a Collection:

  1. In the library management window, click the New button in the upper left-hand corner.
  2. Select collection.
  3. Enter a name for the collection.
  4. Click Create Collection.

To Rename a Collection:

  1. Click the collection.
  2. Click the ellipses.
  3. Click Rename.

To Delete a Collection:

  1. Click the 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 the Content Library in the 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 available, 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.

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.

2.2.9 Create and Configure Data Review Tables

Definition:

  • Data Review Tables: Custom tables of form data used to review data and perform bulk actions in Study Runner.

  • Primary form: A form within either a repeating event or one or more non-repeating events that is selected to use as the main form for the Data Review Table. Actions on the Data Review Table are based off of the Primary form (bulk Remove/Restore Primary forms).

Potential Uses:

  • Remove erroneous form data after an import: Quickly review form data in bulk after importing data (such as data from devices). If issues are noticed, the form data can be removed without having to go into each form individually. The issue can then be addressed, and the data can be imported correctly.
  • Bulk-close automatic queries: If automatic queries are set to appear incorrectly and the issue has been resolved, these automatic queries can be resolved in bulk.
  • Review information to catch potential errors: Create a data review table to track a participant’s weight from visit to visit and check for any potential errors. If an error is suspected, a query can be added or the value can be updated.

User Roles:

  • Investigators, Clinical Research Coordinators, Data Managers, Data Entry Persons, and Data Specialists.
  • Monitors can access Data Review Tables where they can view and close queries, but they cannot Remove or Restore records.
  • Site/Study Viewer users are not currently able to access Data Review Tables.

Data Review Tables are first created and configured within Study Designer by a Data Manager. After the table is configured and the study is published, the table can be accessed from the Tasks menu in Study Runner. 

Create a Data Review Table:

  1. Within Study Designer, click Table Design, then select the + Add a New Data Review Table link.

2. Add the table details including the table name and description (optional). Then select the primary form (and optional event) to use.

a. The Primary form is the form on which your table is based. Information based off of the Primary form will be displayed in the default columns on the table (Event Start Date, Form Status, Event Name, Event Status, Form Last Modified By, and Form Last Modified Date). The Primary form is the form which is removed when you click Remove Forms (the forms with additional items displaying on the table will retain their status).

b. Many forms are used for multiple events (Vital Signs can be used for the Baseline, Follow Up, and Treatment events). When an event is selected for the form, this means that only forms within the selected event will display.

3. Click into the grey box and select which items to display in the table. Only items that can be added to the table will be displayed. This list includes all items from the chosen form that are not in a repeating group, and all items from forms in non-repeating events that are not in repeating groups. Items in archived forms or archived events as well as items in repeating groups will not be able to be selected.

a. The items in the dropdown will be listed as a string in the form of “ItemName (EventName -> FormName)” and will be displayed in alphabetical order based on that string.

b. Type a key word in the grey box and press Enter to filter the list.

4. If needed, drag and drop the selected items to rearrange the order in which the corresponding table columns will appear, then click Save.

a. After the table is saved, Publish the study to see the table within Study Runner.

Note: If you edit a review table that has Archived items in it, the items will remain in the table (unless manually removed from the table) and the table can still be resaved. However, if the Archived items are removed from the table, these items cannot be added back.

Use the Data Review Tables page for information on accessing and using Data Review Tables within Study Runner.