Enforcing Unique Sample Names Within a Project
By default, Clarity LIMS allows duplicate sample names within the same project. If you would like to enforce sample name uniqueness within a project, you can do so.
Two scripts have been developed to support this requirement:
SampleNamePerProjectUniqueConstraintStep: Apply this uniqueness constraint to enforce unique sample names within a project.
CleanupDuplicatedSampleNamesPerProjectStep: Prior to running the uniqueness constraint, use this optional cleanup script to clean up a database that already contains duplicate sample names.
Both scripts are available via the clarity-migrator.jar tool.
Cleaning up the database
If your database contains projects in which duplicate sample names exist, run the CleanupDuplicatedSampleNamesPerProjectStep script to clean up sample names that would violate the sample uniqueness constraint property. The cleanup script searches the database for sample names that are not unique and renames them.
The cleanup script also renames the corresponding original submitted sample name - since there is a one-to-one correspondence between submitted sample and derived sample names in the LIMS interface.
To clean up the database:
As the glsjboss user, change to the clarity-migrator directory:\
Run the clarity-migrator.jar tool, providing the name of the cleanup step as a parameter:\
The step will run and no validation errors should be reported.
Once cleanup has been performed successfully, you can apply the sample uniqueness constraint.
Enforcing sample uniqueness
After you have cleaned up the database (if this step was required), you can apply the uniqueness constraint.
Applying the sample uniqueness constraint results in a change at the LIMS database / schema level. Once you have applied this change, there is no script available to revert it.
If you need to remove the uniqueness constraint, you will need to submit a request to the Illumina Support team.
To enforce sample uniqueness:
As the glsjboss user, change to the clarity-migrator directory:\
Run the clarity-migrator.jar tool, providing the name of the uniqueness constraint step as a parameter:\
The step will run and no validation errors should be reported.
Results
After enforcing sample uniqueness, if a user attempts to accession or update sample names that already exist in the project - via the user interface or the API - an error message displays. The message describes the problem and advises the user to rename the duplicate samples.
The following sections describe and illustrate what happens if an accessioned or updated sample name conflicts with an existing sample name within the same project.
Postgres database
If an accessioned or updated sample name conflicts with an existing sample name within the same project:
Upload/modify via a sample sheet will result in the error shown below.
The sample with duplicate name is named within the parenthesis of the Detailed error message.
The quoted string in the Detailed error is the database name of the constraint being violated (uk_sample_name_per_project = unique key on sample table for name and project).
Sample management accession/modify will result in the error shown below.
If a user attempts to accession/modify a sample name under similar circumstances via an API operation, the results received would be similar to the content of this error message.
Last updated
