This set of topics explains how you define (create) Case Report Forms (CRFs) and make changes to the defined forms. You define the form in an Excel spreadsheet file for use with Study Events in your OpenClinica system. OpenClinica presents the defined CRF in the web interface for users to collect Study Event data for a Subject.

To create and modify defined CRFs, your User Role or User Type requires appropriate permission.

Because defined CRFs are available for use across all Studies in OpenClinica, it does not matter what the current Study is when you create and modify them, but you must be at the Study level.

(If instead you want to enter or modify Event data for Subjects in CRFs, see View and Enter Event Data using the Subject Matrix.)

3.4.1 About CRFs in OpenClinica

A good way to familiarize yourself with a defined CRF is to look at its existing CRF .xls file and at the way OpenClinica presents it in the web interface:

  1. Click here to download a sample CRF defined for a Physical Examination, SAMPLE_PHYSICALEXAM_ENGLISH.xls. Save the file to your computer.
  2. Upload the defined CRF to your OpenClinica system.
    1. Set the current Study to the Study level.
    2. From the Tasks menu, in the Monitor and Manage Data module, select CRFs.
      The Manage Case Report Forms page opens.
    3. Click Create a New CRF.
      The Create a New Case Report Form page opens.
    4. In the MS Excel File to Upload field, click Browse, then navigate to the file you downloaded in step 1, SAMPLE_PHYSICALEXAM_ENGLISH.xls. Select the file, then click Open.
      The path to the filename is shown in the MS Excel File to Upload field.
    5. Click Preview CRF Version.
      The Check CRF Version Data page opens, showing the CRF in the web interface format.
    6. Click Continue.
      The Create a New CRF Version – Data Committed Successfully page opens.
  3. View the defined CRF in OpenClinica:
    1. From the Tasks menu, in the Monitor and Manage Data module, select CRFs.
      The Manage Case Report Forms page opens.
    2. For Sample Physical Exam – English Version, click the View icon.
      The defined CRF displays in the web interface format.
  4. In Excel, open the CRF file you downloaded, SAMPLE_PHYSICALEXAM_ENGLISH.xls.
  5. Compare the CRF when viewed in the web interface format to the defined CRF when opened in Excel.

A Sample Defined CRF when Viewed in the Web Interface:

CRF in Web Interface

Note that when the CRF is previewed after upload, or viewed through ‘Manage CRFs’, any hidden fields in the CRF are visible.

The Same CRF when Opened in Excel, Showing the Items Tab:

Defined CRF when opened in Excel, showing the Items tab

3.4.2 OpenClinica eCRF Specifications

OpenClinica provides a template to users for CRF design.  This section explains each of the fields in the template and how those fields are either dependent or independent of each other.  Best practices are provided as well as some examples of how the CRF Template can be used effectively.

Definitions and acronyms

  • CRF Case Report Form, created in OpenClinica by uploading a CRF definition based on the CRF Template Excel file.
  • Dynamics Skip Patterns/Skip Logic created using Rules and based on variables in the CRF template.
  • Group – A mechanism for logically associating items within a CRF. Items within the same group may repeat together within a CRF.
  • Item A variable within a CRF.
  • OIDs  Object Identifiers uniquely identify a study object such as a CRF, CRF Version, Item Group, or Item and are used to link objects to one another.  OIDs for a given class of object are unique within an instance of OpenClinica, with the exception of Rule OIDs, which are only guaranteed to be unique within a study.
  • Rules OpenClinicas mechanism to carry out cross form or cross field edit checks, skip logic and inserting data across CRFs. Rules are declared in XML and executed by the OpenClinica Rules Engine. Rules are declared external to the CRF Template but dependent on the variables defined in one or more CRFs.
  • SCD Simple Conditional Display.  A way of defining skip logic within the CRF Template, without the use of Rules.
  • Section A mechanism for organizing items within a CRF for layout purposes. All items in a given section appear on the same page in a CRF. Multiple sections are displayed as tabs within the CRF.
  • Tokens  A means of displaying a Study Object value for use in a URL (e.g. in a parameterized link) or for use in other scripts (e.g. jquery). Tokens can also be used in Left Item Text, Right Item Text, Header, and/or Subheader to pass item values. The supported tokens are: 

        ${studySubject} – Passes the current Subject ID

        ${studySubjectOID} – Passes the OID for the current Subject

        ${studyName} – Passes the current Study Name

        ${eventName} – Passes the current Event Name

        ${eventOrdinal} – For repeating Events, passes the Event repeat number (e.g., 2 for the second repeat)

        ${crfName} – Passes the CRF Name

        ${crfVersion} – Passes the CRF Version 

        ${item[item_name]} – Passes the Item value

3.4.2.1 CRF Template - General Constraints

 

The OpenClinica CRF Template can only be edited and saved as a Microsoft Excel 2003.xls file.  OpenOffice spreadsheets and later versions of Microsoft Excel can not be used reliably and may not be successful when uploaded to OpenClinica version 3.1.X.

The CRF Template is used to define the CRF on a client machine with MS Excel.  Once the required information has been provided in the template, it must be uploaded to OpenClinica through the Add CRF page.  Only certain privileged users are allowed access to this page.

During the upload process, a validation of the CRF design is performed. Errors that are caught at this stage will trigger messages to the user informing him of the error and changes necessary to fix the error. 

3.4.2.2 Scope of CRFs and Items

 

A CRF (with its associated versions, groups, and items) is defined globally within an instance of OpenClinica and may be used in one or more studies. The groups and items defined within a particular CRF exist within the scope of the CRF only (though they will have globally unique OIDs). The CRF Physical Exam may have an item with ITEM_NAME blood_pressure and the CRF Vital Signs can have an item also named blood_pressure. OpenClinica treats these items as separate entities and they will have separate OIDs. Response sets also exist within the scope of the CRF only.

A CRF definition may be shared across OpenClinica instances by loading the CRF template spreadsheet into each instance. Each instance of OpenClinica generates OIDs at CRF upload time and those OIDs must be unique within that instance. Therefore the OIDs for the same CRF and items may be different across OpenClinica instances.

3.4.2.3 CRF Versioning

 

OpenClinica supports multiple CRF versions being in use at the same time.  To create a new version, a user must keep the CRF_NAME field the same as the original, but update the CRF_VERSION field with a new value.  This new version is uploaded by selecting the Create New CRF Version icon instead of adding a CRF through the Build Study module.  The user does have the ability to overwrite a CRF Version if needed, however the CRF Version cannot have been assigned or used in any event definitions prior to the attempt to remove it.

When a new CRF Version is added, any item with the same ITEM_NAME as an item in a previous version of the CRF is treated as the same variable and will have the same OID, DESCRIPTION, and DATA_TYPE. The value of ITEM_NAME is case-sensitive, so items with ITEM_NAMEs ‘ItemA’ and ‘itema’ will be considered as different items by OpenClinica.

For Enterprise customers interested in using Datamart:

Please note that Datamart treats items in case-insensitive manner. Please make all ITEM_NAMES  case-insensitive if you plan to use Datamart. Special characters and Postgres reserved words should not be used as item names.

New items that did not exist in prior CRF versions will be added and an appropriate OID generated.

Item metadata vs Item form metadata

Items in a CRF have two types of attributes. Item metadata attributes describe core intrinsic properties of the item. These properties are independent of the CRF Version and cannot change across CRF Versions. These properties include:

ITEM_NAME

DESCRIPTION

DATA_TYPE

GROUP_LABEL

Response Sets (see discussion below)

The properties ITEM_NAME, DATA_TYPE, and RESPONSE_LABEL cannot be changed after the CRF is created.

Item form metadata attributes describe the items representation or behavior on a CRF and may have a different value in each version of a CRF. Most of the attributes in the Items Worksheet in the CRF Template fall into this category.

 Response sets

The item properties beginning with RESPONSE_ on the Items worksheet together define a response set in a CRF. The response set is a coded list of allowable values for the item. The response set is given a name (RESPONSE_LABEL) that allows it to be re-used within the CRF if desired, and the set itself is made up of a list of coded values (RESPONSE_VALUES_OR_CALCULATIONS) with corresponding text labels (RESPONSE_OPTIONS_TEXT). Each item in the list of coded values should meet the constraints defined by the item DATA_TYPE and WIDTH_DECIMAL.

Response sets are intended for use in items that utilize a form input control (INPUT_TYPE) that allows the user to select from a constrained list.  

* Note that the RESPONSE_VALUES_OR_CALCULATIONS attribute can also be used in a separate context to create calculated/derived items.

 

Versioning of response sets should not change the mapping RESPONSE_OPTIONS_TEXT – RESPONSE_VALUES_OR_CALCULATIONS, but it can delete or add new (_OPTIONS_TEXT – RESPONSE_VALUES_OR_CALCULATIONS ) pair to existing set of values. For example, an item is a single-select and its RESPONSE_OPTIONS_TEXT defined as Absent,Mild,Moderate,Severe,Life-threatening while

RESPONSE_VALUES_OR_CALCULATIONS defined as 1,2,3,4,5. In another version of CRF it is possible to drop or add several values, but you cannot redefine mapping by setting Absent to have value other than 1.

3.4.2.4 CRF Template Properties

 

The CRF Template contains five worksheets. Four of the worksheets are intended for input by the user creating the CRF while the fifth worksheet provides instructions about each of the fields of the Template.  When a user selects a cell in a column, a tooltip will popup explaining whether the field is Required or not, and other useful instructive text to help the user understand what the field is for.

In some cases HTML elements like Bold (<b>), Italics (<i>), Line Breaks (<br>), etc. can be used.  In the cases where HTML elements are supported, they are designated as such in CRF Template Elements.

In OpenClinica 3.3, Tokens, were introduced. These are available for use in Left or Right Item Text, Header, or Subheader. They can be used to display the Study Object value for use in a URL (as in a Parameterized Link) or for use in other scripts (e.g., jquery). The supported tokens are: 

    ${studySubject}

    ${studyName}

    ${eventName}

    ${eventOrdinal}

    ${crfName}

    ${crfVersion}

    ${item[item_name]}

Following is an example of a CRF that passes these tokens to a URL to bring up an image:

Example of use of a parameterized link

When the user clicks on the “Click here to open image” link, based on the following Right Item Text the CRF template, the imaging system (in this case www.example.com) is accessed and passes the values for studyName, eventName, crfName, and the SCAN_DATE item for the current Study, Event, and CRF.

Right Item Text:

<a href=”http://www.example.com/${studyName}/${eventName}/${crfName}/${item[‘SCAN_DATE’]}” target=”_blank”>Click here to open image</a>

 


3.4.2.5 CRF Template Elements

Definitions, restrictions and when to use the OpenClinica CRF Template Elements

OpenClinica CRF Design Template v3.5       
This worksheet contains important additional information, tips, and best practices to help you better design your OpenClinica CRFs.   
        
Note:
Each CRF version should be defined in its own Excel file.
     
WorksheetFieldRequiredField Description and InstructionsCan vary by CRF VersionRestrictionsWhen to useAllowable Values
CRF  This worksheet should have no more than one row    
 CRF_NAMEYesDefines the name of the CRF as it will be displayed in the OpenClinica user interface. When a user is assigning CRFs to an event definition, they will be viewing this name. A user performing data entry will identify the form by this name.

Best Practice: Include a short study identifier as part of your CRF name so that it is unique within your database instance. The first 12 characters of your CRF_NAME should be unique.

NoAlpha-numeric characters are allowed
255 characters max
UNIQUE
If the field is blank, the CRF will be rejected at upload time.Text
 VERSIONYes,
but does not display in Participate forms
Defines the version of the CRF as it will be displayed in the OpenClinica user interface. You cannot reuse a version number for the same CRF that has already been assigned to an Even Definition. If a particular CRF version has not been used in an Event Definition, you may overwrite the CRF version.YesAlpha-numeric characters are allowed
255 characters max
UNIQUE
If this is a new version of a CRF that already exists, the CRF_NAME must match the CRF_NAME of the pre-existing CRF in OpenClinica. 

A new version of a CRF would be needed due to a protocol change, adding or removing an Item from a CRF, or changing some of the questions.

Text
 VERSION_DESCRIPTIONYesThis field is used for informational purposes to keep track of what this version of the CRF was created for.YesAlpha-numeric characters are allowed
4000 characters max
NOT UNIQUE
This information appears as part of the CRF Metadata when the user clicks on View (original). This information is not displayed during data entry.Text
 REVISION_NOTESYesThis field is used to keep track of the revisions you made to this particular CRF.  YesAlpha-numeric characters are allowed
255 characters max
This information appears as part of the CRF Metadata when the user clicks on View (original). This information is not displayed during data entry.

If this is the first version of the CRF, you can simply state this is a brand new form.  Going forward, as you make changes and update the versions you can provide information on what is different between the first version and each subsequent version.

Text
Sections       
 SECTION_LABELYes,
but does not display in Participate form.
Must be unique in the worksheet and contain no spaces. The SECTION_LABEL is referenced in the Items Worksheet to associate Items with the appropriate section of the CRF. When the CRF is accessed for data entry, each Section will be a page.  The Items defined with the corresponding SECTION_LABEL will be shown on that single page.

This field is not displayed as part of the CRF but can be seen on the CRF Metadata page.  

No (added or removed only)No spaces
255 characters max
UNIQUE
This value will be used in the Items Worksheet to define where the Items will appear during data entry.

A CRF must have at least one Section.

Alphanumeric text, no spaces
 SECTION_TITLEYes,
but does not display in Participate form.
The value in this field will be displayed at the top of each page when a user is performing data entry, as well as in the tabs and drop down list used to navigate between Sections in a CRF. It does not have to be unique but should be a readable value that makes sense to people entering data.  An example would be ‘Inclusion Criteria’YesAll characters allowed
2000 characters max
This field must be used at all times.  If a CRF does not have a value for SECTION_TITLE the form will be rejected at upload time.

Long Section Titles may not display well.

Text
 SUBTITLENoA sub-title shown under the Section title.  YesAll characters allowed
2000 characters max
HTML elements are supported for this field.Text
 INSTRUCTIONSNoInstructions at the top of the Section (under the subtitle) that explains to the data entry person what to do on this section of the form.  YesAll characters allowed
2000 characters max
HTML elements are supported for this field. 

This field should be used if there are particular data entry instructions that should be conveyed or followed to users.

Text
 PAGE_NUMBERNoNote: Page_Number is a feature that will not be available in future versions of OpenClinica and should not be used.

The page number on which the section begins. If using paper source documents and have a multi-page CRF, put in the printed page number. 

YesAll characters allowed
5 characters max
OpenClinica version 3.3 and above: Do not use.

OpenClinica versions prior to 3.3: For the most part, this field is only used in studies collecting data on multi-page paper forms and then having the data keyed in at a central location performing double data entry.

Text
 PARENT_SECTIONNoNote: Parent_Section is a feature that will not be available in future versions of OpenClinica and should not be used.

Sections can be sub-sections of ones that have been previously defined.  Provide the parent section for this sub-section in this field.

Yes255 characters max
Must equal a valid SECTION_TITLE
OpenClinica version 3.3 and above: Do not use.

OpenClinica versions prior to 3.3: This field does not have any effect in the User Interface. It does not affect data being exported. This will be deprecated after version 3.1.3.

Text
Groups       
 GROUP_LABELYesMust be unique in the worksheet and contain no spaces. GROUP_LABEL is referenced in the Items Worksheet to associate Items with the appropriate Item group in the CRF. The GROUP_LABEL value will be used to generate the GROUP OID to be used in Rules, Data Import, and Export.

The field is not displayed as part of the CRF but can be seen on the CRF Metadata page. 

Best Practice: Each Item on the CRF should be associated with a Group_Label. The first five characters of Group_Label should be unique within your database instance.

No (added or removed only)Alpha-numeric
No spaces
255 characters max
UNIQUE
This field should be used in order to logically group Items together. Item Groups may be used to define repeating Items in the CRF, or for logical grouping of NON-REPEATING Items for easier data analysis once data has been exported from OpenClinica. If you don’t provide a Group_Label, all Items in the CRF will be part of a single group called UNGROUPED. This is not recommended.Text
 GROUP_LAYOUTYesREQUIRED. GRID formats associated Items into a table and allows rows to be added as needed. NON-REPEATING puts Items into a named, logical grouping (useful for Show/Hide functionality).

Defines the type of Item Group (GRID or NON-REPEATING). If left blank will default to NON-REPEATING. A layout of GRID means the Items defined as part of the Item Group will be displayed in a table where each Item is represented as a column, and users can add rows of data to the table as needed during data entry. In Participate, Grids do not display as tables but allow Participants to add repeating records as needed. When viewed in OpenClinica those records will display as a table.

If NON-REPEATING is chosen, the fields will be logically grouped together in the CRF metadata, but cannot repeat, and are displayed using the standard OpenClinica CRF layout. Logically associating Items as a NON-REPEATING Group can be used with Rules to implement show and hide logic.

YesGRID, NON-REPEATING (Blank)This field should be used to define the Item Groups as GRID (repeating) or NON-REPEATING.

NON-REPEATING: Item Groups can span multiple Sections of the CRF. Grouping is not a positional limitation but rather a logical association of Items.

GRID: Item Groups must appear in the same Section and must be placed together in the Items Worksheet. Definition of a repeating Item Group activates the use of the attributes GROUP_HEADER, GROUP_REPEAT_NUMBER and GROUP_REPEAT_MAX.

GRID, NON-REPEATING, Blank
 GROUP_HEADERNo, If used, will not be displayed in Participate.The value is displayed above the GRID when a user is performing data entry.

Used only when the GROUP_LAYOUT is equal to GRID. 

YesAll characters allowed
255 characters max
Only use when the layout is set to GRID.  This value is like a title for the group.  An example of a GROUP_HEADER would be Medications Log. 

The field can be left blank if you do not want a title or header.  If the Layout is set to NON-REPEATING, the value will be ignored and not displayed during data entry.

Text
 GROUP_REPEAT_NUMNoUsed only when the GROUP_LAYOUT is equal to GRID.

Specifies the default initial number of repeats to be displayed on the form. If left blank, only one row will be displayed by default.

YesInteger
Should be left blank for non GRID layout
This field should be used to specify how many rows of data should exist for the Item Group upon initiation of data entry, or in printing of a blank CRF from OpenClinica. If three rows of information, specify the number 3 in the field. When a user accesses the CRF, the row is repeated 3 times by default. 

A user will be allowed to add more rows up to the GROUP_REPEAT_MAX and even remove some of the rows displayed by default.

A number (e.g. 1, 2, 3).
 GROUP_REPEAT_MAXNoUsed only when the GROUP_LAYOUT is equal to GRID. 

This represents the total number of repeats a user will be allowed to add in the Item Group.  When left blank, the default number of repeats is 40, but you can specify more than 40 if necessary.

YesInteger
There is no max value
Should be left blank for non GRID layout
This field should be used to restrict users to a certain number of repeats for the GRID.  However, this restriction works only if data are entered through OpenClinica Web UI. If data are imported using Task-> Import Data option or through web services, all rows of data in the import file will be allowed to import, even if the rows of data in the import exceed the GROUP_REPEAT_MAX..
If GROUP_REPEAT_MAX is less than GROUP_REPEAT_NUMBER, the Group will have the GROUP_REPEAT_MAX number of rows on initial data entry displayed, and no additional rows can be added.
A number
 GROUP_DISPLAY_STATUSNoUsed in conjunction with Rules. If set to HIDE, the Item Group will not appear in the CRF when a user is entering data until certain criteria are met. This criteria is specified in a Rule using the ShowAction.

If left blank, the Group defaults to SHOW. 

YesBlank, SHOW, HIDEIf set to SHOW, all Items in the Group are displayed in the CRF.

If set to HIDE, this can be used with a Rule to conditionally display an entire Group of Items.

If left blank, the default is SHOW.

Hide, Show or leave blankH26
Items       
 ITEM_NAMEYesThe unique label or variable name for the data element.

The field is not displayed as part of the CRF but can be viewed as part of the CRF and Item Metadata, and is shown in the Discrepancy Notes and Rules modules.

This field is case-sensitive. Items with names item1 and Item1 will be treated as different Items. This can cause issues with many data analysis tools and should be avoided in most cases.

For Enterprise customers interested in using Datamart:
Please note that Datamart treat Items in case-insensitive manner. Please treat all ITEM_NAMES as case-insensitive.

Also for use with Datamart, Postgres has a list of reserved words and special characters, which should not be used as Item Names. For a complete list, please see
http://www.postgresql.org/docs/8.4/static/sql-keywords-appendix.html.

Best Practice: The first five characters of Item_Name should be unique within your instance. If you are using SAS, Item_Name is truncated to eight characters.

No (added or removed only)English
No spaces
255 characters max
Case-sensitive
UNIQUE
This field should be used at all times.

ITEM_NAME will be used to form the OID and the variable name when exporting data from OpenClinica.  Brevity is recommended for the value as it will be used to generate the unique OC_OID.

Re-use of the same ITEM_NAME across CRF Versions indicates the variable is the same Item. Once created, an Item Name cannot be modified within the CRF. See CRF Versioning and Scope of CRFs and Items in this document for more detail.

Alphanumeric text, no spaces
 DESCRIPTION_LABELYesThe description or definition of the Item. Should give an explanation of the data element and the value(s) it captures. It is not shown on the CRF but is in the data dictionary.NoRequired
All characters allowed
4000 characters max
This field must be used at all times.  Provide a description that will help explain what the variable means and what values it is collecting. 

For example, if the variable were looking to collect height, the DESCRIPTION_LABEL would be This variable collects the height of the subject.  It captures the value in inches.

This field should not be changed in any subsequent versions of the CRF. If you do change it  and you are the owner of the CRF the DESCRIPTION_LABEL attribute for this Item will be changed for all versions of the CRF.

 
 LEFT_ITEM_TEXTNoDescriptive text that appears to the left of the input on the CRF. Often phrased in the form of a question, or descriptive label for the form field input.  YesAll characters allowed
2000 characters max
This field should be used as a way of describing the expected input to users entering or reviewing CRF data. The value of LEFT_ITEM_TEXT is displayed to the left of the form input. The text wraps after the first 20 characters.

An example question would be What is the subjects height?  Or, a simple one word height suffices as well.

If the Item is part of a GRID, the LEFT_ITEM_TEXT is displayed as a column header above the field and not be displayed to the left of the Item.

HTML elements are allowed; however, only a limited subset of tags is officially supported (bold <b></b>, italics <i>, underline <u>, superscript <sup>, subscript <sub>, line break <br>, link <a href=””>, image <img src=””>).

Tokens can also be used to substitute Study Object values. These can be used to display the Study Object value for use in a URL or for use in other scripts (e.g. jquery). The supported tokens are:
    $ {studySubject}
    $ {studySubjectOID}
    $ {studyName}
    $ {eventName}
    $ {eventOrdinal}
    $ {crfName}
    $ {crfVersion}
    $ {item[item_name]}
For more information please see:
https://docs.openclinica.com/3.1/study-setup/build-study/create-case-report-forms-crfs#content-title-5514

 
 UNITSNoUsed to define the type of values being collected.  It appears to the right of the input field on the CRF.No64 characters maxIf you are collecting data in inches, this field can specify your units as inches, IN, or in. 

This field should not be changed in any subsequent versions of the CRF. If you do change it and you are the owner of the CRF and no data have been entered for this Item, the UNITS attribute for this Item will be changed for all versions of the CRF.

There are no edit checks associated specifically with units. This will appear as text to right of the input field and will be displayed between parenthesis.

If you are exporting to CDISC ODM XML format, this will appear in the metadata as measurement units.

 
 RIGHT_ITEM_TEXTNoDescriptive text that appears to the right of the form input on the CRF, and to the right of any UNITS that are specified too. Often phrased in the form of a question, or supporting instructions for the form field input.  YesAll characters allowed 2000 characters maxThis field can be used as a way of describing the expected input to users entering or for field-specific instructions. The value of RIGHT_ITEM_TEXT is displayed to the right of the form input. The text wraps after the first 20 characters.

An example of use of right Item text is If other, please specify.

If the Item is part of a GRID, the RIGHT_ITEM_TEXT will be ignored and never displayed.

HTML elements are allowed; however, only a limited subset of tags is officially supported (bold <b></b>, italics <i>, underline <u>, superscript <sup>, subscript <sub>, line break <br>, link <a href=””>, image <img src=””>).

Tokens can also be used to substitute Study Object values. These can be used to display the Study Object value for use in a URL or for use in other scripts (e.g. jquery). The supported tokens are:
    $ {studySubject}
    $ {studySubjectOID}
    $ {studyName}
    $ {eventName}
    $ {eventOrdinal}
    $ {crfName}
    $ {crfVersion}
    $ {item[item_name]}
For more information please see:
https://docs.openclinica.com/3.1/study-setup/build-study/create-case-report-forms-crfs#content-title-5514

 
 SECTION_LABELYes,
but does not display in Participate form.
All Items in a given Section are displayed on a single web page when the user is entering data, and appear in the order in which they are entered on this Template.

Every Item must be assigned to a Section of the CRF. 
SECTION_LABEL does not display in Participate.

YesValue must exist on the Sections WorksheetFor example, you might want all of the information collected as part of a physical exam such as height, weight, blood pressure, and heart rate should be on the same Section.A valid SECTION_LABEL as defined in the ‘Sections’ worksheet
 GROUP_LABELYes,
but does not display in Participate form.
Assigns Items to an Item Group.  If the Group is GRID the Items need to have the same SECTION_LABEL as all other Items in the Group, and must be consecutively defined in the ITEMS worksheet.

Best practice:
All Items should be assigned to a GROUP_LABEL.

GROUP_LABEL does not display in Participate.

YesValue must exist on the Groups WorksheetGROUP_LABEL should be used to identify whether an Item belongs to an Item Group defined in the GROUPS worksheet.

If the Group is a repeating group (GRID layout), each Item in the Group is displayed as a column in the grid.

Warning, too many Items in a Group, or use of long LEFT_ITEM_TEXT values, will make the grid extremely wide and force the data entry user to scroll the page to the right to complete data entry.

For NON-REPEATING Items, specify a Group Label to be used to logically assemble related Items together for easier data analysis.

OpenClinica 3.1.2 and previous versions allowed Items to be moved from one Item Group to another between versions (i.e. UNGROUPED Items could later be grouped). While  OpenClinica allowed this functionality, CDISC ODM does not support this type of structure change between different CRF versions. As a result, these types of structural changes could break extracts which contain the effected CRF. A new column has been introduced to View CRF page to allow a user to verify CRF integrity. The new table, called Items gives a list of Items in a CRF where the last two columns (Version(s) and Integrity Check) provide information about which version(s) the Item belongs to and if the Item passes the integrity check (verifying that the Item has not been assigned to more than one Item Group).

OpenClinica 3.1.3 and future versions will not allow Items to be assigned to different Item Groups between versions.

Must be the GROUP_LABEL of a section defined in ‘Groups’ worksheet
 HEADERNoContains text that used as a header for a particular Item. Using this field will break up the Items with a distinct line between the header information and the next set of Items. The text is bolded to call greater attention to it.  YesAll characters allowed
2000 characters max
HTML elements are allowed; however, only a limited subset of tags is officially supported (bold <b></b>, italics <i>, underline <u>, superscript <sup>, subscript <sub>, line break <br>, link <a href=””>, image <img src=””>).

Tokens can also be used to substitute Study Object values. These can be used to display the Study Object value for use in a URL or for use in other scripts (e.g. jquery). The supported tokens are:
    $ {studySubject}
    $ {studySubjectOID}
    $ {studyName}
    $ {eventName}
    $ {eventOrdinal}
    $ {crfName}
    $ {crfVersion}
    $ {item[item_name]}
For more information please see:
https://docs.openclinica.com/3.1/study-setup/build-study/create-case-report-forms-crfs#content-title-5514

This field can be used as a replacement for left and right Item text or as a replacement for instructions.  It allows a greater number of characters, along with bolding the text, to get the data entry persons attention.

 
 SUBHEADERNoThis field can contain text that will be used underneath the HEADER, or independently of a HEADER being provided.  The text will be separated by a line and have a grey background.  YesAll characters allowed
240 characters max
HTML elements are allowed; however, only a limited subset of tags is officially supported (bold <b></b>, italics <i></i>, underline <u></u>, superscript <sup></sup>, subscript <sub></sub>, line break <br>, link <a href=””>, image <img src=””>).
 
Tokens can also be used to substitute Study Object values. These can be used to display the Study Object value for use in a URL or for use in other scripts (e.g. jquery). The supported tokens are:
  $ {studySubject}
  $ {studySubjectOID}
  $ {studyName}
  $ {eventName}
  $ {eventOrdinal}
  $ {crfName}
  $ {crfVersion}
  $ {item[item_name]}
 For more information please see:
 https://docs.openclinica.com/3.1/study-setup/build-study/create-case-report-forms-crfs#content-title-5514
 
 This field can be used as a replacement or augmentation for left and right item text or as a replacement/augmentation for section/group instructions. It allows a greater number of characters, along with providing a grey background to the text in order to get the data entry users attention.
 
 PARENT_ITEMNoDO NOT USE.

This will not be supported in future versions of OpenClinica and should not be used.

Historically, this field could contain an ITEM_NAME that immediately preceded this Item, and was in the same Section. This would cause the child Item to be indented underneath the ITEM_NAME specified.

YesValue for ITEM_NAME must already exist in the CRF and immediately precede the current ITEM
Only one level of indention is allowed.
Do not use Parent_Item in OpenClinica version 3.3 and above.

In OpenClinica versions prior to version 3.3, this can only be used with NON-REPEATING Items and must be a valid ITEM_NAME.  It is used strictly for visual purposes in the user interface when people are entering data.

Use of this field is not recommended. It will be deprecated in a future release.

 
 COLUMN_NUMBERNo, If used, will not be displayed in Participate.Data entry screens are set up by columns.  By default a blank value will put the Item in column 1. To have NON-REPEATING Items show up on a horizontal plane next to each other, specify column numbers greater than 1.YesIntegerThis is to be used with only NON-REPEATING Items and controls the display of multiple Items on a single row.  If you set the column to 3 for an Item, the previous two Items in the worksheet should have COLUMN_NUMBERS of 1 and 2.  Otherwise, your Item will be displayed in the first column.

Use of COLUMN_NUMBERS greater than 3 is not recommended due to typical screen width limitations.

 
 PAGE_NUMBERNoDO NOT USE.

This will not be supported in future versions of OpenClinica and should not be used.

YesAlpha-numeric
5 characters max
Note: Page_Number will not be available in future versions of OpenClinica, so it is recommended that you do not use it. 
 QUESTION_NUMBERNo, If used, will not be displayed in Participate.This field is used to specify an identifier for each Item on the Items worksheet.  It appears to the extreme left of the LEFT_ITEM_TEXT. If LEFT_ITEM_TEXT was left blank, to the left of the form input.YesAlpha-numeric
20 characters max
Used to display question numbers on a CRF. 
 RESPONSE_TYPEYesThe type of input display you would like to use for a given Item on the CRF. It is different from DATA_TYPE. RESPONSE_TYPE reflects the display; DATA_TYPE defines how it is stored in the database. YesOption must be selected from the drop down box:
-text
-textarea
-single-select
-radio
-multi-select
-checkbox
-calculation
-group-calculation
-file
-instant calculation
Text: a rectangular box to enter information on a single line (3999 character limit)

Textarea: a multi-line box for entering information
(3999 character limit)

Radio and Single-Select only allow one option to be chosen for an Item.  Radio buttons cannot be deselected in the user interface once an option has been chosen.

Multi-Select and Checkbox allow multiple options to be selected at once.

File allows a file to be uploaded and attached to the CRF by the data entry person. Any file type is acceptable.
(10MB size limit) 

Calculation and Group-Calculation are used to derive values. Calculations allow for the execution of arithmetic expressions and support some basic functions. The calculations use values from previous fields within the same CRF as variables.  The calculated field cannot be directly edited by the data entry person and will appear grayed out.  Group-calculation allows the user to find a value based on the values in a column of a GRID (e.g. sum).
The group-calculation should not be contained in a repeating group, rather the variable that is being used in the calculation should be in a GRID while the calculated field itself is NON-REPEATING.

The values of calculated fields are generated when the user saves the Section of the form.

Forced reason for change (when turned on) is not enforced for calculated fields.

Instant-calculation (introduced in 3.1.3) is used to populate a destination field with date/time information when content of a trigger field is changed. The trigger field must precede the instant-calculation field.  This is a client side action; it is executed by triggering an on change function defined by the CRF designer in the RESPONSE_VALUES_OR CALCULATIONS field in the CRF template. The on change function takes arguments of an Item Name (trigger item) and value. The Item Name indicates the name of trigger field. The value indicates what date format should be used (two variables may be used: _CURRENT_DATE    the current server date, _CURRENT_DATE_TIME  – current server date and time).
Please note that instant-calculation field can be used in a GRID only if its trigger field is on the same row of the GRID. The trigger field for an instant-calculation field can be of any response type.

 
 RESPONSE_LABELYesCreate a custom label associated with a response set. This label must be defined once and may be reused by other Items with the same responses (e.g. Yes, No) and values. No80 characters max
Must be alphanumeric
In order to facilitate the creation of a CRF, unnecessary duplication of RESPONSE_OPTIONS_TEXT and RESPONSE_VALUES_OR_CALCULATIONS values can be mitigated by the RESPONSE_LABEL.  If the same options and values are going to be used for multiple Items like Yes, No and 1,2, provide the information once and enter a unique response label.  This label can be used throughout the rest of the Items worksheet so other Items will use the exact same options and values. If a RESPONSE_LABEL is reused within a CRF, the RESPONSE_OPTIONS_TEXT and RESPONSE_VALUES_OR_CALCULATIONS must be left blank or exactly match the values of the original RESPONSE_LABEL in the CRF.Alphanumeric text, no spaces
 RESPONSE_OPTIONS_TEXTNoA comma delimited string of values that will be used as the options to be chosen by a data entry person when they are entering data in a CRF. Yes (with limitations)Required for each unique RESPONSE_LABEL
4000 characters max
This field is only used for checkbox, multi-select, radio and single-select fields.  This will be the text displayed to the data entry person, which they will choose for each Item.  If the options themselves contain commas (,) you must escape the commas with a /Comma-delimited list of values
 RESPONSE_VALUES_OR_CALCULATIONSNoIf the field is not a calculation or group-calculation, this will be a comma-delimited string of values that will be used as the values saved to the database when a user chooses the corresponding RESPONSE_OPTIONS_TEXT.

If this is a calculation or group-calculation field, it will be an expression that takes the inputs of other Items in the Items worksheet that are of INT or REAL data type to calculate a value.

Yes (with limitations)Required for each unique RESPONSE_LABEL
4000 characters max
For checkbox, multi-select, radio and single-select fields, this will be the values that correspond to a RESPONSE_OPTIONS_TEXT.  The number of options and values must match exactly or the CRF will be rejected when it is uploaded into OpenClinica. 

The following calculations are allowed in this field if the RESPONSE_TYPE is calculation: sum(), avg(), min(), max(), median(), stdev(), pow(), and decode().
Cumulative calculations on a group of repeating Items must be of type group-calculation. Only cumulative calculations on the entire set of repeating items are allowed. The allowed functions are sum(), avg(), min(), max(), median(), and stdev().
For example, in an invoice with a repeating group of line Items, the calculation for a total price would be the group-calculation func: (sum (LINE_ITEM_PRICE)).
Instant calculation fields should use this field to define the onchange() function with arguments of an Item Name (the trigger Item) and value.

Comma-delimited list of values
 RESPONSE_LAYOUTNoThe layout of the options for radio and checkbox fields.  The options can be HORIZONTAL (left to right) or VERTICAL (top to bottom). In Participate the response layout will automatically adjust to optimize display on the Participant’s device.YesBlank, Horizontal, VerticalLeaving the field blank or selecting Vertical displays the Items in a single column from top to bottom. Choosing Horizontal will put the Items in a single row, left to right. Response Layout will automatically adjust to optimize display on different devices.Horizontal or Vertical
 DEFAULT_VALUENo, If used, will not be displayed in Participate.Default text for RESPONSE_OPTIONS_TEXT 
Commonly used for response type single select to provide additional instructions for data entry. For example, select one.
Yes4000 characters maxUse this to specify an instruction (for example: “Select one”) that will appear in the input field. For single-select default value does not have to be part of the response set. It will be interpreted as a blank value if the user does not choose anything.

Default values can be used for the following RESPONSE_TYPEs:
TEXT
TEXTAREA
SINGLE-SELECT
MULTI-SELECT
CHECKBOX

Note:
Be careful in using this field because if the default value corresponds to an option in the response set, it will be saved to the database even if the user does not select it.  

ST – Character String
INT – Integer
REAL – Floating
DATE – Date                 PDATE – Partial Date       FILE – File
 DATA_TYPEYesThe data type is the format in which the value is stored in the database. NoRequired
Option must be selected from the drop down box:
-ST
-INT
-REAL
-DATE
-PDATE (Not supported in Participate forms)
-FILE
ST (String): Any characters can be provided for this data type.

INT (Integer): Only numbers with no decimal places are allowed for this data type.

REAL: Numbers with decimal places.

DATE: Only full dates are allowed for this data type.  The default date format the user must provide the value in is DD-MMM-YYYY.

PDATE: Partial dates are allowed for this data type.  The default date format is DD-MMM-YYYY so users can provide either MMM-YYYY or YYYY values. (Not supported in Participate forms.)

FILE: This data type allows files to be attached to the item.  It must be used in conjunction with a RESPONSE_TYPE of file.  The attached file is saved to the server and a URL is displayed to the user viewing the form. The maximum file size that can be uploaded is 10 megabytes. There is no file type restriction.

This field should not be changed in any subsequent versions of the CRF. If you do change it and you are the owner of the CRF and no data have been entered for this Item, the DATA_TYPE attribute for this Item will be changed for all versions of the CRF. If original DATA_TYPE for the Item was DATE, owner of the CRF can change it to PDATE even if data have been submitted for the CRF.

 
 WIDTH_DECIMALNo, If used, has no effect in Participate.Specify the width (the length of the field) and the number of decimal places to use for the field

Has no effect in Participate.

YesNot required.

If provided must be in the form w(d) as follows:

w integer from 1 to 26, or literal w if INT or REAL.  If ST, from 1 to 4000 is allowed.

d literal d. if the item has DATA_TYPE of REAL, may also be an integer from 1 to 20. d cannot be larger than w

Defines the width (the maximum allowed length of the field) and the number of decimal places to use for the field in the form w(d).

The first input defines the width of the field. The second input specifies the number of decimal places for the field, if the item has a DATA_TYPE of REAL.

The WIDTH_DECIMAL attribute should only be used for Items with the ST, INT or REAL data types. The width attribute specifies the length of the field treated as a string, so even if the Item is of type INT or REAL, leading/trailing zeroes and decimal points count towards the width.

For Items of type REAL, evaluation of the width occurs prior to evaluation of the decimal, so values exceeding the specified or system default width will be rejected even if they could be rounded to a length within the width limit.

Examples.:                                                     
DATA_TYPE REAL, WIDTH_DECIMAL 5(1) Allows a maximum of 5 characters with only 1 decimal place. OpenClinica will accept 12345 and 1234., 123.4, or 12.30  but will not accept 012345 or 123456.

Inputs such as 12.345 or 1234.5678 or 012345 or 12.300 will be allowed and rounded.

REAL w(4) Allows up to OpenClinicas maximum length for an Item of ST, INT, or REAL (26 characters), with any decimal in excess of 1/10000th rounded to the 4th decimal place.

REAL 20(d) Allows a maximum length of 20 and decimal length of 4 (the default in OpenClinica).  .

ST 20(d) or INT 20(d) Allows a maximum length of 20 characters.

If the DATA_TYPE of the Item is DATE, PDATE, or FILE, the WIDTH_DECIMAL attribute should be left blank.

Please be advised that OpenClinica is not tuned to process very large REAL numbers or numbers with many digits after decimal point. So, numbers like 1234.123456789012345589 may not be validated properly to their format. For more complex scenarios where precision above 20 digits is required, it may be better to use a regular expression to verify the input.

 
 VALIDATIONNo, If used, has no effect in Participate.Specify a validation expression to run an edit check on this Item at the point of data entry.

Has no effect in Participate; all validation for Participate must be written in Rules.

Yes1000 characters maxThe validation will run when the user hits ‘save’. If the user has entered data, which satisfy the validation expression, data will save normally. If the value entered does not meet the requirements of the validation, an error message will appear (i.e., the VALIDATION_ERROR_MESSAGE) and the user will need to correct the value or enter a discrepancy note to continue. The validation should be of the format “expressionType: expression”. Must be between 1 and 1000 characters and is an optional field.

regexp:

This Supports Java-style regular expressions (similar to Perl). For more information, see http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html

Examples:
This example requires a three-letter string (all uppercase)
regexp: /regular expression/ = regexp: /[A-Z]{3}/

func:

Supports built-in library of basic integer functions. Currently supported functions include:
(1) greater than – gt(int) or gt(real)
(2) less than – lt(int) or lt(real)
(3) range – range(int1, int2) or range(real1, real2)
(4) gte(int) or gte(real)
(5) lte(int) or lte(real)
(6) ne(int) or ne(real)
(7) eq(int) or eq(real)

Examples:
This example requires a number between 1 and 10
func: func(args) = func: range(1, 10)

 
 VALIDATION_ERROR_MESSAGENo, If used, has no effect in Participate.Defines the error message provided on the data entry screen when a user enters data that does not meet the VALIDATION.

Has no effect in Participate.

Yes255 characters max
Required if VALIDATION is provided
Must be used when a VALIDATION is specified. The message should be clear to the data entry person as to what the problem is. 
 PHIYesSignifies whether this Item would be considered Protected Health InformationNoBlank, 1, 0Leaving the field blank or selecting 0 means the Item would not be considered Protected Health Information.  This flag does not do anything to mask the data or prevent people from seeing it.  The field is used as a label only.
When creating a data set, this label will show in the metadata and the user could choose to include this Item in the dataset (create dataset step) or not based on this label.

This field should not be changed in any subsequent versions of the CRF. If you do change it and you are an owner of the CRF the PHI attribute for this Item will be changed for all versions of the CRF.

0 or 1
 REQUIREDYesThis field indicates whether a value must be entered in order to save the data entered in that Section.

In OpenClinica, for REQUIRED fields, users must either enter a value or provide a discrepancy note.

In Participate, patients must enter information in required fields to submit data to OpenClinica.

YesBlank, 1, 0This can be used for any RESPONSE_TYPE.

Leaving the field blank or selecting 0 means a value is not required.

In OpenClinica, if 1 is selected, the data entry person must provide a value or enter a discrepancy note explaining why the field is left blank. 

In Participate, if 1 is selected, patients must enter information  to submit data to OpenClinica.

blank, 0 or 1
 ITEM_DISPLAY_STATUSNoUsed in conjunction with Dynamics in Rules or SIMPLE_CONDITIONAL_DISPLAY. If set to HIDE, the Item will not appear in the CRF when a user is entering data unless certain conditions are met. The conditions for display are specified with a Rule using the ShowAction, or via SIMPLE_CONDITIONAL_DISPLAY. If left blank, the value defaults to SHOW.YesBlank, SHOW, HIDEIf you would like to design skip patterns and dynamic logic for a single Item, set the display status to HIDE.  When the form is accessed for data entry, the Item will initially be hidden from view from the user.  With Rules, another value can trigger the Group of Items to be shown instead of hidden.

Instead of Rules, you can also use the SIMPLE_CONDITIONAL_DISPLAY field to decide when this Item should be shown.  SIMPLE_CONDITIONAL_DISPLAY only works with Items set to HIDE.

Hide, Show or leave blank
 SIMPLE_CONDITIONAL_DISPLAYNo, If used, has no effect in Participate.Does not apply to Participate forms.

Contains 3 parts, all separated by a comma:  ITEM_NAME, RESPONSE_VALUE, Message.

ITEM_NAME – The Item name of the field determining whether this hidden Item becomes shown.
RESPONSE_VALUE – The value of the ITEM_NAME that will trigger this hidden Item to be shown
Message – A validation message that will be displayed if this Item has a value but should not be shown anymore.

YesComma separated listSimple Conditional Display works with Items that have a defined response set (radio, checkbox, multi-select and single-select fields).  The hidden Item can be of any response type.

SIMPLE_CONDITIONAL_DISPLAY (SCD) has an effect only when ITEM_DISPLAY_STATUS (IDS) of the Item is set to HIDE. Several levels of hierarchy of Simple Conditional fields can be nested hierarchically. The Items must be in the same section of the CRF

For example, assume there is a SEX Item with response options of Male, Female, and response values of 1,2.  If the user chooses Female option, additional questions about pregnancy are asked. If Male is chosen, these questions are hidden. However, if the user chooses Female, fills in pregnancy data and after that gets back to the SEX Item and switches the answer to Male, the Items about pregnancy will remain on the screen (not hidden). The user can delete pregnancy answers and in that case the UI Items will get hidden.

Note that the database gets updated only on SAVE. In the above example the system will allow saving inconsistent data (SEX = Male, but pregnancy Items filled), but it is up to a user to create discrepancy fields for them explaining the situation.
Note that radio button controls cannot be deselected, meaning there is no way to delete its value once it has been selected.

 
 
  

 

 

3.4.3 Overview of Creating and Modifying CRFs

Before defining the CRF, design it by identifying all the Items that will be on it, the parameters for each Item, and how they will be organized on the form. For guidelines, see Designing a CRF.

This is the overall process for defining a Case Report Form (CRF) for use in your OpenClinica system:

  1. Download the CRF template or an existing, defined CRF. For detailed instructions, see Create a CRF.
  2. Modify the Items and other content in the defined CRF using Microsoft Excel. See Providing Content for a Defined CRF.
  3. Upload the defined CRF to your OpenClinica system, then identify and correct any errors.
  4. Assign the defined CRF to an Event Definition in a Study as part of the Build Study process. Review the Event Definitions for the Sites in the Study, and if necessary, modify the parameters for the defined CRF at the Sites in the Study.

3.4.3.1 About CRF Versions

You can use a defined CRF in multiple Event Definitions and in multiple Studies in OpenClinica. You can also create different versions of the defined CRF. When you assign a CRF to a Study Event, you can specify which versions of the CRF are available to that Event and can specify the default version to be used. For example, you can create a defined CRF in English and create another version in Spanish; then, when a user completes the CRF for a Study Subject, the user can choose the version of the CRF based on the language they prefer to work with. 

When you define a CRF, OpenClinica creates a parent record (called the “original”), and a version that can be used to collect data. When you create a new version of the CRF, it has the same name as the “original,” but has a different version label assigned to it. When you make a change to a defined CRF, if there are other versions of the defined CRF that the change applies to, you will need to make the change to each version of the defined CRF.

3.4.4 Designing CRFs

When you design a CRF in OpenClinica, you can base it on an existing form you use (for example, a paper version), if you have one. But you will need to modify the form design so it works well in the OpenClinica web interface and takes advantage of OpenClinica’s features. Whether or not you have an existing form, you can benefit from these guidelines for designing the form before you create the defined CRF:

  1. List all the information (Items) you need to collect and record the parameters for each Item. For example, if you need to capture the Subjects temperature, the Item is Temperature, it is required, and the parameters are any number between 95.0 and 103.9, with up to one decimal place, in degrees Fahrenheit. You specify the range so that when a user enters data into the form, OpenClinica flags a value outside the acceptable range for further action.
  2. Determine if you will put all of the Items in one CRF or in multiple CRFs:
    • If a portion of the CRF can be used for other Events or other Studies, you might want to define a CRF for just that portion so you can reuse it, and define a different CRF for the rest of the Items.
    • If the information will be collected at different times during the Event, or at different physical locations (even within a Site), consider defining separate CRFs for each, or separate sections within the CRF for logistical convenience.
  3. Determine the sections in the CRF and what Items to put in each section. When you enter data into a CRF, you save one section at a time, so fewer Items in a section minimizes the risk you will lose data if you accidentally close a CRF without first saving it. Fewer Items in a section also means the page opens quicker, makes it easier to locate an Item, and minimizes the need to scroll.

3.4.5 Create a CRF

Before defining a CRF, you need to create the CRF you will use as a basis:

  1. From the Tasks menu, in the Study Setup module, select Build Study.

    The Build Study page displays.

  2. For the Create CRF task, click the View icon.

    The Manage Case Report Forms (CRFs) page opens.

    Manage CRFs Table, Study Setup

  3. From the Manage Case Report Forms page, download the CRF you will use as a basis for defining the CRF.
    Note that when you save the Excel file in this process, the Excel filename (the name that precedes .xls) is not used by OpenClinica in any way.

    Choose one of the following options to download the CRF you will use as a basis:
    • Download an Existing Defined CRF: When you want to define a CRF to be similar to one already in your OpenClinica system, download the existing defined CRF to use as a basis.
      1. From the Manage Case Report Forms page, click the Download icon in the Actions column for the version of the CRF you want to download.
      2. Save the file to your computer using a unique, descriptive name.

      (Note that this is not the same as Creating a New Version of an Existing CRF)

    • Download a Defined CRF from the CRF Library: You can use a defined CRF from the OpenClinica library as a basis for the CRF you are defining. The library includes CRFs for common types of clinical forms that were defined by OpenClinica experts and are aligned with CDISC Clinical Data Acquisition Standards Harmonization (CDASH) standards, as well as CRFs defined by the OpenClinica community.
      1. Go to the CRF Library page of the OpenClinica documentation site.
      2. Click Login, then log in using your OpenClinica username and password.
        The CRF Library page displays.

      3. Select the link for the version of OpenClinica that you are using.
        The list of available eCRFs displays:

      4. Click the link for the domain you are interested in. For example, Adverse Events.
        The domain page displays and may include multiple versions of forms.

      5. Select the link for the form that best meets your needs.
        If applicable, Rules associated with the form are available and should be downloaded in addition to downloading the form.
      6. Save the CRF and associated Rules to your computer using unique, descriptive names.
    • Download a Blank CRF Template: If you have experience defining CRFs or there are no existing CRFs that are similar to what you need, use a blank template:
      1. From the Manage Case Report Forms page, click Blank CRF Template.
      2. Save the template to your computer using a unique, descriptive name.

After creating the CRF, provide content for it using Excel, then upload the defined CRF to OpenClinica.

3.4.6 Providing Content for a Defined CRF

When you define a CRF for use in OpenClinica, you use Excel (1997 to 2003 version) to provide the content in these four tabs (sheets) of the CRF .xls file:

  • CRF
  • Sections
  • Groups
  • Items

Each tab contains column headers that specify what belongs in that column; do not modify the column headers.

The fifth tab contains complete instructions for providing content for the CRF. You can also access instructions when you are providing content in the other tabs: click a column header and detailed instructions for that column display in a pop-up window.

To familiarize yourself with how the defined CRF in Excel relates to the presentation of that CRF in the OpenClinica web interface, see About CRFs in OpenClinica.

When you are first learning to provide content for defined CRFs for OpenClinica, work on only one or two Items at a time.

For more information, see OpenClinica eCRF Specifications in the OpenClinica Technical Documentation.

 

Instructions Tab in the Defined CRF:

Defined CRF when opened in Excel, showing the Instructions tab

 

Clicking a Column Header in the Defined CRF Displays Instructions for that Column in a Pop-Up Window:

Defined CRF showing pop-up instructions

3.4.7 Upload a Defined CRF

After using Excel to provide content for a defined CRF, upload the CRF to OpenClinca:

  1. From the Tasks menu, in the Study Setup module, select Build Study.
    The Build Study page opens.
  2. For the Create CRF task, click the View icon.
    The Manage Case Report Forms page opens.
  3. Click Create a New CRF.
    The Create a New Case Report Form page opens.

    Create New Case Report Form

  4. Click Browse, then navigate to the defined CRF you want to upload. Select the file and click Open.
  5. In the Create a New Case Report Form page, click Preview CRF Version.
    The Check CRF Version Data page opens.
  6. If there are any errors, OpenClinica reports them at the top of the page and provides details for the cells containing the errors below that. Click Go Back, correct the errors in the defined CRF using Excel, and repeat steps 4 through 6.

    Example of an Error Message for a Defined CRF:

    Error Message when Creating CRF File

    Example Showing Details for the Errors that are in the Defined CRF:

    Cells Showing Errors in CRF Excel File

  7. When the defined CRF you uploaded is free of errors, OpenClinica displays a preview of the web interface for the CRF, and the Alerts & Messages sidebar panel displays a success message. Review each section of the CRF in the web interface preview (click the tab for a section to show it), viewing drop-down lists, checking wording and arrangement of Items, and so on. Make notes of anything you want to change. To make changes, click Cancel, make changes using Excel and save the file, then repeat steps 4 through 6. (Note: do not click Continue while you are still changing the content of the defined CRF. If you do click Continue but still want to make changes, you will need to replace the existing CRF or create a new version of it.)

    Preview a CRF:

    Create CRF - Preview

  8. After previewing the defined CRF and completing any changes, click Continue.

    The Create a New CRF – Data Committed Successfully page opens.

    Create New CRF Version - Data Committed Successfully

  9. Review the defined CRF:
    1. Click Go back to the CRF List.
      The Manage CRFs page opens.
    2. For the CRF you want to review, click the View icon in the Actions column for the version you defined (do not click the View icon in the row that is marked “original” version).
    3. Review each section of the defined CRF (click the tab for a section to show it), viewing drop-down lists, checking wording and arrangement of Items, and so on. Make notes of anything you want to change. If you need to make changes to the name or description, see Edit a Defined CRF. If you want to, you can instead, Replace the Defined CRF.

After completing all changes to a defined CRF, assign the CRF to an Event Definition for any of your Studies.

3.4.8 Table of CRFs

The table of CRFs lists all versions of all defined CRFs in your OpenClinica system and provides access to features for managing the defined CRFs. The available features in the table depend on your User Role and User Type. To access the table of CRFs:

  1. From the Tasks menu, in the Study Setup module, select Build Study.
    The Build Study page opens.
  2. For the Create CRF task, click the View icon.
    The Manage Case Report Forms page opens.

    Manage CRFs table, Study Setup

The CRFs table is the same table you can access from the Monitor and Manage Data module. In addition to using this table to create, modify, and remove defined CRFs as described in other topics on this page, you can use this table to:

3.4.9 Edit the Defined CRF Name and Description

After adding a defined CRF to OpenClinica, you can change the Name and Description shown in OpenClinica for that CRF:

  1. Access the Table of CRFs.
  2. For the CRF whose Name and/or Description you want to change, click the Edit icon in the Actions column.
    The Update CRF Details page opens.

    Update CRF Details

  3. Change the Name and Description, then click Confirm.
    The Confirm CRF Details page opens.

    Confirm CRF Details

  4. Click Submit.
    The Table of CRFs page opens and shows the updated name for the CRF.

3.4.10 Create a New Version of a Defined CRF

You can make changes to a defined CRF that is already in your OpenClinica system.

Start by downloading the existing defined CRF from OpenClinica: see Download an Existing Defined CRF in Create a CRF. Then make changes to defined CRF using Excel: see Providing Content for a Defined CRF. Finally, upload the new version to OpenClinica. When you upload it, you can either:

3.4.10.1 Replace a Defined CRF

You can replace an existing version of a defined CRF under the following conditions:

  • You must be the CRF’s Owner, as listed in the Table of CRFs. The Owner is the user who uploaded the CRF you are replacing.
  • The CRF cannot be assigned to any Event Definitions in any Studies.
  • The values for CRF_NAME and VERSION for the CRF already in OpenClinica and the CRF you are replacing it with must match exactly.

If these conditions are not met, OpenClinica prevents you from replacing the CRF, but you can instead Add it as a New Version of the CRF.

To replace a CRF:

  1. Access the Table of CRFs.

    Table of CRFs - Before CRF Replacement

  2. For the CRF you are replacing, click the Create New Version icon CRF - Create New Version Icon.
    The Create a CRF Version for … page opens. In the example shown here, the CRF being replaced is Initial Treatment.

    Create New CRF Version

  3. Click Browse, then navigate to the CRF you want to upload. Select the file and click Open.
  4. Click Preview CRF Version.
    The Create a New CRF Version – Confirm Delete Previous Same Version page opens.
    In the example, the v1.0 version of the Initial Treatment CRF is being replaced: the CRF you are uploading has the value v1.0 for VERSION, and Initial Treatment for CRF_NAME.

    Create New CRF Version - Confirm Deletion of Previous Same Version

  5. Click Yes, Remove Previous Version.
    The Check CRF Version Data page opens, presenting a preview of the CRF in the OpenClinica web interface.
  6. Correct any errors as described in Upload a Defined CRF (step 6).
  7. After previewing the CRF and completing any changes, click Continue.
    The Create a New CRF Version – Data Committed Successfully page opens.
  8. Click Go back to the CRF List.
    The Manage CRFs page opens.
    • There will be a new value for Date Updated if you the version you replaced was last uploaded on a previous date.
    • There is a new Version_OID for the CRF you replaced. This is not the same as the value you specified for VERSION for the CRF, but is an internal identifier that OpenClinica uses to manage CRF versions.

    Table of CRFs - After CRF Replacement

3.4.10.2 Add a New Version of a Defined CRF

For background information, see About CRF Versions.

You can add a new version of a CRF to OpenClinica under the following conditions:

  • The CRF_NAME in the new version of the defined CRF must match the CRF Name already in OpenClinica, but the value for VERSION must be different.
  • For each ITEM_NAME, the DESCRIPTION, GROUP LABEL, and DATA_TYPE must exactly match the DESCRIPTION, GROUP LABEL, and DATA_TYPE already in OpenClinica. Changes to response sets are limited.

For more information, see CRF Versioning in the OpenClinica Technical Documentation.

When you add a new version of a CRF, the version already in OpenClinica remains. If you want to, you can remove the previous version from OpenClinica after adding the new version, or you can keep the previous version if you want users to be able to complete either versions going forward.

To add a new version:

  1. Access the Table of CRFs.

    Table of CRFs - Before Adding CRF

  2. For the CRF to which you are adding a new version, click the Create New Version icon CRF - Create New Version Icon.
    The Create a CRF Version for … page opens. In the example shown here, a new version (Espanol) is being added for the Last Treatment CRF.

    CRF - Create New Version, Adding a Version

  3. Click Browse, then navigate to the CRF you want to upload. Select the file and click Open.
  4. Click Preview CRF Version.
    The Check CRF Version Data page opens, presenting a preview of the defined CRF in the OpenClinica web interface.
  5. Correct any errors as described in Upload a Defined CRF (step 6).
  6. After previewing the CRF and making changes, click Continue.
    The Create a New CRF Version – Data Committed Successfully page opens.
  7. Click Go back to the CRF List.
    The Manage CRFs page opens. The version of the CRF you added is listed in the table.

    Table of CRFs - After Adding CRF

Now, when a user enters Event Data for a Subject, they can choose which version of the defined CRF to use. For the example, Last Treatment, the user can choose the English or Espanol version.

Enter CRF Data - Choose Version

3.4.11 Remove, Restore, and Delete Defined CRFs

If your User Type has appropriate permission, you can perform the following actions on defined CRFs or versions you no longer want to use:

  • Delete a version of a CRF if it has not been used for data entry for any Subjects and you no longer want the CRF in your OpenClinica system for potential use in any Studies. You cannot recover the CRF after its been deleted.
  • Remove a version of the CRF if it has been used for data entry for Subjects, to prevent its use going forward. Data captured using this version of the CRF is not included in data extracts whose definition specifies that CRF. You can restore a version of the CRF that’s been removed.
  • Restore a version of the CRF that has previously been removed, which allows it to again be used for data entry for Subjects.
  • Remove the “original” (parent) CRF to prevent any versions of that CRF to be used going forward, and to prevent the CRF from being assigned to any more Event Definitions. You can restore the parent CRF, and all versions, after it has been removed. Data captured using any versions of the CRF is not included in data extracts whose definition specifies that CRF.
  • Restore an “original” CRF that has previously been removed, which allows any versions of that CRF to be used going forward, and allows the CRF to be assigned to Event Definitions.
  • Archive a version of the CRF to prevent it from being added to any more Event Definitions. Data previously captured using that version of the CRF is included in data extracts whose definition specifies that CRF. Instructions to archive a CRF are in Administer CRFs.

Delete a CRF Version

Delete a version of a defined CRF if it has not been used for data entry for any Subjects. A deleted version of a CRF cannot be restored. To delete a version of a CRF:

  1. Access the Table of CRFs.

    Table of CRFs - After Adding CRF

  2. For the version of the CRF you want to delete, click the Delete icon Delete Icon. For the example, the Espanol version of the Last Treatment CRF is being deleted.
    The Confirm Deletion of CRF Version page opens.

    Delete CRF Version

  3. Click Delete CRF Version, then click OK in the confirmation dialog box.
    The Manage CRFs page opens. The version of the CRF you deleted no longer appears in the table.

    Table of CRFs - After Deleting CRF Version

If you try to delete a version of a CRF that has already been used to enter Subject data, OpenClinica prevents you and displays the following:

Delete CRF Version - Prevented

Remove a CRF Version

If a version of a defined CRF has been used for data entry for Subjects, you can prevent its use going forward by removing it. A version of a CRF that has been removed can be restored. To remove a version of the CRF:

  1. Access the Table of CRFs.
  2. For the version of the CRF you want to remove, click the Remove icon Remove Icon. For the example shown here, the Last Treatment CRF, English version, is being removed.
    The Confirm Removal of CRF Version page opens. It lists the Event CRFs and Subjects who have had data entered using that version of the CRF.

    Remove CRF Version

  3. Click Remove CRF Version, and then click OK in the confirmation dialog box.
    The Manage CRFs page opens. The version of the CRF you removed is listed, but with a Restore icon Restore Icon instead of a Remove icon in the Actions column and a Status of “removed”.

    Table of CRFs - After Removing CRF

After removing the version of the CRF, you can still view the CRF and can still view Subject data for that version of the CRF, as shown below, however you cannot change any of the data. The status of the CRF for the Subject is “locked”:

Subject Record After CRF Removed

After removing a version of the CRF, it is no longer available for you to choose from when you enter data for any other Subjects for that CRF.

Restore a CRF Version

After removing a version of a defined CRF, you can restore it to make it available for use for entering Subject data. To restore a version of the CRF:

  1. Access the Table of CRFs.
  2. For the version of the CRF you want to restore, click the Restore icon Restore Icon. For the example shown here, the Last Treatment CRF, English version, is being restored.
    The Confirm Restore of CRF Version page opens. It lists the Event CRFs and Subjects who have had data entered using that version of the CRF.

    Restore CRF Version

  3. Click Restore CRF Version, then click OK in the confirmation dialog box.
    The Manage CRFs page opens. The CRF you restored is listed with a status of “available.”

    CRF Table - After Restoring CRF Version

Remove the Original Version of a CRF

You can remove the original (parent) version of a defined CRF, which automatically removes all versions of the CRF. To remove the original version of a CRF:

  1. Access the Table of CRFs.
  2. For the CRF you want to remove, click the Remove icon Remove Icon in the row for the version “original”. For the example shown, the Last Treatment CRF is being removed.
    The Confirm Removal of CRF page opens. It lists all versions of that CRF and all Event Definitions to which the CRF has been assigned.

    Remove CRF File

  3. Click Remove CRF, then click OK in the confirmation dialog box.
    The Manage CRFs page opens. The CRF you removed is listed, but with a Restore icon Restore Icon instead of a Remove icon in the Actions column and a Status of “removed.” All versions of the CRF are listed, but with a status of “auto-removed.”

    Table of CRFs - After Removing CRF

After removing the original version of a defined CRF, any Event Definitions to which the CRF was assigned list the CRF, but show the status as auto-removed. When you are adding CRFs to Event Definitions, the removed CRF is not listed for you to choose from.

Note: you cannot delete the original version of a defined CRF.

Restore the Original Version of a CRF

After removing the original version of a CRF, you can restore it. Restoring the original CRF restores all versions of it to all Event Definitions in all Studies to which the CRF was assigned. To restore the original version of a CRF:

  1. Access the Table of CRFs.
  2. For the CRF you want to restore, click the Restore icon Restore Icon in the row for the version “original.” For the example shown, the Last Treatment CRF is being restored.
    The Confirm Restore of CRF page opens. It lists CRF versions for that CRF and all Event Definitions to which the CRF has been assigned.

    Restore CRF File

  3. Click Restore CRF, then click OK in the confirmation dialog box.
    The Manage CRFs page opens. It lists the CRF you restored and all versions of it with a status of “available.”

    Table of CRFs - After Restoring CRF