3.4.2.5 CRF Template Elements

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.

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.

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.

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

A CRF must have at least one Section.

Long Section Titles may not display well.

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

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.

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.

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.

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.

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.

Used only when the GROUP_LAYOUT is equal to GRID. 

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.

Specifies the default initial number of repeats to be displayed on the form. If left blank, only one row will be displayed 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.

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.

If left blank, the Group defaults to SHOW. 

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.

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.

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.

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

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.

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

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

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.

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.

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.

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

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

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.

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.

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.

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.  

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.

Has no effect in Participate.

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

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.

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

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)

Has no effect in Participate.

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.

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.

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.

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.

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.

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.