Custom Fields

[BioPharma]

Custom Fields are key-value pairs that can be associated with files and folders in the Repository. Fields have properties that are convenient for tracking metadata, including:

Compatibility with search functions
Value types and input validators for enforcing correct data entry
A flag to indicate its value “may contain PHI” for downstream anonymization
Can be grouped into field sets as template for recurring study types
User access to fields can be controlled via permission flags

Fields at the folder-level may be used to track general information about a particular case or study and fields at file-level may be used to track additional information (e.g., stain type of an image).

Some fields are defined automatically by the system (i.e., System Fields) and others may be user defined (i.e., Custom Fields). To learn more about fields and their properties, see Working With Custom Fields.

To be able to change the properties of Custom Fields, special permissions are required. See Permission Flags or contact your administrator for more information.

Working With Custom Fields

Fields are key-value pairs that can be associated with items (e.g., files, folders) in the Repository. Fields can be added or removed from items and field values can be edited by users that have the Edit metadata permission, see Permission Flags.

Clicking on a field value anywhere will trigger a search for all items in the Repository that have a field with the same value that was clicked. The search can then be modified to a different value for the same field from the search page.

Metadata fields that are marked with “May contain PHI” will be hidden (field value will be “Anonymized”) for users that do not have “View Protected Health Information” permission.

Working With Fields From the Repository

Fields associated with any item in the Repository can be edited from the Repository.

To view an item’s fields

Navigate to any folder in the Repository (click on the Repository button from the Navigation Menu then navigate to a folder)
Select a single item in a folder
View fields in the Metadata tab of the right-hand panel. You may need to click on the button if the panel is collapsed

To add fields to an item

Navigate to any folder in the Repository (click on the Repository button from the Navigation Menu then navigate to a folder)
Select a single item in a folder
View fields in the Metadata tab of the right-hand panel. You may need to click on the button if the panel is collapsed
Click on the Edit Metadata button
In the popup dialog, click on the Add Fields dropdown menu
(Optional) Begin typing to search for a field by name
Select a field from the dropdown menu
Enter values for fields accordingly
Click on the Update button to save your changes, or click on the X button at the top right corner of the popup dialog to cancel

The Edit Metadata dialog can also be accessed from the context menu. See Repository Operations for more details.

To edit an item’s fields

Navigate to any folder in the Repository (click on the Repository button from the Navigation Menu then navigate to a folder)
Select a single item in a folder
View fields in the Metadata tab of the right-hand panel. You may need to click on the button if the panel is collapsed
Click on the Edit Metadata button
Change the value(s) of the listed field(s) accordingly, or clear the value by clicking on the gray X inside the field at the right-hand side
Click on the Update button to save your changes, or click on the X button at the top right corner of the popup dialog to cancel

If you attempt to modify an item which is governed by a reason for change tracking policy, you will be required to provide a reason for the change.

To delete fields from an item

Navigate to any folder in the Repository (click on the Repository button from the Navigation Menu then navigate to a folder)
Select a single item in a folder
View fields in the Metadata tab of the right-hand panel. You may need to click on the button if the panel is collapsed
Click on the Edit Metadata button
Click on the red X button at the far right-hand side, outside of a field, to remove it from the item
Click on the Update button to save your changes, or click on the X button at the top right corner of the popup dialog to cancel

If you attempt to modify an item which is governed by a reason for change tracking policy, you will be required to provide a reason for the change.

Working With Fields From Within the Viewer

Fields associated with any item that is viewable in the Viewer can be edited from within the Viewer.

To view an item’s fields

If the left sidebar is not displayed, toggle it by clicking on the Menu > button at the bottom left of the Viewer
Hover or click on the button in the left sidebar
System and Custom Fields are displayed. You may need to scroll down to see them all

To add fields to an item

If the left sidebar is not displayed, toggle it by clicking on the Menu > button at the bottom left of the Viewer
Hover or click on the button in the left sidebar
Click on the Edit Metadata button
In the popup dialog, click on the Add Fields dropdown menu
(Optional) Begin typing to search for a field by name
Select a field from the dropdown menu
Enter values for fields accordingly
Click on the Update button to save your changes, or click on the X button at the top right corner of the popup dialog to cancel

To edit an item’s fields

If the left sidebar is not displayed, toggle it by clicking on the Menu > button at the bottom left of the Viewer
Hover or click on the button in the left sidebar
Click on the Edit Metadata button
Change the value(s) of the listed field(s) accordingly, or clear the value by clicking on the gray X inside the field at the right-hand side
Click on the Update button to save your changes, or click on the X button at the top right corner of the popup dialog to cancel

If you attempt to modify an item which is governed by a reason for change tracking policy, you will be required to provide a reason for the change.

To delete fields from an item

If the left sidebar is not displayed, toggle it by clicking on the Menu > button at the bottom left of the Viewer
Hover or click on the button in the left sidebar
Click on the Edit Metadata button
Click on the red X button at the far right-hand side, outside of a field, to remove it from the item
Click on the Update button to save your changes, or click on the X button at the top right corner of the popup dialog to cancel

If you attempt to modify an item which is governed by a reason for change tracking policy, you will be required to provide a reason for the change.

Custom Field Settings

Custom Fields can be used to define metadata for tracking study or case information. Fields have properties such as a name, type, input validators to enforce correct data entry, and a PHI flag that is used for anonymization.

Fields are accessible to users that have the appropriate permissions, see Permissions.

To view existing fields

Click on the Settings button from the Navigation Menu
Click on the Fields tab

To create a new field

Click on the Settings button from the Navigation Menu
Click on the Fields tab
Click on the Create Field button
Select a type of field from the Type dropdown menu. See Field Types more information about types
Type in a name for the field in the Name area
(Optional) Select “Field may contain protected health information (PHI)” if the field may contain PHI. See Fields With PHI for more information about anonymization
(Optional) Select the appropriate validators if applicable. See Field Validators for more information about data entry errors
(Optional) For "Dropdown" types, use the + Add option button to define each option
Click on the Create Field button when finished

Editing Custom Fields

The properties of existing fields can be edited so long as the changes do not invalidate existing values of the field. For instance:

The type of field should not be changed after it has been associated with an item
Options in a dropdown menu field should be removed cautiously after they have been associated with an item

To edit the properties of an existing field

Click on the Settings button from the Navigation Menu
Click on the Fields tab
Select the field to be edited
Make changes as desired
Click on the Save Field button when finished, or click on the Close button to discard the changes

Deleting Custom Fields

Deleting a field that is in use will affect all items in the Repository with that field.

To delete an existing field

Click on the Settings button from the Navigation Menu
Click on the Fields tab
Select the field to be deleted
Click on the Delete Field button
Click on the Yes button to confirm

Fields With PHI

Fields that contain protected health information (PHI) or other sensitive information may be marked as such. If the PHI flag has been set/checked for a field, the application will replace the value of the field with "Anonymized" for users that do not have the correct permissions. See Permission Flags for more details.

Field Types

All fields, including System Fields and Custom Fields, have one of the following types:

Field Type	Description
Text	Single line text field. May be used for unstructured or structured data such as comments or barcodes. See Field Validators
Numbers	Supports integer and floating-point numeric values
Checkbox	Supports true/false values
Dropdown	Holds a single value from a list of possible options
Date	A date field with calendar support for data entry
DateTime	A field that holds a date and time. The user can enter the value using a popup calendar tool
User	A dropdown menu containing entries for all active users and users pending activation

Field Validators

Field validators are used to enforce the correct entry of data by users. Users will not be allowed to enter data into fields that do not conform to the correct pattern, if a validator is defined. The following validators are available:

Field Type	Validators
Text	Min Length: the minimum number of characters allowed Max Length: the maximum number of characters allowed Pattern: a regular expression conforming to JS Regex standard
Numbers	Integer: if selected, requires an integer value; otherwise, floating point values are considered valid Minimum: the minimum value allowed Maximum: the maximum value allowed
Checkbox	n/a
Dropdown	n/a
Date	Minimum: the oldest value allowed Maximum: the latest value allowed
DateTime	Minimum: the oldest value allowed Maximum: the latest value allowed
User	n/a

The Pattern validator for text fields passes if the regular expression matches all or part of the input, unless the ^ and/or $ anchors are used. See the JS Regex reference for details.

Validators are not enforced through the API and they are not enforced when fields are imported from a CSV file.