Compound/Entity registration business rules

Molecule/Entity and Batch fields allow for customization of registration business rules to suit each vault’s needs. 

In this article we go over molecule/entity and batch field definition by the vault administrator. We cover adding new fields, editing and deletion of existing fields.

 See also our YouTube video on how to add or edit batch fields:

Formal chemical registration in CDD enforces molecule (or entity) and batch (or lot) registration. Data associated with molecules/entities and batches, such as unique identifiers, vendor information, date of synthesis, and chemists name, just to name a few, are stored in data fields at the appropriate level of the hierarchy. CDD auto-generates several data fields in any new vault, but these may also be customized by the vault administrator to suit each vault's business rules and needs. Existing molecule/entity or batch fields may be edited or deleted, and new fields may be added at any time. 

Moreover, molecule/entity and batch fields apply to vaults with and without formal chemical registration, and are fully integrated with CDD’s data import and validation, allowing each group to ensure that pertinent data is captured correctly for any newly registered molecules/entities and batches. As a best practice, we recommend that you consider your molecule/entity and batch/lot registration process and requirements as soon as you subscribe to CDD, and define your custom list of data fields before importing compound libraries.

 

Molecule/Entity Field Definition

Here's an example of one vault's molecule/entity fields, utilizing all of the available settings. In this example, we are using a vault that's configured to store plasmids.  As such, the Molecule terminology has been renamed to Plasmid.  We will refer to this screen-shot in the table below, describing the options.

 

Setting	Description	Editing
Name	Pick a unique name for the field. This name will appear throughout the application. Include units of measurement for numeric data: see "Backbone size" example in the screen-shot above. There is a limit of 20 characters on the Molecule/Entity field Name.	Changes apply to existing and new molecules/entities throughout the application.
Data Type	Set the kinds of values that are permitted for a given field. Date:   Vault fields of this type accept values of acceptable date formats, which include YYYY-MM-DD; YYYYMMDD; MM/DD/YYYY; Month DD, YYYY.  CDD Vault supports dates that conform to the ISO 8601 standard and provides a calendar picker for dates being entered through the user interface. Number: fields of this type accept only real numbers, excluding numeric modifiers such as >,<=, etc. If you plan to store numbers such as >95, consider using the text data type. Text: fields of this type will accept any alpha-numeric values. Pick List: define a list of permissible values that may be entered into this batch field.  See here for more details on Pick Lists File: fields of this type will accept file attachments of any format and size. Image and PDF files will be rendered with previews, all others will appear as downloadable hyperlinks.	Not editable if there are values in the database.
Must be Unique	Check this flag to ensure that values in the field are unique across the vault (batches/molecules/projects). This is a good way to designate additional identifiers when chemical structures cannot be used to determine uniqueness. For multiple unique fields, values are validated within the scope of each field, but will not be checked across fields.	Changes are prospective: applicable to new molecule/entity registration, and upon manual editing of existing molecules/entities.
Overwritable	Check this flag to allow users to overwrite existing data values in the field via the Import Data wizard.	Providing this option is intended to allow vault administrators to temporarily allow users to correct previous data mistakes in bulk.
This field is	This setting determines how this field is to be populated during new molecule/entity registration. Autogenerated: you may not edit or delete such fields. See "Plasmid name" example in the screen-shot above. Both legacy and new molecules/entities will be populated. Required: ensures that a value must be supplied on new molecule/entity registration. Optional: ensures that it is available throughout the application, but the value may be left blank on new molecule/entity registration. Conditionally Required (or <another field> is required): ensures that one of several fields is required, while others in the group are optional. In other words, a value must be supplied for one of the grouped fields, but all of them may contain values as well. To set two or more fields as conditionally required, choose "or <field name> is required" from the drop-down: you will notice that all affected fields are updated when you do so.	Changes are prospective: applicable to new molecule/entity  registration, and upon manual editing of existing molecules/entities.

 

Batch Field Definition

Here's an example of one vault's batch fields, utilizing all of the available settings. We will refer to this screen-shot in the table below, describing the options.

Setting	Description	Editing
Name	Pick a unique name for the field. This name will appear throughout the application. Include units of measurement for numeric data: see "amount" example in the screen-shot above. There is a limit of 20 characters on the Batch field Name.	Changes apply to existing and new batches throughout the application.
Data Type	Set the kinds of values that are permitted for a given field. Date:   Vault fields of this type accept values of acceptable date formats, which include YYYY-MM-DD; YYYYMMDD; MM/DD/YYYY; Month DD, YYYY.  CDD Vault supports dates that conform to the ISO 8601 standard and provides a calendar picker for dates being entered through the user interface. Number: fields of this type accept only real numbers, excluding numeric modifiers such as >,<=, etc. If you plan to store numbers such as >95, consider using the text data type. Text: fields of this type will accept any alpha-numeric values. Pick List: define a list of permissible values that may be entered into this batch field.  See here for more details on Pick Lists Batch Link: allows linking Batch records to other entities stored in the same or across separate CDD Vaults (if the Link Across Vaults feature is enabled for your CDD Account). File: fields of this type will accept file attachments of any format and size. Image and PDF files will be rendered with previews, all others will appear as downloadable hyperlinks.	Not editable if there are values in the database.
Must be Unique	Check this flag to ensure that values in the field are unique across the vault (batches/molecules/projects). This is a good way to designate additional batch identifiers, such as lab notebook number or vendor lot number: see "external identifier" example in the screen-shot above. For multiple unique fields, values are validated within the scope of each field, but will not be checked across fields.	Changes are prospective: applicable to new batch registration, and upon manual editing of existing batches.
Overwritable	Check this flag to allow users to overwrite existing data values in the field via the Import Data wizard.	Providing this option is intended to allow vault administrators to temporarily allow users to correct previous data mistakes in bulk.
This field is	This setting determines how this field is to be populated during new batch registration. Autogenerated: you may not edit or delete such fields. See "Batch name", and "Formula Weight" examples in the screen-shot above. Both legacy and new batches will be populated. Required: ensures that a value must be supplied on new batch registration. Optional: ensures that it is available throughout the application, but the value may be left blank on new batch registration. Conditionally Required (or <another field> is required): ensures that one of several fields is required, while others in the group are optional. In other words, a value must be supplied for one of the grouped fields, but all of them may contain values as well. To set two or more fields as conditionally required, choose "or <field name> is required" from the drop-down: you will notice that all affected fields are updated when you do so.	Changes are prospective: applicable to new batch registration, and upon manual editing of existing batches.

 

Add a New Field

Molecule/Entity and Batch Fields are defined only by the vault administrator, and apply to all molecules/entities and batches across all projects in the vault. 

Click on “Add/Edit xxx Fields” on the appropriate sub-tab of the Vault Settings page.

 

At the bottom of the current list of fields, click on the “Add a xxx field”, enter a unique name for the field, and set the available settings: data type, uniqueness flag, and required/optional status. Do not forget to save your work by clicking "Update" button.

A newly defined field will appear throughout the application, even if there is no value for this field on existing batches: in the import interface, on the search page keywords drop-down and results table, as well as in batch details view, and new batch registration form.

 

Edit an Existing Field 

The steps to edit an existing field are similar to adding a new one. Once in edit mode, change the settings that are available to you. Note that if any data is stored within the field you are editing, you will not be able to change it's data type. Also, if any public (shared) Saved Searches exist that include a molecule/entity/batch field, you will not be able to change it's data type even if there is no data stored in that field. Field name change is applied to all molecules/entities/batches, but if you are changing field requirement or uniqueness, the new business rule is prospective, meaning it will not apply to previously registered molecules/entities/batches. Manual editing existing data will enforce new rules. Data may be updated to compliance either manually, or via file import.

Remove an Existing Field

In edit mode, click “Remove” next to any batch field. Caution: when you remove an existing field, you are permanently deleting all the values stored in that field across the vault. You may want to do a back-up of your data before deleting a field.

 

Order Fields

In edit mode, rearrange fields by clicking the “drag” icon. The order defined on the batch Fields tab will determine the order of fields in the rest of the application, including the batch creation form, and the search page.