Custom Participant Properties may include any information users know or want to capture regarding Participants that is not already captured by the Built-In Participant Properties.
Participant List Property Limits
- A Master Participant List can have a total of 250 properties per list. These properties can be of any Data Type.
- A Derived list has the same requirements but can also inherit all of the Master Participants Custom Properties. Thus if the master list has 250 properties, these 250 properties can be inherited to the derived list, and an additional 250 custom properties can be created on the derived list, for a total of 500 properties.
Adding a Custom Participant Property
- Must be logged in as a User with the Administrator and/or Study Administrator Role for the Study/Project or System
- Click on the Enterprise Manager Link in the upper right corner of the Discovery interface if you haven’t been taken directly there at login.
- Expand the Project where the study is located
- Click on the Participant Lists link
- Click on the Edit Participant List Columns Icon
- Select the Custom Participant Property tab
- Click Take Action/Add Participant List Column
- Enter the appropriate information and Click Save.
Participant Property Fields/Attributes
The Property Fields are the same for both Standard and Custom Participant Properties.
NOTE: * denotes a required field
Name* – The Name of the Participant Property
The requirements for naming Participant List Columns are similar to those for naming Surveys and Variables.
The following is a list of the requirements:
- 2-128 characters in length
- Starts with a capital A-Z or 0 – 9
- Following characters can be A-Z, 0-9, underscore (_), hyphen (-), or period (.)
- Cannot use DATSTAT as this is reserved for Standard Properties
Data Type* – Defines the way the data is stored
Possible Data Types:
- Date – A valid calendar date, including day, month, and year. E.g. 12/11/2005. Dates that don’t exist, like 02/30/2004, are not valid
- Date/Time – A valid date and time, including year, month, day, hour, minute, and second. E.g. 12/11/2005 12:51;17 pm
- Decimal – Numbers with both whole and fractional component. E.g., 3.14, -299.173 – The precision can be up to 28 places.
- Float – A float is a decimal number in which you can put the decimal anywhere in the number. This is distinct from “decimal” in that a decimal requires that you specify a precision and scale. The scale is the total number of digits including decimals places; the precision is the number of places right of the decimal. Decimals allow more specific and precise values, while floats are approximate values.
- Integer – Numbers without a decimal component. E.g., 21, 55000, -211
- Text
- Time – A valid time, including hour, minute and second. E.g. 12:51:17 pm
- True/False – A simple 0 or 1 value. 0 traditionally represents No or False, while 1 represents Yes or True. Illume allows you to reverse the traditional meanings if you wish. All checkbox items are of this data type, since a checkbox can have only two states (checked or not checked).
Label* – Text the User sees when Adding/Editing a Participant, and in Data Grids once a participant is uploaded
Display Type* – The Control that is output when Adding/Editing a Participant
The options are Pop-List, Radio Button, Text Box, , Check Box, Commentary, and Hidden.
Only when the options Drop-Down and Radio Button are selected will the Scale tab become enabled.
Property Group* – The Group Name of the Fields. Specifying a Property Group allows Users the ability to group Properties together, making them easier to find. In addition, when viewing a Participant, Property Groups are presented in alphabetical order, so putting critical properties in an “early” Property Group ensures they will be presented at the top of the screen. DatStat recommends using numbers as a prefix for group names so that the order of your groups is organized the way you prefer, for example 01: Patient Contact Information 02: Patient Study Progress, etc)
NOTE: Property Group names are Case Sensitive – They must be typed exactly the same for each Property in that Group or there will be a separate group created (i.e. “Consent Variables” is not the same as “Consent variables”).
Order in Group* – Within a Property Group, this is the order in which a particular Participant Property will be presented.
NOTE: Order is not enforced but is respected. In other words, if you have three properties in the same group marked as “Order in Group=1”, an error will not be presented. Rather, Discovery will present those properties in random order as the first three properties.
Parent Column – Used to identify the Parent for a Dependent Property
Error Message – Error Message that will display if the property is entered incorrectly when Adding/Editing a Participant. For example, if integer data type is specified for a property and non-integer data are entered when editing a participant, this error message will appear and will prevent the User from saving that participant until the data are changed.
Default Value – If the property uses a scale, you may define that the property defaults to a particular scale value. The Default Value must match one of the scale values if they are defined
Description – A text description of the Participant Property
Required? – Check box to make this a required property. Required means that all participants must have a value for this property from the moment they are uploaded.
Disabled? – Check box to remove it from view during Adding/Editing a Participant
Allow Bulk Update? – Check box to allow a User with sufficient Privileges to use the Bulk Update Action for this Property value.
Unique? – Check box which will require that the Property value is unique across all Participants in the Study. It will prevent duplicate entries by presenting an error message. This is typically used for ID and Email Address fields.
Indexed? – Check box which creates a database index on this Property field to increase speed of search/query.
NOTE: If Indexing is used too frequently it will decrease over-all performance of the system.
Data Validation – Specifies Formats and Bounds for the Property to ensure the data are correctly inputted.
- Max. Length – Maximum Number of digits for an integer
- Min. Value – Minimum Number of digits for an integer
- Decimal Precision
- Validation Pattern (Regular Expression)
- Max. Value
- Decimal Scale
Scale Tab
The Custom Participant Properties can be given scale values by Clicking on the Add New Scale Value link in the Scale Tab. The Data Type must be Integer and it has to be a drop-down/poplist – you can enter numeric or text as the value/code
Code – Scale Value for that possible response
If a Numeric data type is chosen then it will be Numeric
If a Text data type is chosen it can be textual
Label – Visible Text associated with Code
NOTE: Scale Values must match the defined Data Type. e.g. Use 1,2,3 if Integer was selected
After the first code and label has been added, click “Add New Scale Value” to add another. Continue this process until all have been created.
User Access Exclusions
Participant Properties can have Exclusions set to give Full, Read Only or Hidden access to Users or User Groups. By default, all users have read/write access to all properties. Thus, exclusions can be set for a user or user group to make a property read only, or entirely hidden. This is set property by property – it is not possible to set exclusions in bulk.
A Participant Property may have multiple Exclusions applied. See the Section on User Access Exclusions for more details
A Note on Date and Time Data:
DatStat Discovery uses Microsoft’s .NET DateTime object to store dates and times. The .NET DateTime object can represent dates between 12:00 a.m. January 1, 0001 CE and 11:59:59 p.m. on December 31, 9999. Illume considers dates outside of this range to be invalid. Non-existent dates are also invalid. For example, February 29, 2005 is invalid because 2005 is not a leap year. Participant must enter dates or times in a format that .NET recognizes. In general, for the United States locale, dates in the following formats are valid:
- mm/dd/yyyy This is a 2-digit month, followed by a slash, followed by a 2-digit day, followed by a 4-digit year. E.g., 09/16/2006
- Monthname Day, Year E.g. January 25, 2005
Other date formats will also work in the US. You should, however, suggest a format that you know will work in either your question prompt or in the question label. For example, a prompt that suggests a valid format would be: Please enter your date of birth (mm/dd/yyyy): Illume and .NET recognize both 12- and 24-hour time formats, though Discovery may ignore the seconds. The following time formats are valid in the US locale:
- hh:mm This is a 24-hour time format. E.g. 23:15
- hh:mm am/pm This is a 12-hour time format. E.g. 11:15 pm
.NET uses the same standard set of date and time formats that other Microsoft products use. This means that any Date, Time, or Date/Time format produced by an application like Microsoft Excel, Access, or SQL Server will work in Illume. Use the Date data type only for variables that must include a day, month, and year. If your variable requires only one of these values (day or month or year), choose the whole number or text data type. Choose Date/Time data type only for variables that require a day, month, and year value with an optional time value.
Dates, Times, and Localization
Discovery and .NET use the locale settings of the Illume server to determine dates and times. This can cause some confusion if a survey is not designed correctly. For example, if you are administering a survey to participants in both the US and the UK, you should be aware that the two locales use different date formats. A US participant entering 06/12/2006 will mean June 12, 2006, while a British participant entering the same thing will mean December 12, 2006. If the survey is running on a server whose locale is set to EN-US (English, United States), the date will always be interpreted as June 12. If the server’s locale is set to EN-GB (English, Great Britain), the date will always be interpreted as December 6. This will be a problem if your question includes a minimum and/or maximum date. The British User or the US User may not be able to get past the date question simply because the participant and the server do not agree on what the date means. One way to avoid date/time problems caused by local differences is to break dates and times into separate questions, each of which is of type whole number. For example, instead of asking for a participant’s birth date, ask for his or her year of birth, then month of birth, then day of birth.
Adding a Participant Property after initial list creation
When testing or running a study, Users may realize that a Participant Property is needed that was not already created.
Users must first determine is if this Property should be created at the Master or Derived list level. If the Master list feeds into multiple derived lists OR information is being captured on participants at the master list level, not within the Discovery Study interface then add to a Master. If the Property is only relevant to the specific study to which the participants are enrolled, then the Property should be created at the Derived list level.
Master Level Properties used in a Derived List
- Log in as a User with the Study Administrator Role for the Study/Project or System in Discovery/Illume
- In the Enterprise Manager screen expand the appropriate Project
- Select the Participant Lists icon
- Select the Edit Participant List Columns icon from the appropriate row of Participant Lists
- Follow the steps above to add the property.
- If the Master List is used in the Study you are finished
- If there is a Derived list then continue
- Click on the Edit Participant List icon
- Check the Added Property in the Inherited Participant List Columns section
- Click Save and OK
Derived List Properties not used in Master List
- Log in as a User with the Study Administrator Role for the Study/Project or System in Discovery/Illume
- In the Enterprise Manager screen expand the appropriate Project
- Select the Participant Lists icon
- Select the Edit Participant List Columns icon from the appropriate row of Participant Lists
- Follow the steps above to add the property.
- Click Save and OK