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
  1. Navigate to any folder in the Repository (click on the Folder Repository button from the Navigation Menu then navigate to a folder)

  2. Select a single item in a folder

  3. View fields in the Metadata tab of the right-hand panel. You may need to click on the Expand button if the panel is collapsed

To add fields to an item
  1. Navigate to any folder in the Repository (click on the Folder Repository button from the Navigation Menu then navigate to a folder)

  2. Select a single item in a folder

  3. View fields in the Metadata tab of the right-hand panel. You may need to click on the Expand button if the panel is collapsed

  4. Click on the Edit Metadata button

  5. In the popup dialog, click on the Add Fields dropdown

  6. (Optional) Begin typing to search for a field by name

  7. Select a field from the dropdown

  8. Enter values for fields accordingly

  9. 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
  1. Navigate to any folder in the Repository (click on the Folder Repository button from the Navigation Menu then navigate to a folder)

  2. Select a single item in a folder

  3. View fields in the Metadata tab of the right-hand panel. You may need to click on the Expand button if the panel is collapsed

  4. Click on the Edit Metadata button

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

  6. 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
  1. Navigate to any folder in the Repository (click on the Folder Repository button from the Navigation Menu then navigate to a folder)

  2. Select a single item in a folder

  3. View fields in the Metadata tab of the right-hand panel. You may need to click on the Expand button if the panel is collapsed

  4. Click on the Edit Metadata button

  5. Click on the red X button at the far right hand side, outside of a field, to remove it from the item

  6. 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
  1. If the left sidebar is not displayed, toggle it by clicking on the Menu > button at the bottom left of the Viewer

  2. Hover or click on the Info button in the left sidebar

  3. System and Custom Fields are displayed. You may need to scroll down to see them all

To add fields to an item
  1. If the left sidebar is not displayed, toggle it by clicking on the Menu > button at the bottom left of the Viewer

  2. Hover or click on the Info button in the left sidebar

  3. Click on the Edit Metadata button

  4. In the popup dialog, click on the Add Fields dropdown

  5. (Optional) Begin typing to search for a field by name

  6. Select a field from the dropdown

  7. Enter values for fields accordingly

  8. 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
  1. If the left sidebar is not displayed, toggle it by clicking on the Menu > button at the bottom left of the Viewer

  2. Hover or click on the Info button in the left sidebar

  3. Click on the Edit Metadata button

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

  5. 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
  1. If the left sidebar is not displayed, toggle it by clicking on the Menu > button at the bottom left of the Viewer

  2. Hover or click on the Info button in the left sidebar

  3. Click on the Edit Metadata button

  4. Click on the red X button at the far right hand side, outside of a field, to remove it from the item

  5. 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
  1. Click on the Settings Settings button from the Navigation Menu

  2. Click on the Fields tab

To create a new field
  1. Click on the Settings Settings button from the Navigation Menu

  2. Click on the Fields tab

  3. Click on the Create Field button

  4. Select a type of field from the Type dropdown. See Field Types more information about types

  5. Type in a name for the field in the Name area

  6. (Optional) Select “Field may contain protected health information (PHI)” if the field may contain PHI. See Fields With PHI for more information about anonymization

  7. (Optional) Select the appropriate validators if applicable. See Field Validators for more information about data entry errors

  8. (Optional) For Dropdown types, use the + Add option button to define each option

  9. 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 field should be removed cautiously after they have been associated with an item
To edit the properties of an existing field
  1. Click on the Settings Settings button from the Navigation Menu

  2. Click on the Fields tab

  3. Select the field to be edited

  4. Make changes as desired

  5. 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
  1. Click on the Settings Settings button from the Navigation Menu

  2. Click on the Fields tab

  3. Select the field to be deleted

  4. Click on the Delete Field button

  5. 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 TypeDescription
TextSingle line text field. May be used for unstructured or structured data such as comments or barcodes. See Field Validators
NumbersSupports integer and floating-point numeric values
CheckboxSupports true/false values
DropdownHolds a single value from a list of possible options
DateA date field with calendar support for data entry
DateTimeA field that holds a date and time. The user can enter the value using a popup calendar tool
UserA dropdown 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 TypeValidators
TextMin Length: the minimum number of characters allowed
Max Length: the maximum number of characters allowed
Pattern: a regular expression conforming to JS Regex standard
NumbersInteger: if selected, requires an integer value; otherwise, floating point values are considered valid
Minimum: the minimum value allowed
Maximum: the maximum value allowed
Checkboxn/a
Dropdownn/a
DateMinimum: the oldest value allowed
Maximum: the latest value allowed
DateTimeMinimum: the oldest value allowed
Maximum: the latest value allowed
Usern/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.