Field Properties Editor

• Use the arrows and X's to the left of each field to reorder or delete fields.
• Click on the Name, Label or Type for any field to edit them.
• Selecting a row brings up the field properties editor: the block of tabs to the right.
• The highlight bar indicates which field is currently selected for editing.
• A wrench icon on the left will indicate a row with unsaved changes.

• Basic Properties
• Display Properties
• Format Properties
• Validators (Field-level Validation)
• Reporting Properties
• Advanced Properties

Basic Properties

Name: This is the name used to refer to the field programmatically. It must start with a character and include only characters and numbers.

Label (Optional): The name that users will see displayed for the field. It can be longer and more descriptive than the name and may contain spaces.

Type: Fields come in different types, each intended to hold a different kind of data. Once defined, the field type cannot be changed, since the data in the field may not be able to be converted to the new type. To change the field type, you may need to delete and recreate the field. This will delete any data in the field, so re-importing the data will be necessary. The field types are:

• Text (String)
• Multi-Line Text
• Boolean (True/False)
• Integer
• Number (Double) - A decimal number.
• Date/Time
• Flag (String)
• File - The File type is only available for certain types of table types, including assay designs and sample sets, see below for a complete list. When a file has been uploaded into this field, it displays a link to the file; for image files, an inline thumbnail is shown. The uploaded file is stored in the file repository, in the assaydata folder.
• Attachment - This type is only available for lists, see below for a complete list. This type allows you to attach documents to individual records in a list. For instance, an image file could be associated with a given row of data in an attachment field, and would show an inline thumbnail. The attached file is not uploaded into the file repository. Maximum file size is 50MB.
• User - This type points to registered users of the LabKey Server system, found in the table core.Users.
• Subject/Participant (String) - This type is only available in a study.
• Lookup - See below.

Field Types Available by Data Structure

The following table show which fields are available in which sort of table/data structure. Notice that Datasets do not support File or Attachment fields. For a workaround technique, see Linking Data Records with External Files.

Inline Thumbnails for Files and Attachments

Fields of type File and Attachment are available in certain schema including lists, sample sets, and assay run results. When the file or attachment is an image, such as a .png or .jpg file, the cell in the data grid will display a thumbnail of the image. Hovering reveals a larger version.

When you export a grid containing these inline images to Excel, the thumbnails remain associated with the cell itself.

Lookup

You can populate a field with data via lookup into another table. Click on the Type property for a field, select the Lookup option, then select a source Folder, Schema and Table from the drop-down menus in the popup. These selections identify the source location for the data values that will populate this field. For examples, see the List Tutorial and the Advanced List Demo.

A lookup appears as a foreign key (<fk>) in the XML schema generated upon export of this study. An example of the XML generated:

<fk>
          <fkDbSchema>lists</fkDbSchema>
          <fkTable>Reagents</fkTable>
          <fkColumnName>Key</fkColumnName>
</fk>

Note that lookups into lists with auto-increment keys may not export/import properly because the rowIds in this type of list may be different in every database.

Display Properties

Display properties for a field are shown on the Display tab and control how and when the field is displayed.

Description: Verbose description of the field. XML schema name: description.

URL: A template for generating hyperlinks for this field. The ${ } syntax may be used to substitute a field's value into the URL. See URL Field Property.

Shown In Display Modes: Checkboxes allow you to choose whether or not the column is displayed in certain modes.

Format Properties

Format: You can create custom Date, DateTime or Number Formats for displaying values of these types. You can also configure date, datetime, and number formats at the folder, project, or site level for broader consistency. See Date & Number Display Formats.

Conditional Formats: Conditional formats let you change the way the data is displayed based on the data value. For details see Conditional Formats

Validators (Field-level Validation)

Field validators ensure that all values entered for a field obey a regular expression and/or fall within a specified range. They can automate checking for reasonableness and catch a broad range of field-level data-entry errors during the upload process.

Required: When required, a field cannot be empty. Defaults to "False."

Add Regex Validator: Define a regular expression that defines what strings are valid.

• Name: Required. A name for this expression.
• Description: Optional. A text description of the expression.
• Regular Expression: Required. A regular expression that this field's value will be evaluated against. All regular expressions must be compatible with Java regular expressions, as implemented in the Pattern class.
• Error message. Optional. The message that will be displayed to the user in the event that validation fails for this field.
• Fail when pattern matches. Optional. By default, validation will fail if the field value does not match the specified regular expression. Check this box if you want validation to fail when the pattern matches the field value, which may be an easier way to express the error cases you want to catch.

• Name: Required. A name for this range requirement.
• Description: Optional. A text description of the range requirement.
• First condition: Required. A condition to this validation rule that will be tested against the value for this field.
• Second condition: Optional. A condition to this validation rule that will be tested against the value for this field. Both the first and second conditions will be tested for this field.
• Error message: Required. The message that will be displayed to the user in the event that validation fails for this field.

For information on script-based validation, which can be used to validate rows or entire tables in a programmatic way, see Transformation Scripts.

Reporting Properties

The reporting tab allows you to set attributes used in creating reports. Select the field of interest in the properties editor, click the Reporting tab and select:

Measure: A field identified as a measure contains data useful for charting and other analysis. Measures are typically numeric results/observations, like weight, or CD4 count. Only those columns identified as measures will be listed as options for the y-axis of a time chart, for example.

Data Dimension: Data dimensions define logical groupings of measures. For example, 'Gender' could be a dimension for a dataset containing a 'Height' measure, since it may be desirable to study height by gender.

Recommended Variable: Define which fields in this table/query/etc. should be prioritized as 'recommended' variables when creating new charts/reports/etc for datasets containing large numbers of columns.

Default Scale Type: For numeric field types, defines whether linear or log scales will be used by default for this field.

Advanced Properties

Missing Value Indicators: A field marked with 'Missing Value Indicators', can hold special values to indicate data that has failed review or was originally missing. Defaults to "False." Data coming into the database via text files can contain the special symbols Q and N in any column where "Missing value indicators" is checked. “Q” indicates a QC has been applied to the field, “N” indicates the data will not be provided (even if it was officially required).

Default Type: Dataset schemas can automatically supply default values when a user is entering values or when imported data tables have missing values. The "Default Type" property sets how the default value for the field is determined. "Last entered" is the automatic choice for this property if you do not alter it. Note: This property is not included in XML schemas exported from a study.

Options:

• Editable default: An editable default value will be entered for the user. The default value will be the same for every user for every upload.
• Last entered: An editable default value will be entered for the user's first use of the form. During subsequent uploads, the user will see their last entered value.

Options:

• If you have chosen "Editable default," you can set the default value through the Set Values option. Each time the user sees the form, they will see this default value.
• If you have chosen "Last entered" for the default type, the field will show the setting entered previously, but you can still set the initial value of the field through the "Default Value" option.

In most places where data is imported from files (TSV, Excel, etc) LabKey Server tries to match file column headers to property names. In some cases it also looks for matching property labels. The "Import Aliases" option offers further flexibility by allowing an arbitrary number of alternate column aliases. At import time, LabKey uses these aliases to track down values.

Protected: Protected columns are those that contain protected or identifiable information about participants, such as internal participant IDs, transplant dates, birth dates, etc.

Exclude From Shifting: Participant date columns with this property checked will not be shifted on export/publication when the "Shift Participant Dates" option is selected.

Max Text Length: Specify the maximum number of characters allowed in text fields. The default value is 4000 characters. For values over 4000 characters, select Max. Selecting "Max" will utilize the max number of characters allowed by the underlying database implementation, for example, 1GB for PostgreSQL. Sample Sets and assay run fields do not support the Max setting. (Key fields and fields in the table exp.objectproperty do not support the Max setting.)

Related Topics

• Linking Data Records with External Files