In order to leverage Fieldsets, you must first create the Fieldset(s) and define the settings, properties, and Access Policies that should be enforced before deciding which Entity Schemas the Fieldsets should apply to. You have the option to create a Name Template after the Fieldset object is created. In order to have a schema apply a Fieldset, the schema must match the exact field names and definitions that are defined by the Fieldset.
Configure a Fieldset
- Click the avatar icon in the bottom left of the Benchling platform, hover over Feature Settings, and select Fieldsets.
- In the Fieldsets menu, click the Create button in the upper right corner to create a new Fieldset.
- Define the Fieldset Settings. At minimum, you are required to specify the Name, Organization, and Available Registration Naming Options.
Each setting plays an important part for each Entity Schema that applies the Fieldset. The following definitions will help you understand each setting and how it can be useful when creating a Fieldset driven data model.
Name - Enter a descriptive name for your Fieldset into the textbox. This is the name that users will see when they use the Fieldset.
Organization - Use the dropdown to designate the organization for the Fieldset. Only the associated Entity Schemas of the designated Organization’s Registry will be able to apply this Fieldset.
Warehouse name - This name is used to access Fieldset data in both the Warehouse and the API. You may edit this name if desired.
Entity Type - Choose an Entity Type if you would like to restrict the Entity Schemas that are allowed to apply this Fieldset. This ensures that administrators can only apply this Fieldset to specific types of entity schemas.
Prefix - Configuring a prefix is optional as prefixes can be set on the Fieldset or on the schemas themselves. However, when configured the prefix will be applied to all schemas that apply the Fieldset. If you would like each schema to have its own unique prefix, leave the prefix blank on the Fieldset configuration page.
Use as Category - This is an important feature of Fieldsets. If you plan to use this Fieldset as a category for data entry on an entity link field, you must enable this setting.
Constraint - Configuring Fieldset constraints is optional. However, when configured the constraint will be applied to all schemas that apply the Fieldset. A constraint ensures uniqueness on the field(s) added to the constraint. This is used to ensure uniqueness between two entities registered across all schemas that apply the Fieldset.
Fieldset Fields - The Fieldset fields define the field names and definitions that will be used for all schemas that apply the Fieldset. Select the + icon next to the Fieldset Field to create a new field. Complete the following components when creating a new field:
Name - Name your Fieldset field. Ensure the name is meaningful and intuitive.
Warehouse name - This name is used to access field data in both the Warehouse and the API for any schema that applies the Fieldset. You may edit this name if desired.
Required - Determine if the field value is required or optional. If this box is checked, a user cannot register an entity if they do not provide a value for a required field.
Multi-select - Determine if the field should be multi-select. Some definitions, such as Dropdowns, allow you to check the multi-select box which ensures multiple values can be entered.
Definition - Choose the type of data that will be stored when a user enters a value for the field.
Available Registration Naming Options - Use the check boxes to select which Registry naming options will be available to the user when they register entities with the schema.
Name template - The ability to add a name template to the Fieldset only becomes available after the Fieldset has been created. Once the Fieldset has been created, click on the Set name template option to define the name template.
- After all settings have been specified, click Next.
- Define Access Policies
Fieldset-level Access Policies allow you to set permissions per Fieldset. Fieldsets have two general sets of permissions:
-
-
- Read - Allows users to filter the Registry by Fieldset, allows for inserting Fieldset lookup tables.
- Admin - Allows users to edit the Fieldset itself.
-
These access policies only affect who has access to edit the definition of the Fieldset itself (Admins) and who has access to filter the Registry by Fieldset or work with lookup tables that reference the Fieldset (Read).
- Click the Create button
Implement the Fieldset on the Relevant Schema(s)
- If not already created, create the entity schema(s) that will implement the Fieldset.
- Navigate to the schema that will apply the Fieldset.
- Use the schema Fieldsets dropdown to select the Fieldset that should be applied.
- Choose an available naming option.
- Click the Add button.
Update a Fieldset
Updating a Fieldset relies on the principles of how a Schema and Fieldset depend on one another. Generally, the Schema is dependent on the Fieldset.
Fieldset settings require uniqueness across the applying schemas. For example, this means that the Prefix of a Fieldset will be consistent across all Schemas that successfully apply the Fieldset. If a schema has already applied a Fieldset with a prefix or any other settings (e.g. name template, fields, etc), then you cannot apply another Fieldset with a prefix even if the fields from that Fieldset are unique. The entire Fieldset definition must be applied for it to be successful.
Adding or updating a setting on an existing Fieldset requires you to plan ahead and will likely require you to modify the Schemas that apply the Fieldset before you update the Fieldset, itself.
The following sections explain how each setting can be updated.
Name - Updating the name of a Fieldset will succeed without a failure. You will need to refresh your browser to see the new Fieldset name in Notebook entries and Categories.
Prefix - Adding or updating a Prefix on a Fieldset is dependent on the schemas that apply the Fieldset. When you add or update the prefix, Benchling will attempt to apply that prefix to all Schemas that apply the Fieldset.
If the Schema has already applied a Prefix from another Fieldset, you will not be able to add the prefix because there would be a conflict.
If the Schema has its original prefix, it will be overwritten and updated by the prefix from the Fieldset.
A prefix cannot be removed from a Fieldset that is applied by 1 or more schemas. To workaround this, you first need to un-link each schema from the Fieldset, remove the prefix on the Fieldset, and finally re-apply the Fieldset to all schemas.
Entity Type - Adding or updating the Entity Type of a Fieldset will work as long as all schemas applying the Fieldset are the type you are setting on the Fieldset.
Check all of the applied Schemas before adding or changing the Entity Type of a Fieldset to avoid errors. To correct any conflicts, choose to either update those Schemas with the correct Entity Type and/or remove the Fieldset relationship on any Schemas with conflicting Entity Types.
If you set the Entity Type to None, it removes the Entity Type constraint relationship to each schema. This operation will always succeed. This will not change the Entity Type on any of the associated schemas.
Name template - When you add or update a Name Template, Benchling will propagate it down to each Schema that applies the Fieldset. The name template from the Fieldset will propagate even if the schemas already have a name template.
Removing the Name Template from the Fieldset removes the constraint relationship between the Schema and the Fieldset. This operation will always succeed. This operation will not change the Name Template on any of the associated Schemas.
Constraints - If you add or update a constraint on a Fieldset, Benchling will attempt to propagate the changes down to all schemas that apply the Fieldset.
If any of the schemas already have an existing constraint, even a constraint on the same Fieldset field, the operation will fail.
A Fieldset constraint applies across the group of schemas that are part of the Fieldset. All schemas applying the Fieldset have to first remove their constraints to allow them to apply a Fieldset with constraints.
When all of the schemas do not have constraints, you will be able to add the constraint to the Fieldset.
Updating a Fieldset constraint will always succeed. The changes will propagate down to the constraints of the associated Schemas.
Removing a Fieldset constraint will always succeed. This will not affect the constraints of the associate schemas.
Fields - Adding a Field to a Fieldset requires the associated schemas to have that same field already defined.
Updating any attribute (e.g. definition) on a field will propagate to all associated schemas
Fields from a Fieldset can be referenced in look-ups, so removing a Field from a Fieldset may not work. To remove a field from a Fieldset, you must first remove any references to that Field.
Removing a field will not affect any fields on the associated schemas.
Archive a Fieldset
To archive a Fieldset, first remove all dependencies to the Fieldset. Dependencies include entity links to the category, look-ups to a field via the category, and schemas that apply the Fieldset.