This topic describes the interface for editing all fields and properties prior to release 19.3. Beginning with 19.3.0, some data structures, including assays, sample sets, and data classes, use a new interface. To learn about the new field editor, see this topic:
Each field in a list or dataset is associated with a set of properties that can be edited using the field property editor shown below. The set of fields composing a list or dataset can also be called a
domain, and this tool is sometimes called the domain editor.
Field Properties Editor
- Use the , , and buttons 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.
The interface for editing field properties looks like this:
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; it may not include spaces.
Label (Optional): The name that users will see displayed for the field. It can be longer than the name and may contain spaces.
Type: Fields come in different types, each intended to hold a different kind of data. Once defined, there are only limited ways you can change it, based on the ability to convert existing data to the new type.
To change a field type, you may need to delete and recreate it, reimporting any data. 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. For General Purpose assays, the File field presents special behavior for image files; for details see Linking Assays with Images and Other Files.
- 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, but is stored as a BLOB field the database. By default, the maximum file size is 50MB, but this can be changed in the Admin Console using the setting Maximum file size, in bytes, to allow in database BLOBs. See Site Settings.
- 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. The Subject/Participant ID is a concept URI, containing metadata about the field. It is used in assay and study folders to identify the subject ID field. Currently, there is no special built-in behavior associated with this type. It is treated as a string field.
- 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.
Field Type | Dataset | List | Sample Set | Assay Design |
---|
Text (String) | Yes | Yes | Yes | Yes |
Multi-Line Text | Yes | Yes | Yes | Yes |
Boolean | Yes | Yes | Yes | Yes |
Integer | Yes | Yes | Yes | Yes |
Number (Double) | Yes | Yes | Yes | Yes |
DateTime | Yes | Yes | Yes | Yes |
File | No (workaround) | No | Yes | Yes |
Attachment | No (workaround) | Yes | No | No |
User | Yes | Yes | Yes | Yes |
Subject/Participant(String) | Yes | Yes | Yes | Yes |
Lookup | Yes | Yes | Yes | Yes |
Inline Thumbnails for Files and Attachments
Fields of type
File and
Attachment are available in certain structures including lists, sample sets, and assay run results (see the table above for details). 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.
Bulk Import into the File Field Type
You can bulk import data into the File field type, provided that the files/images are already uploaded to the File Repository. For example suppose you already have a set of images in the file Repository, as shown below.
You can load these images into a File field, if you refer to the images by their full server path in the File Repository. For example, the following shows how an assay upload might refer to these images by their full server path:
ImageName | ImageFile |
---|
10001.png | http://localhost:8080/labkey/_webdav/Tutorials/List%20Tutorial/%40files/NIMH/Images/10001.png |
10002.png | http://localhost:8080/labkey/_webdav/Tutorials/List%20Tutorial/%40files/NIMH/Images/10002.png |
10003.png | http://localhost:8080/labkey/_webdav/Tutorials/List%20Tutorial/%40files/NIMH/Images/10003.png |
10004.png | http://localhost:8080/labkey/_webdav/Tutorials/List%20Tutorial/%40files/NIMH/Images/10004.png |
On import, the Assay grid will display the image thumbnail as shown below:
Lookups
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
Tutorial: Lists and the
Online List Example Project.
When a user imports data via the UI, the field will be shown as a dropdown menu listing the available values. Typing ahead will scroll the list to the matching value. When the number of available values exceeds 10,000, the field will be shown as a text entry field.
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 the display modes: Grid, Insert, Update, Details.
Format Properties
Format: You can create custom formats for displaying values in this column. For example, you can specify
Date, DateTime or Number Formats to suit your locale. 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
Data Validation (Field-level Validators)
Data validators ensure that all values entered for a field obey certain rules - such as matching a regular expression and/or falling within a specified range. They can automate checking for reasonableness and catch a broad range of data-entry errors during the upload process.
Validators are applied in the following circumstances:
| On Existing Data | On Import | On Update |
---|
Required Validator | Yes | Yes | Yes |
Regex Validator | No | Yes | No |
Range Validator | No | Yes | No |
Required
Required: When the required box is checked, a field cannot be empty. Defaults to "False."
Regular Expression Validation
Define a regular expression that defines what strings are valid.
Add Regex Validator:
- 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. The entire string value being tested must match the regular expression. Note that ".*" matches every other character and can be useful if you just want to ensure that the string contains a specific pattern. For example, ".*[<>].*" matches everything that contains either "<" or ">".
- 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.
Range Validation
Specify comparisons for numeric or date fields that must be satisfied. For example, a range can be defined with an upper and lower bound.
Add Range Validator:
- 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.
Note: Validators are not included in XML schemas exported from a study.
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.
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 with 'Missing Value Indicators' checked, can hold special values when values are missing. Unchecked by default. The set of missing values in use for a field when this option is checked can be configured site-wide or at the folder level. The default set of values are:
- Q: quality control has been applied and removed the value
- N: data will not be provided (even if it is officially required).
See
Manage Missing Value Indicators / Out of Range Values for details.
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.
Default Value
For either of the "Default Types," you may wish to set a default value. The use of this value varies depending on the "Default Type" you have chosen.
Note: This property is not included in XML schemas exported from a study.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.
Import Aliases
A set of alternate field names when importing from external files, in addition to the field's name and label. Multiple aliases may be separated by spaces or commas. To specify an alias that contains spaces, use double-quotes (") around the alias.
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.
PHI Level
Tag a field as containing some level of PHI (Protected Health Information):
These settings allow an administrator to exclude columns based on the PHI role assigned to the user. Columns marked with a PHI level higher than the current user's maximum PHI role can be excluded. For details see
Compliance: Setting PHI Levels on Fields. These are respected in the following scenarios:
- Viewing a data grid
- Editing a data record
- Exporting a data grid
- Exporting a folder or study
- Publishing a study
- Querying data
- Building reports on data
- Accessing data via the API
Possible column settings are:
- Not PHI: (Default) Not protected. Users with access to read the dataset can see this field.
- Limited PHI: Users with access to limited PHI can see this field.
- Full PHI: Only users with access to see full PHI can see this field.
- Restricted PHI: Only users with access to restricted information can see this field.
To tag a column at a specific PHI level:
- Navigate to the dataset/list that contains the column you want to protect.
- Edit the dataset/list definition.
- In the designer, select the column you wish to protect.
- Click the Advanced tab, select the appropriate level from the PHI Level dropdown.
Exclude From Shifting: If you check this box for a date column, the value 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, 2GB for SQLServer. 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