3 CRF Template Elements

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


OpenClinica CRF Spreadsheet Field

Description

Can vary by CRF Version

Restrictions

When to use

CRF Worksheet

 

 

 

 

CRF_NAME

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

No

Required

Alpha-numeric characters are allowed

255 characters max

UNIQUIE

If the field is blank, the CRF will be rejected at upload time.

VERSION

Defines the version of the CRF as it will be displayed in the OpenClinica user interface. You can not provide a value that has already been used in the OpenClinica instance unless it has not been assigned to an event definition yet.  If a particular CRF version has not been used in an event definition, you may overwrite it.

Yes

Required

Alpha-numeric characters are allowed

255 characters max

UNIQUE

If this is a new version of a CRF that already exists, the CRF_NAME field must match the value of the form already 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.

VERSION_DESCRIPTION

This field is used for informational purposes to keep track of what this version of the CRF was created for.

Yes

Required

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

REVISION_NOTES

This field is used to keep track of the revisions you made to this particular CRF. 

Yes

Required

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

 

 

 

 

 

Sections Worksheet

 

 

 

 

SECTION_LABEL

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)

Required

Alpha-numeric

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.

SECTION_TITLE

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’

Yes

Required

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

SUBTITLE

A sub-title shown under the section title. 

Yes

All characters allowed

2000 characters max

HTML elements are supported for this field.

INSTRUCTIONS

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

Yes

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

PAGE_NUMBER

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.

Yes

All characters allowed

5 characters max

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.

PARENT_SECTION

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

 

255 characters max

Must equal a valid SECTION_TITLE

This field does not have any affect in the User Interface. It does not affect data being exported. This will be deprecated after version 3.1.3.

         

 

 

 

 

 

Groups Worksheet

 

 

 

 

GROUP_LABEL

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

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.  The entire GROUPS worksheet can be left blank if desired and all the items in the CRF can be part of a single group called UNGROUPED.

 

We suggest to provide records in this worksheet only if you are going to use Groups for Items grouping on Items worksheet.

 

GROUP_LAYOUT

Defines the type of item group (GRID or NON-REPEATING, Blank). A layout of GRID means the items defined as part of the item group can be dynamically repeated during the data entry process, and will be displayed in a horizontal grid where each item is represented as a column and users can add rows of data to the table during data entry.

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 (dynamic) show and hide logic.

 

If left blank the item group will be treated as if it is set to NON-REPEATING. 

Yes

Blank, GRID, NON-REPEATING

This field should be used to define the item groups as repeating (GRID) or non-repeating.

Non-repeating item groups can include items from across multiple sections of the CRF. Items that are members of a repeating (GRID) item group 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.

GROUP_HEADER

The value is displayed above the GRID when a user is performing data entry.

 

Used only when the GROUP_LAYOUT is equal to GRID. 

Yes

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

GROUP_REPEAT_NUMBER

The default (initial) number of repeats on the form should be provided here. If left blank, only one row of information will be displayed by default.

 

Used only when the GROUP_LAYOUT is equal to GRID. 

Yes

Integer

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 will be 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.

 

If the Layout is set to NON-REPEATING, the value will be ignored and not displayed during data entry.

GROUP_REPEAT_MAX

The total number of rows a user will be allowed to repeat in the item group.  When left blank, the default number of repeats is 40.

 

Used only when the GROUP_LAYOUT is equal to GRID. 

Yes

Integer

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 group will have GROUP_REPEAT_MAX number of rows on initial data entry displayed and no additional rows can be added.

GROUP_DISPLAY_STATUS

Used in conjunction with Dynamics in 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 with a Rule and using the ShowAction.

 

If left blank, the value defaults to SHOW. 

Yes

Blank, SHOW, HIDE

If you would like to design skip patterns and dynamic logic for the item groups, set the display status to HIDE.  When the form is accessed for data entry, the group of items will be hidden from view from the user.  With Rules, entry of a desired value elsewhere in data entry can trigger the item group  to then be shown instead of hidden (this applies to GRID and NON-REPEATING). The opposite is true as well.  Groups that are set to HIDE which have been shown as a result of a rule can also be hidden based on certain criteria being met.


Note that the GROUP is the container for items and that items within the group can have nested SHOW/HIDE logic as well. If a hidden group is shown but some of the items within that group have been set to HIDE within the ITEMS worksheet, additional logic will have to be built for those individual items. If all items within the group are set to SHOW within the items worksheet, then showing the time group will show all items.

 

 

 

 

 

Items Worksheet

 

 

 

 

ITEM_NAME

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

No (added or removed only)

Required

Only ASCII characters from "a" to "z", "A", to "Z", "0" to "9", and "_" are supported. No spaces.

255 characters max

Must be UNIQUE within the CRF version

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.

DESCRIPTION_LABEL

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

No

Required

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 is 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 can not be changed in any subsequent versions of the CRF. If you do change it, it will be ignored on upload and the DESCRIPTION_LABEL provided with the first version of the CRF will be used.

LEFT_ITEM_TEXT

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

Yes

All 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 subject’s height?”  Or, a simple one word “Height” suffices as well.

If the item is part of a repeating group (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 limited subsets of tags are officially supported (bold <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 Objects. 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}

    $ {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

UNITS

Used to define the type of values being collected.  It appears to the right of the input field on the CRF.

No

64 characters max

If you are collecting data in Inches, this field can specify your units as Inches, IN, or in. 

This field can not be changed in any subsequent versions of the CRF. If you do change it, it will be ignored on upload and the UNITS provided with the first version of the CRF will be used.

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_TEXT

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

Yes

All characters allowed 2000 characters max

This field can be 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 repeating group (GRID), the RIGHT_ITEM_TEXT will be ignored and never displayed.

HTML elements are allowed; however, only limited subsets of tags are officially supported (bold <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 Objects. 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}

    $ {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_LABEL

Logically organizes the items that should be together on a section.  The items in a given section are displayed on a single web page when the user is entering data, and appear in the order they are entered in the Template.

 

Every item in the worksheet must be assigned to a section of the CRF.

Yes

Required

Value must exist on the Sections Worksheet

For example, all of the information collected as part of a physical exam like Height, Weight, Blood Pressure, and Heart Rate should be on the same section.

GROUP_LABEL

Assigns items to an item group.  If the group is repeating, 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.  Repeating items are displayed on a single row with the LEFT_ITEM_TEXT (if any exists) as a column header.

Yes

Value must exist on the Groups Worksheet

This field 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. 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,  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 affected CRF. A new table 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.

HEADER

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

Yes

All characters allowed

2000 characters max

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 person’s attention.

HTML elements are allowed; however, only limited subsets of tags are officially supported (bold <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 Objects. 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}

    $ {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

SUBHEADER

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

Yes

All characters allowed

240 characters max

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 user’s attention.

HTML elements are allowed; however, only limited subsets of tags are officially supported (bold <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 Objects. 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}

    $ {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

PARENT_ITEM

This field can contain an ITEM_NAME that immediately precedes this item, and is in the same section.  This will cause the child item to be indented underneath the ITEM_NAME specified

Yes?

Value for ITEM_NAME must already exist in the CRF and immediately precede the current ITEM

Only one level of indention is allowed

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.

COLUMN_NUMBER

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.

Yes

Integer

This is to be used with only non-repeating items and controls 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, it will just be applied to the first column.

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

PAGE_NUMBER

Page number where the item would appear. If using paper source documents and have a multi-page CRF, put in the printed page number.

Yes

Alpha-numeric

5 characters max

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.

QUESTION_NUMBER

This field is used to specify an identifier for each item or question in the Items worksheet.  It appears to the left of the LEFT_ITEM_TEXT field, or if that field was left blank, to the left of the form input.

Yes

Alpha-numeric

20 characters max

This field allows you to specify questions as 1, 2, 2a etc. in a field. 

RESPONSE_TYPE

The types of responses are based on standard HTML elements web browsers can display in a form. Allowed use of the available RESPONSE_TYPEs depends on the item DATA_TYPE and use of Response Sets. 

Yes

Required

Option must be selected from the drop down box:

-text

-textarea

-single-select

-radio

-multi-select

-checkbox

-calculation

-group-calculation

-file

-instant-calculation (OpenClinica 3.1.3 and up)

Text is a rectangular box to enter information.  Textarea is a larger box where more information is visible to the person viewing the form with data.

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

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

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 can not be directly edited by the data entry person and will appear “grayed out”.  Group-calculation allows the user to find a value based off of the column in 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.

File allows a file to be uploaded and attached to the CRF by the data entry person. 

Instant-calculation (introduced in 3.1.3) is used to populate a destination field with date/time information when content of a parent field is changed. The trigger field must precede the intstant-calculation field.  This is a client side action; it is executed by triggering onchange function defined by the CRF designer in the RESPONSE_VALUES_OR CALCULATIONS field in the CRF template. The onchange function takes arguments of item name (parent item) and value. The item name indicates the name of parent field. The value indicates what date format should 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 repeating group only if its trigger field is on the same row of a repeating group. The trigger field for an instant-calculation field can be of any response type.

RESPONSE_LABEL

Create 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 (eg Yes, No) and values.

No

Required

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

RESPONSE_OPTIONS_TEXT

A 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 /

RESPONSE_VALUES_OR_CALCULATIONS

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

Items with a RESPONSE_TYPE of "calculation" support arithmetic operators to populate the field with a derived value upon CRF save. ITEM_NAMEs of other INT or REAL items in the same CRF can be used as variables to compute the derived value. For example, the calculation for a line item total price in an invoice would be "func: (ITEM_PRICE * QTY)". The following functions are also allowed in the calculation expression: sum(), avg(), min(), max(), median(), stdev(), pow(), and decode().

Cumulative calculations on a group of repeating items must be of RESPONSE_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))”.

Cumulative calculations using the group-calculation input type cannot be in the same group with fields of a calculation input type. Also a group calculation field cannot use a calculation field as an input to its calculation.

 

RESPONSE_LAYOUT

The layout of the options for radio and checkbox fields.  The options can be left to right, or top to bottom depending on the value specified in the Items worksheet

Yes

Blank, Horizontal, Vertical

Leaving the field blank and selecting Vertical display the items in a single column from top to bottom.  Choosing Horizontal will put the items in a single row, left to right.

DEFAULT_VALUE

Default text for RESPONSE_OPTIONS_TEXT  

Yes

4000 characters max

 

This field allows the user to specify a default value that will appear in the CRF section the first time the user accesses the form.  For single-select default value does not have to be part of the response set and can be instructive text if need be.  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-SELCT
  • MULTI-SELECT
  • CHECKBOX

Default values can not be used for the following RESPONSE_TYPEs (CRF will be rejected on upload):

 

  • CALCULATION
  • GROUP_CALCULATION
  • FILE
  • INSTANT_CALCULATION
  • RADIO

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.  

DATA_TYPE

The data type is the format the value should be supplied in.

No

Required

Option must be selected from the drop down box:

-ST

-INT

-REAL

-DATE

-PDATE

-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 are allowed for this data type.

 

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.

 

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.

WIDTH_DECIMAL

Specify the width (the length of the field) and the number of decimal places to use for the field

Yes

Not required.

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

w – integer from 1 to 32, or literal ‘w’ if INT or REAL.  If ST, from 1 to 255 is allowed.

d – literal ‘d’. if the item has DATA_TYPE of ‘REAL’, may also be an integer from 1 to 20.

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 evalution 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 OpenClinica’s maximum length for an item of ST, INT, or REAL (32 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 ahydrocephalusdecimal 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.

VALIDATION

Specify a validation expression to run an edit check on this item at the point of data entry.

Yes

1000 characters max

The 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_MESSAGE

Defines an error message provided to on the data entry screen when a user enters data that does not meet the VALIDATION.

Yes

255 characters max

Required if VALIDATION is provided

Must be used when a VALIDATION is specified and it should be clear to the data entry person what the problem is.  If there is a VALIDATION stating the number must be between 1-10, write that message in this field for the user to see if they enter 11 or 0.

PHI

Signifies whether this item would be considered Protected Health Information

No

Blank, 1, 0

Leaving the field blank or selecting 0 mean 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 more as a label.

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.

REQUIRED

This field determines whether the user must provide a value for it before saving the section the item appears in.

Yes

Blank, 1, 0

Leaving the field blank or selecting 0 mean the item would be optional so the data entry person does not have to provide a value for it.  If 1 is selected, the data entry person must provide a value, or enter a discrepancy note explaining why the field is left blank.  This can be used for any RESPONSE_TYPE

ITEM_DISPLAY_STATUS

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

Yes

Blank, SHOW, HIDE

If 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 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 use the SIMPLE_CONDITIONAL_DISPLAY field to decide when this item should be shown.  SIMPLE_CONDITIONAL_DISPLAY only works with items set to HIDE.

SIMPLE_CONDITIONAL_DISPLAY

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.

 

Yes

Comma separated list

Simple 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. Many levels of hierarchy are supported. Several levels of hierarchy of Simple Conditional fields work similar to a single parent-child simple conditional relationship.

SIMPLE_CONDITIONAL_DISPLAY (SCD) has an effect only when ITEM_DISPLAY_STATUS (IDS) of the item is set to HIDE.

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.

However, radio button control cannot be deselected (meaning there is no way to delete it’s value once it was selected).

 


Approved for publication by Benjamin Baumann (bbaumann), Principal. Signed on 2014-06-12 4:57PM

Not valid unless obtained from the OpenClinica document management system on the day of use.