Custom Fields

In Clarity LIMS, custom fields are used to record information about a step, sample, or other LIMS component.

There are two types of custom fields: global fields and master step fields.

The default configuration includes both global and master step fields. You can add additional fields to meet the needs of your lab, and display those fields to the user at run time (see Step Milestones).

• Global fields—Apply to the whole LIMS system. You can use these fields to record measurements and information about measurements, submitted samples, derived samples, accounts, containers, projects, and clients.

• Master step fields apply to the master step on which they are configured, and are inherited by all steps derived from that master step.

To access the Custom Fields configuration screen, the Configuration:update permission is required. Users who do not have this permission do not see the Custom Fields tab.

By default, only the Administrator role has the Configuration:update permission. For more on user roles and permissions, see User Roles and Configured Role-Based Permissions.

Configuration: Update Permission Access

• View custom fields.

• Add new custom fields.

• Edit custom fields.

• Delete custom fields.

Access the Custom Fields Configuration Screen and View Existing Custom Fields

1. On the main menu, select Configuration.

2. On the LIMS configuration screen, select the Custom Fields tab.

3. On the Custom Fields configuration screen, select the Global Fields or Master Step Fields tab.

   All global fields and master step fields configured in the system are listed on their respective tab, and are organized into groups.

   • Global fields are grouped by object—Measurement, Derived Sample, Submitted Sample, Account, Container, Project, and Client.

   • Global field groups are sorted by the number of fields each contains, starting with the group that contains the most fields. Groups with the same number of fields are sorted alphabetically.

   • Master step fields are grouped by master step.

   • Master step field groups are sorted alphabetically.

4. Select a group header to expand the list of fields it contains.

   Each list item includes the name of the custom field and an icon to convey its field type (see Field Types and Additional Options).

Note the following additional details:

• An asterisk (*) displays if the custom field is Required.

• Secondary icons display if the custom field is Read-Only or a Dropdown list.

  NOTE: To maximize the number of field name characters displayed, the asterisk and secondary icons are hidden in smaller viewports (between 766 px and 875 px).

• Select a field to view its details in the Field Details area on the right (see Field Details).

• If viewing master step fields, there is also a Group of Defaults section. Select a group to see the fields and their prepopulated values. For details, see Configure Groups of Defaults.

Add and Configure Custom Fields

Configure custom fields to record information about a step, sample, or other Clarity LIMS component.

For example, you can:

• Use global fields to capture sample measurements and track information about projects.

• Use master step fields to record instrument settings and other details about a specific step.

• Configure automation scripts that populate custom fields or perform calculations at run time.

• Create groups of defaults—collections of prepopulated master step fields that eliminate the need for manual input of values at run time and make sure that the correct information is always recorded.

When adding custom fields, keep the following in mind:

• You cannot save a custom field until you have entered a name and selected a field type.

• You cannot create a custom field on a global field object or master step with the same name as an existing field on that object/master step. For example, if you have a created a global field called 'Description' on the Account object, you cannot create another global field called 'Description' on the Account object. However, you can create a 'Description' field on the Project object.

• If the field name you specify is the same as a field that has been deleted, the new field is created and the conflicting field name is renamed. Deleted fields do not display in the LIMS interface, but are saved in the database.

Add a Custom Field

1. On the main menu, select Configuration.

2. On the configuration screen, select the Custom Fields tab.

3. On the Custom Fields configuration screen, select the Global Fields or Master Step Fields tab.

4. In the header of the global field object or master step for which you want to add a new field, select Add.

5. In the Field Details area, complete the required fields:

   a. Type a name for the field.

   b. Select the appropriate field type. See sections below for details.

6. Set the required field options:

   • Required: If this field must be filled in, set this option to Yes. Otherwise, set to No.

   • Read only: If you do not want the user to edit the field value at run time, set to Yes. To allow editing of the field at run time, set to No

7. The Field Options and Additional Options reflect the field type selected:

   • Default (for nondrop-down field types only): If you would like to set a default value, enter the value here.

   • Dropdown Items (for drop-down field types only):

   To set a default item, add this value first and set the Set as Default toggle switch to Yes. You can only set the first item as the default, and you cannot reorder items after you have added them.

   • Repeat to add more items to the list.

   • To remove a list item, select the X button.

   • If you do not specify any drop-down items, or if you specify only one item and set it as the default value, upon save, the field converts to its equivalent nondrop-down type and custom entries are enabled.

   • Select Add and enter the first list item.

8. Complete other options, as required. See sections below for details.

9. Select Save. The new custom field is added to the bottom of the fields list. It is now available to be displayed on master step and/or step milestone screens.

Field Details

For any field selected, the Field Details area displays the following information:

• The field name.

• The global field object (Derived Sample shown here), or the master step, with which the field is associated.

• The field type.

• The field options, that is, whether the field is:

  • Required—If set to Yes, the field must be filled in.

  • Read only—If set to Yes, the field cannot be edited at run time.

• The default value for the field, if set.

• For drop-down field types:

  • The Default option is replaced with a Dropdown Items list.

  • The first list item may be set as the default value for the field.

Additional options may also display, as described below. These differ depending on the field type. For example, the Range From and To fields only display for Numeric field types.

Field Types and Additional Options

The following table describes the field types available for custom fields, and the additional options that apply to each type.

Custom Field Types and Additional Options

Field Type	Field Description	Additional Options
Text	Field in which to type a line of text. Field length is only limited by the database field used to store it. PostgreSQL limit - 1 Gb, Oracle limit - 4000 characters.	Not applicable
Numeric	Field in which to type a number.	Range From, To Decimal Places Displayed
Hyperlink	Field containing a link to a website URL. Select the link to open the URL in a web browser.	None
Text Dropdown	Field in which to select from a list of predefined text options.	Custom Entries Dropdown Items
Numeric Dropdown	Field in which to select from a list of numbers.	Custom Entries Dropdown Items Range From, To Decimal Places Displayed
Hyperlink Dropdown	Field in which to select from a list of website URLs. Select a link to open the URL in a web browser.	Custom Entries Dropdown Items
Multiline Text	Field in which to type multiple lines of text.	Not applicable
Toggle Switch	A field to toggle between Yes and No values.	None Set (Default) Yes No
Date	A calendar tool to select a date.	Not applicable

Toggle Switch Field Types

The Toggle Switch field type renders as a toggle switch on the Record Details screen.

Configuration options:

• Default value configured as Yes or No: When the screen displays, Yes or No is selected by default. User can select Yes or No.

• Default value configured as None Set: When the screen displays, neither Yes nor No is selected. User selects a value.

• Required: The field may be configured as a required field, even if the default value is None Set. When the user enters the screen, neither Yes nor No is selected, but a value must be selected.

Additional Optional Usage

The following table explains how to use the additional options associated with the Numeric, Numeric Dropdown, Text Dropdown, and Hyperlink Dropdown field types.

Field Types Additional Options Usage

Additional Options	Usage
Range From, To	Use to define the range within which numeric values must fall. At run time, the user is prevented from entering a number outside of the defined range.
Decimal Places Displayed	Use to specify the number of decimal places to display in a numeric field. This value is used for display purposes only. The field stores the value as input by the user or script. Note: If the user edits the value of a Numeric field (or gives the field focus by selecting inside it), the value that displays— including the number of decimal places, is written to the database, overwriting the existing value. For this reason, we recommend that you increase the number of decimal places to display to ensure sufficient precision.
Dropdown Items	Use to create a list of options to select at run time.
Custom Entries	Use to control whether or not the user may enter a value at run time. If set to No, a value from the predefined drop-down list must be selected. If set to Yes, a value must be entered into the field.

Edit and Delete Custom Fields

This section describes how to edit and delete custom fields.

Edit Custom Fields

1. On the Custom Fields configuration screen, select the Global Fields or Master Step Fields tab.

2. Expand the global field object group or master step containing the field to edit.

3. Select the field.

4. Make your changes and select Save.

When editing custom fields, keep the following in mind:

• You cannot modify the field type, unless you are changing a drop-down field type to its equivalent nondrop-down type or vice versa. For example, you can change a Numeric Dropdown field to a Numeric field, or a Text field to a Text Dropdown field.

• If you convert a drop-down field type to its equivalent nondrop-down type, Clarity LIMS removes all nondefault list values and enables custom entries upon saving. If a default drop-down option was set, it becomes the default for the nondrop-down field.

Delete Custom Fields

1. On the Custom Fields configuration screen, select the Global Fields or Master Step Fields tab.

2. Expand the global field group or master step containing the field you would like to delete.

3. Select the field and select Delete. Confirm the deletion.

When deleting custom fields, keep the following in mind:

• You cannot delete a master step field if it has been assigned a value, or is in use in a step—that is, if a step derived from the master step with which the field is associated has been started.

• If you delete a custom field, it no longer displays in the LIMS interface. However, its information is saved in the database for historical purposes.

• You cannot restore a deleted field for use in the LIMS, but you can create a field with the same name. The original deleted field is renamed in the database.

Reorder Global Fields

You cannot reorder master step fields on the Custom Fields configuration screen. This configuration is instead available on the Record Details milestone. For details, refer to the Configure Step Data section of the Configure Record Details Milestone topic.

However, you can reorder global fields by simply clicking and dragging them into position.

To drag and drop on a mobile or touch-screen device, touch and hold the item you wish to drag. After a moment, the item appears to lift off the page and its color changes to white. You can then drag the item and drop it into its new position.

The order is reflected in various places in the LIMS interface, for example:

• Submitted sample global field ordering is reflected on the Sample Management screen, in the Sample Details section.

• Project global field ordering is reflected on the Project Details screen (on the Custom Fields tab) and on the Sample Management screen (in the Project Details section).

Configure Groups of Defaults

Groups of defaults are collections of prepopulated master step fields. Using these eliminates the need for lab scientists to manually enter field values each time they run the step, and makes sure that the correct information is recorded every time a step is run.

When you have added groups of defaults to a master step:

• They become available for selection when you create a step based on the master step.

• When running a step in Clarity LIMS, if the step has one or more groups of defaults configured, these steps display in a drop-down list in the upper-right corner of the Record Details screen. Select the desired group of defaults and the LIMS populates the step fields with the corresponding values.

• If you have configured a default group of defaults, those values automatically populate the step fields.

Add a Group of Defaults

1. On the Custom Fields configuration screen, select the Master Step Fields tab.

2. Expand the master step on which to configure a group of defaults.

3. Below the configured master step fields, in the Group of Defaults section, select Add.

4. In the Group of Defaults area on the right, the fields associated with the master step display.

   • Name the group of defaults.

   • Populate each field with the value to set for the group of defaults.

5. Select Save.

6. [Optional] When configuring the Record Details milestone for a step, if the related master step has one or more groups of defaults configured, you can select a default group to display.

7. [Optional] Reorder groups of defaults by clicking and dragging them into position.

   To drag and drop on a mobile or touch-screen device, touch and hold the item you wish to drag. After a moment, the item appears to lift off the page and its color changes to white. You can then drag the item and drop it into its new position.

   The order is reflected in the drop-down list that displays at the top of the Record Details screen.