basespace clarity lims 5.0 data model documentation · many of the database table names described...
TRANSCRIPT
BaseSpace Clarity LIMS 5.0Data Model Documentation
GenoLogics, An Illumina Company
ii
Preface ......................................................................................................................................... v
1. How to Use this Guide ..................................................................................................... v
2. Intended Audience and Prerequisites ................................................................................. v
3. Your Feedback ................................................................................................................. v
1. Concepts .................................................................................................................................. 1
1.1. Unique identifiers - *id and luid ..................................................................................... 1
1.2. ownerid ......................................................................................................................... 1
1.3. createddate .................................................................................................................... 1
1.4. lastmodifiedby and lastmodifieddate ............................................................................... 2
1.5. attachtoclassid and attachtosubtypeid .............................................................................. 2
1.6. Property key value pairs ................................................................................................ 3
2. Terminology ............................................................................................................................. 4
2.1. ...................................................................................................................................... 4
3. User Information ...................................................................................................................... 5
3.1. General ......................................................................................................................... 5
3.2. Attributes ...................................................................................................................... 5
3.3. Associated Data ............................................................................................................. 6
4. Project ..................................................................................................................................... 7
4.1. General ......................................................................................................................... 7
4.2. Attributes ...................................................................................................................... 7
4.2.1. LUID .................................................................................................................. 7
4.2.2. Maximum Sample ID .......................................................................................... 7
4.2.3. Status ................................................................................................................. 8
4.3. Associated Data ............................................................................................................. 8
4.4. Examples ....................................................................................................................... 9
4.4.1. New Projects ...................................................................................................... 9
4.4.2. Closed Projects ................................................................................................... 9
5. Process ................................................................................................................................... 11
5.1. General ........................................................................................................................ 11
5.2. Attributes ..................................................................................................................... 11
5.3. Associated Data ........................................................................................................... 12
5.4. Examples ..................................................................................................................... 14
5.4.1. Process Runs .................................................................................................... 14
5.4.2. Processes Completed ......................................................................................... 15
5.4.3. Processtype Filtering ......................................................................................... 15
5.4.4. Processes Run By A Specific User ..................................................................... 15
5.4.5. List of Processes Run On A Specific Instrument and Software ............................. 16
5.4.6. Processes Associated To A Specific Project ........................................................ 16
6. Sample ................................................................................................................................... 18
6.1. General ........................................................................................................................ 18
BaseSpace Clarity LIMS 5.0 Data Model Documentation
iii
6.2. Attributes ..................................................................................................................... 18
6.3. Associated Data ........................................................................................................... 18
6.4. Examples ..................................................................................................................... 19
6.4.1. Processes Run On A Specific Sample ................................................................ 19
6.4.2. Controls ............................................................................................................ 20
7. Artifact ................................................................................................................................... 21
7.1. General ........................................................................................................................ 21
7.2. Attributes ..................................................................................................................... 21
7.3. Associated Data ........................................................................................................... 21
8. Control ................................................................................................................................... 23
8.1. General ........................................................................................................................ 23
9. Control Type .......................................................................................................................... 24
9.1. General ........................................................................................................................ 24
9.2. Attributes ..................................................................................................................... 24
9.3. Associated Data ........................................................................................................... 24
9.4. Examples ..................................................................................................................... 25
9.4.1. Control Samples ................................................................................................ 25
9.4.2. Controls for a Protocol Step .............................................................................. 26
10. Workflow Configuration ....................................................................................................... 27
10.1. General ...................................................................................................................... 27
10.2. Attributes ................................................................................................................... 27
10.3. Associated Data ......................................................................................................... 29
10.4. Examples ................................................................................................................... 29
10.4.1. Showing all workflows and their protocols ....................................................... 29
10.4.2. Showing process stats for all active workflows ................................................. 30
11. Reagent Kits and Lots .......................................................................................................... 31
11.1. General ...................................................................................................................... 31
11.2. Attributes ................................................................................................................... 31
11.3. Associated Data ......................................................................................................... 32
11.4. Examples ................................................................................................................... 32
11.4.1. Showing all reagent kits and lots for protocol steps ........................................... 32
12. User-Defined Field (UDF) .................................................................................................... 34
12.1. General ...................................................................................................................... 34
12.2. Attributes and Associated Data ................................................................................... 34
12.3. Value Storage ............................................................................................................ 37
12.4. Decoding the UDF values for different UDF types ....................................................... 38
12.5. Examples ................................................................................................................... 39
12.5.1. List of all UDFs defined in the system ............................................................. 39
12.5.2. Result File UDF Names and Values ................................................................. 40
12.5.3. Project UDF Names and Values ....................................................................... 41
BaseSpace Clarity LIMS 5.0 Data Model Documentation
iv
12.5.4. Process UDF Names and Values ...................................................................... 42
12.5.5. Process Output UDF Names and Values ........................................................... 43
12.5.6. List of all UDF preset values for a specific UDF ............................................... 45
13. User-Defined Type (UDT) .................................................................................................... 46
13.1. General ...................................................................................................................... 46
13.2. Attributes ................................................................................................................... 46
13.3. Associated UDFs ....................................................................................................... 47
13.4. Examples ................................................................................................................... 47
13.4.1. Project UDT and UDF Names and Values ........................................................ 47
13.4.2. Process UDT and UDF Names and Values ....................................................... 49
14. Glsfile .................................................................................................................................. 51
14.1. General ...................................................................................................................... 51
14.2. Attributes ................................................................................................................... 51
14.2.1. File Server Name ............................................................................................ 51
14.2.2. File URI ......................................................................................................... 51
14.2.3. Original Location ............................................................................................ 52
14.2.4. Is Published [deprecated] ................................................................................. 52
14.2.5. Is Temporary .................................................................................................. 52
14.2.6. Attach To ID / Class ID .................................................................................. 52
14.3. Associated Data ......................................................................................................... 52
14.4. Examples ................................................................................................................... 53
14.4.1. New Files ....................................................................................................... 53
14.4.2. Project Files .................................................................................................... 53
15. Software, Instrument and more .............................................................................................. 54
15.1. General ...................................................................................................................... 54
15.2. Attributes ................................................................................................................... 54
16. UDF-Related Views .............................................................................................................. 57
16.1. General ...................................................................................................................... 57
16.2. Views ........................................................................................................................ 57
16.3. Attributes ................................................................................................................... 57
16.4. Usage ........................................................................................................................ 59
17. Auditing ............................................................................................................................... 60
17.1. General ...................................................................................................................... 60
17.2. Attributes ................................................................................................................... 60
17.3. Associated Data ......................................................................................................... 61
17.4. Examples ................................................................................................................... 62
17.4.1. Audit Events for a particular user ..................................................................... 62
v
PrefaceBaseSpace Clarity LIMS is GenoLogics' comprehensive and integrated laboratory asset, workflow, and
data management platform. BaseSpace Clarity LIMS transforms laboratory processes into a sophisticated
end-to-end system and enables the efficient collection, organization, management, and analysis of
information across sciences.
1. How to Use this Guide
This guide provides examples of queries for a variety of common scenarios in genomics and proteomics
labs, including diagrams of the relevant portions of the schema. These examples can guide you in building
reports based on similar types of queries to extract the data that is important to your lab.
To use this guide, we suggest that you choose a query that is similar to the type of question that you
wish to ask. Then, begin modifying the SQL to reflect the configuration and usage of your GenoLogics
system. Continue to modify the SQL, using the schema diagrams as a guide, in order to gather the required
information.
2. Intended Audience and Prerequisites
This guide provides an overview of the data model used by the BaseSpace Clarity LIMS database. It
assumes that you or someone in your laboratory's IT department have experience with relational databases
and a basic understanding of SQL.
3. Your Feedback
For more information about GenoLogics products, please consult the training videos and documentation
at support.genologics.com. After consulting the documentation, should you have further questions, please
e-mail us at [email protected].
1
Chapter 1. ConceptsThere are several concepts which apply throughout the BaseSpace Clarity LIMS database and are
important for understanding the following detailed sections. These concepts are explained in the
following text.
1.1. Unique identifiers - *id and luid
The BaseSpace Clarity LIMS system uses numeric identifiers internally. These identifiers generally have
*id at the end of their name. For example, the identifier in the project table would be the projectid. These
identifiers are also used for specifying relationships between tables. For example, there is a researcherid
field in the project table that associates the researcher directly to the project.
Additional unique identifiers are created and stored in parallel to the mentioned internal identifiers. These
identifiers are character strings and are usually stored in a field named luid, which is short for LIMS
Unique Identifier (LIMS ID). Each LIMS ID is specific to the table it is a field of and does not have any
relationship to other LIMS IDs. It is generally derived from other fields, making the LIMS ID unique
across all tables in the system. The specific generation strategy is documented with the actual table.
1.2. ownerid
The ownerid on any record establishes a relationship to a user. Generally, this will be the user who caused
the record to be created. It can be joined to the principalid in the principals table.
The following example query shows how the username, as well as the first and last name of the owner
of each project in the system can be retrieved.
SELECT
project.name,
principals.username,
researcher.firstname,
researcher.lastname
FROM
project
JOIN principals ON project.ownerid = principals.principalid
JOIN researcher ON principals.researcherid = researcher.researcherid
1.3. createddate
Most tables have a field named createddate that stores the date and time information of the record
creation.
Concepts
2
1.4. lastmodifiedby and lastmodifieddate
Most tables have two fields named lastmodifiedby and lastmodifieddate that store the date and time
of the last modification to this record as well as the identifier of the user responsible for the change. To
retrieve the details of the modifiying user a query analogous to the following query can be used:
SELECT
project.name AS projectname,
project.lastmodifieddate,
principals.username,
researcher.firstname,
researcher.lastname
FROM
project,
principals,
researcher
WHERE
project.lastmodifiedby = principals.principalid
AND principals.researcherid = researcher.researcherid
1.5. attachtoclassid and attachtosubtypeid
The fields attachtoclassid and attachtoid are used together with the classindex table to define
"ANY" relationships. The attachtoclassid field will always reference classindex.classindexid. The
attachtoid field will reference the field with the name matching classindex.anycolumn in the table
with the name matching classindex.tablename.
An example query would be:
SELECT
*
FROM entityudfstorage
INNER JOIN classindex
ON entityudfstorage.attachtoclassid = classindex.classindexid
INNER JOIN project
ON entityudfstorage.attachtoid = project.projectid
WHERE
classindex.classname = 'Project'
Note: the fields are not always named attachtoclassid and attachtoid, but will always be of the format
*id and *classid. For instance, protocol attaches to a process using the processid and processclassid
columns.
Concepts
3
The field attachtosubtypeid is sometimes used in conjunction with the attachtoclassid in narrowing
which sub-types of a class something can be attached to. For instance, the process type 'Configured
Process' is used to model many processes in the system. No matter which subtype of configured process
has been run, its data will be stored in the configuredprocess table. In order to allow different UDFs
on different types of configured process, we use the attachtosubtypeid to discriminate based on the
processtype.typeid.
An example query for finding all of the applicable UDFs for the 'Copy' configured process would be:
SELECT
processtype.displayname,
classindex.classname,
classindex.tablename,
udf.name
FROM processtype, classindex, udf
WHERE classindex.classname = 'ConfiguredProcess'
AND processtype.typename = 'ConfiguredProcess'
AND udf.attachtoclassid = classindex.classindexid
AND udf.attachtosubtypeid = processtype.typeid
AND processtype.displayname = 'My Configured Process Name'
1.6. Property key value pairs
The Property table is used to store key value pairs for general system configuration and for persisting
custom key value pairs. Properties are keyed by the name column.
An example query would be:
SELECT
propertyid, -- identifier
name, -- key value for the property
value, -- current assigned value
defaultvalue, -- system default
description, -- describes details about the value
iscustom, -- whether this is a custom value or a built in system value
showinapi, -- whether this value will appear in the api
createddate,
lastmodifieddate
FROM
property
4
Chapter 2. TerminologyMany of the database table names described in this documentation differ from the user-facing terminology
in the BaseSpace Clarity LIMS UI. To help make it easier to understand how to extract specific
information from the system, we have included this chapter that describes the name used in the BaseSpace
Clarity LIMS User Interface, and its corresponding representation in the database.
Table 2.1.
UI term Database table or column name
Custom Field User-Defined Field (UDF)
Custom Type User-Defined Type (UDT)
Workflow labworkflow
Master Step ProcessType
Protocol labprotocol
Master Step Configuration processtype.stepconfiguration
Step Configuration protocolstep.stepconfiguration
Group of Defaults protocol
Automation processparameter
Step Triggers epptriggerconfiguration
Master Step Triggers masterepptriggerconfiguration
Groups of Labels reagentcategory
Group of Defaults protocol
5
Chapter 3. User Information
3.1. General
User information as well as other information related to researcher is stored in a group of tables in the
BaseSpace Clarity LIMS data model.
3.2. Attributes
The central table for each person is the researcher table, which contains the following attributes:
SELECT
researcherid,
roleid,
firstname,
lastname,
title,
initials,
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby,
labid,
addressid
FROM
researcher
A person acting as a system user needs a record in the principals table associated to the researcher,
which contains the following attributes:
SELECT
principalid,
username,
password, -- the encyrpted password
isvisible,
isloggedin,
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby,
researcherid,
ldapdn
FROM
principals
User Information
6
3.3. Associated Data
The diagram below shows tables related to user and their relationships.
Figure 3.1. User Associated Data
7
Chapter 4. Project
4.1. General
A project is one of the top level entities in the system and ties together researcher and samples and
therefore indirectly most of the data in the system.
4.2. Attributes
Project has the following attributes:
SELECT
projectid, -- internal identifier
name, -- name
opendate, -- time stamp of when the project was opened
closedate, -- time stamp of when the project was closed
invoicedate, -- time stamp of when the project was invoiced
luid, -- LIMS identifier
maximumsampleid, -- sample count/maximum relative sample id
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby,
researcherid -- identifier of the researcher associated to the project
FROM
project
4.2.1. LUID
The default generation pattern for the project LIMS ID is to use the first three characters of the name
attribute in upper case and append the projectid. For example a project with name='Liver Research
Project' and projectid='1234' would result in luid='LIV1234.
4.2.2. Maximum Sample ID
The maximumsampleid attribute contains the maximum relative sample identifier within this Project and
is used in the sample LIMS ID generation. It represents a count of how many sample LIMS IDs have
been created within this project.
Project
8
4.2.3. Status
One common derived attribute for project is their current status. A pending status would be characterized
by an empty opendate. Once a opendate value exists, the project is considered open until a closedate
exists.
4.3. Associated Data
Researcher is directly related to project in a 1:n relationship reflecting that a researcher can have multiple
projects at a time, but each project has one dedicated researcher as the owner.
SELECT
project.name,
researcher.firstname,
researcher.lastname
FROM
project,
researcher
WHERE
project.researcherid = researcher.researcherid
ORDER BY project.name
Samples are associated to projects in a n:1 relationship:
SELECT
project.name AS projectname,
sample.name AS samplename
FROM
project,
sample
WHERE
project.projectid = sample.projectid
ORDER BY project.name
Project
9
Figure 4.1. Project Associated Data
4.4. Examples
4.4.1. New Projects
The following query simply returns the project records for projects opened in the specified time.
SELECT
*
FROM
project
WHERE
project.opendate >= '2008-01-01'
AND project.opendate <= '2008-01-31'
ORDER BY project.name
4.4.2. Closed Projects
This query shows how to return closed projects as well as the associated researcher and laboratory
information and the total count of samples associated to the project.
SELECT
Project
10
project.name AS projectname,
project.closedate,
researcher.firstname, researcher.lastname,
lab.name AS labname,
COUNT(sample.sampleid) as samplecount
FROM
project,
researcher,
lab,
sample
WHERE
project.researcherid = researcher.researcherid
AND researcher.labid = lab.labid
AND project.projectid = sample.projectid
AND project.closedate >= '2008-01-01'
AND project.closedate <= '2008-01-31'
GROUP BY project.name, project.closedate, researcher.firstname, researcher.lastname,
lab.name
ORDER BY project.name
11
Chapter 5. Process
5.1. General
Process is a central piece of the BaseSpace Clarity LIMS data model. It represents any process, for
example the acquisition of data relating to a sample; a run of a specific analysis; a re-array of samples;
and many more. The different processes captured in the system are categorized in the processtype table.
5.2. Attributes
The main purpose of Process is to tie together other entities; hence many of its attributes relate to or
describe the attributes of other entities.
SELECT
processid, -- unique identifier
daterun, -- date the process was actually run (null before completed)
luid , -- LIMS ID
isprotocol, -- true if this is an entry to represent a group of
-- defaults, false otherwise
protocolnameused, -- the name of the group of defaults selected on the record
-- details milestone
programstarted, -- whether or not an external program was started
datastoreid, -- [deprecated]
isglobal, -- [deprecated]
ownerid, -- the principal ID of the user ('researcher') who created
-- the process
createddate,
lastmodifieddate,
lastmodifiedby,
installationid, -- the installation of the instrument involved
-- with the process
techid, -- the principal ID of the user who completed the step. If
-- the step was escalated, then the step technician will
-- be the escalation reviewer
typeid, -- the processtype of the process
stringparameterid, -- [deprecated]
fileparameterid, -- [deprecated]
protocolstepid, -- the protocol step this process was created under
workstatus, -- the status of the process (COMPLETE unless in progress)
reagentcategoryid, -- the group of labels selected when executing the process
signedbyid, -- the id of the principal ID of the user who created
-- the process
signeddate, -- the date the process was signed
nextstepslocked, -- if next steps are determined by a script and cannot be
-- changed manually
autocreatedprocessid -- for protocol steps configured to auto-start next steps
FROM
process;
Process
12
Processtype has many attributes that are used for application internal purposes, but also contains
displayname, that can be used to characterize the process instance.
SELECT
typeid,
displayname,
typename,
isenabled,
contextcode,
isvisible,
showinexplorer,
showinbuttonbar,
iconconstant,
outputcontextcode,
useprotocol,
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby,
behaviourname, -- application internal use only
style,
metadata, -- application internal use only
modulename, -- application internal use only
expertname,
canedit,
openpostprocess -- application internal use only
FROM
processtype
5.3. Associated Data
Principals is directly related to process in a 1:n relationship. This relationship represents the user that
entered the process in the system and therefore ran it. Each principal can have many processes associated.
Each process is associated to a processtype, which describes the basic nature of the process. A process
can also be associated with a protocolstep. Protocol steps are described further in Chapter 10, Workflow
Configuration.
SELECT
process.luid,
processtype.displayname,
principals.username
FROM process
JOIN processtype ON process.typeid = processtype.typeid
Process
13
JOIN principals ON process.techid = principals.principalid
JOIN installation ON process.installationid = installation.id
In addition each process can be associated to an installation, which in turn links to instrument and
software.
SELECT
process.luid,
processtype.displayname,
instrument.name AS instrumentname,
software.name AS softwarename
FROM process
JOIN processtype ON process.typeid = processtype.typeid
JOIN installation ON process.installationid = installation.id
JOIN instrument ON installation.instrumentid = instrument.instrumentid
JOIN software ON installation.softwareid = software.softwareid
Process
14
Figure 5.1. Process Associations
5.4. Examples
5.4.1. Process Runs
The following query simply returns a list of processes run in the specified time frame.
SELECT
processtype.displayname,
process.luid,
process.daterun
FROM
process JOIN processtype ON process.typeid = processtype.typeid
Process
15
WHERE
process.daterun >= '2008-01-01'
AND process.daterun <= '2008-01-31'
ORDER BY process.daterun
5.4.2. Processes Completed
The following query builds on the previous query but includes only processes actually completed.
SELECT
processtype.displayname,
process.luid,
process.daterun
FROM
process JOIN processtype ON process.typeid = processtype.typeid
WHERE
process.daterun >= '2008-01-01'
AND process.daterun <= '2008-01-31'
AND process.workstatus = 'COMPLETE'
ORDER BY process.daterun
5.4.3. Processtype Filtering
The following query returns a list of processes of a few specific types only.
SELECT
processtype.displayname,
process.daterun,
process.luid
FROM
process JOIN processtype ON process.typeid = processtype.typeid
WHERE
processtype.displayname in (
'Bioanalyzer QC (RNA) 4.0', 'NanoDrop QC (RNA) 4.0', 'Qubit QC (RNA) 4.0'
)
ORDER BY displayname, daterun
For a full list of available types simply return all rows of the processtype table.
5.4.4. Processes Run By A Specific User
The following query returns a list of processes that has been run by a specific user. This information is
stored in the researcher table, which can be joind via the principals table.
Process
16
SELECT
processtype.displayname,
process.daterun,
process.luid,
principals.username,
researcher.firstname,
researcher.lastname
FROM process
JOIN processtype ON process.typeid = processtype.typeid
JOIN principals ON process.techid = principals.principalid
JOIN researcher ON principals.researcherid = researcher.researcherid
WHERE username = 'admin'
5.4.5. List of Processes Run On A Specific Instrument and Software
Since each process run on a certain equipment is associated to the instrument and software a query like
the following would allow the user to find how much it gets facilitated.
SELECT
process.luid,
process.daterun,
processtype.displayname,
instrument.name AS instrumentname,
software.name AS softwarename
FROM process
JOIN processtype ON process.typeid = processtype.typeid
JOIN installation ON process.installationid = installation.id
JOIN instrument ON installation.instrumentid = instrument.instrumentid
JOIN software ON installation.softwareid = software.softwareid
WHERE software.name = 'Xcalibur'
AND instrument.name = 'GeneChip Scanner 3000'
5.4.6. Processes Associated To A Specific Project
The following query returns all processes associated to a specific project specified by its name. It uses
the indirect relationship between project and process.
SELECT
project.name,
processtype.displayname,
sample.name,
process.daterun
FROM
process,
processiotracker,
artifact,
artifact_sample_map,
sample,
Process
17
processtype,
project
WHERE
process.processid = processiotracker.processid
AND process.typeid = processtype.typeid
AND processiotracker.inputartifactid = artifact.artifactid
AND artifact.artifactid = artifact_sample_map.artifactid
AND artifact_sample_map.processid = sample.processid
AND sample.projectid = project.projectid
AND project.name = 'Serum Profiling-2D gel'
ORDER BY project.name, sample.name, daterun
18
Chapter 6. Sample
6.1. General
Samples are modelled within the database quite differently than they appear within the web UI. Within
the database, a sample represents a special form of a process. They are best viewed as the process of
receiving a sample; that is, the process of sample accessioning. When a sample is added to a workflow,
an analyte is created and it is the analyte that runs through the workflow. In the web UI, samples and
analytes are referred to as submitted samples and derived samples respectively. The web UI displays a
sample in terms of its related artifacts, and not as a process.
You cannot have an analyte without a sample to create it. Sample and analyte each have their own LIMS
ID, but they build upon each other.
A control is a special form of a sample where the sample's controltypeid is set. Controls are not associated
with any particular project (i.e. their projectid is null). See controltype for more information.
6.2. Attributes
Sample has the following attributes:
SELECT
sampleid,
name, -- Name of the sample
datereceived, -- Date the sample was received
datecompleted, -- Date the sample's project was closed
projectid, -- The project for which this sample was accessioned
processid, -- The corresponding process
controltypeid -- Optional control type
FROM sample;
6.3. Associated Data
Sample is related to process directly as well as to artifact indirectly via the artifact_sample_map.
Sample is related to controltype via controltypeid.
Sample
19
Figure 6.1. Sample Associated Data
6.4. Examples
6.4.1. Processes Run On A Specific Sample
The following query returns all process run on a specific sample given its name. There is no direct
relationship between process and sample, but an indirect relationship exists involving joining sample
to artifact_sample_map, artifact_sample_map to artifact, artifact to processiotracker, and
processiotracker to process. Once the relationship has been established between sample and process,
we can join process to processtype in order to harvest the displayname field.
When writing queries which are constrained by the sample.name field, it is important to remember
that this field is not necessarily unique. For example, depending upon naming conventions it is entirely
possible to have several samples within the same project having a shared sample name.
SELECT
processtype.displayname,
sample.name,
process.daterun
Sample
20
FROM
process,
processiotracker,
artifact,
artifact_sample_map,
sample,
processtype
WHERE
process.processid = processiotracker.processid
AND process.typeid = processtype.typeid
AND processiotracker.inputartifactid = artifact.artifactid
AND artifact.artifactid = artifact_sample_map.artifactid
AND artifact_sample_map.processid = sample.processid
AND sample.name = 'Serum-1'
ORDER BY name, daterun
6.4.2. Controls
The following query returns all controls. A sample is a control if its controltypeid field is not null.
SELECT
s.sampleid,
s.name,
ct.controltypeid,
ct.name,
ct.supplier,
ct.cataloguenumber,
ct.website,
ct.createddate,
ct.lastmodifieddate,
ct.lastmodifiedby,
ct.archived,
ct.singlestep
FROM sample s
JOIN controltype ct ON (ct.controltypeid = s.controltypeid);
21
Chapter 7. Artifact
7.1. General
Artifacts are a core abstraction in the BaseSpace Clarity LIMS data model and map to either result files
or analytes. Artifacts are the main participants in processes, which is the other core abstraction in the
system. A simplified description would be that any process input or output is an artifact.
7.2. Attributes
Artifact has the following attributes:
SELECT
artifactid,
luid,
name, -- name of the artifact
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby,
isworking,
isoriginal,
artifacttypeid, -- identifier of the artifact type of this artifact
currentstateid, -- identifier of the current artifact state
originalstateid -- original identifier of the artifact state when it was
-- first created
FROM
artifact
7.3. Associated Data
Artifact ancestry is determined by the intermediary table artifact_ancestor_map.
SELECT
artifactid, -- descendant artifact identifier
ancestorartifactid -- ancestor artifact identifier
FROM
artifact_ancestor_map
-- artifact_ancestor_map does not contain loops (cyclic relationships)
-- artifact_ancestor_map does not contain generic subartifacts ancestors/descendants
-- artifact_ancestor_map contains shared (compound) artifacts as descendants
Artifact
22
ReagentLabels can be applied to artifacts to (along with ancestry) support traceability for multiplexing
applications.
SELECT
labelid, -- pk of this reagent label
name, -- name of the reagent label
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby
FROM
reagentlabel
Artifacts and ReagentLabels are related by the intermediary table artifact_label_map.
SELECT
artifactid,
labelid
FROM
artifact_label_map
The following tables in the system are all related to artifact as specialized artifacts and linked directly
via artifactid:
• analyte
• resultfile
23
Chapter 8. Control
8.1. General
Control is a special form of Sample. See Sample for more information.
24
Chapter 9. Control Type
9.1. General
Control represents the controls that are used within a workflow. For example, molecular weight standards
or genomic DNA standards. Within the web UI, a control sample can be added to an ice bucket to be
used within a workflow.
9.2. Attributes
Control type has the following attributes:
SELECT
controltypeid,
name, -- The name of the control
supplier, -- The supplier's name
cataloguenumber, -- The supplier's catalogue number
website, -- The URL for the control on the supplier's website
createddate, -- UTC date the control type was created
lastmodifieddate, -- UTC date the control type was last modified
lastmodifiedby, -- ID of the principal that last modified the control type
archived, -- True/1 if the control has been archived
singlestep -- True/1 if the control is automatically removed after a single use
FROM controltype;
9.3. Associated Data
Control type has no direct relationships. Sample is related to control type via its controltypeid
field. Control types that are valid for a particular protocol step are related to control type via the
protocolstep_controltype_map table.
Control Type
25
Figure 9.1. Control Type Associated Data
9.4. Examples
9.4.1. Control Samples
Controls are special forms of a sample where their controltypeid field relates them to a specific control
type.
Control Type
26
SELECT
s.sampleid,
s.name,
ct.controltypeid,
ct.name,
ct.supplier,
ct.cataloguenumber,
ct.website,
ct.createddate,
ct.lastmodifieddate,
ct.lastmodifiedby,
ct.archived,
ct.singlestep
FROM sample s
JOIN controltype ct ON (ct.controltypeid = s.controltypeid);
9.4.2. Controls for a Protocol Step
Available control types are restricted by protocol step.
SELECT
ps.stepid,
ps.processtypeid, -- The corresponding process type
ps.protocolstepindex, -- The order of the step in the containing labprotocol
ps.protocolid, -- The lab protocol that contains the step
ps.qcprotocolstep, -- Whether the step is a QC step
ct.controltypeid,
ct.name, -- The name of the control
ct.supplier, -- The supplier's name
ct.cataloguenumber, -- The supplier's catalogue number
ct.website, -- The URL for the control on the supplier's website
ct.createddate, -- UTC date the control type was created
ct.lastmodifieddate, -- UTC date the control type was last modified
ct.lastmodifiedby, -- ID of the principal that last modified the control type
ct.archived, -- True/1 if the control has been archived
ct.singlestep -- True/1 if the control is automatically removed after a
-- single use
FROM protocolstep ps
JOIN protocolstep_controltype_map psct ON (psct.protocolstepid = ps.stepid)
JOIN controltype ct ON (ct.controltypeid = psct.controltypeid);
27
Chapter 10. Workflow Configuration
10.1. General
Workflow configuration extends the basic process type information to support the representation
of workflows, protocols and protocol steps that are currently configured in the LIMS. Workflow
configuration is spread across the labworkflow, workflowsection, labprotocol, processtype, and
protocolstep tables.
10.2. Attributes
The labprotocol table describes the available protocols:
SELECT
protocolid,
protocolname, -- the name of the protocol
qcprotocol, -- whether the protocol is standard or QC
protocolindex, -- determines the order protocols appear to the user
displayablemodifieddate, -- the last time this protocol was modified
displayablemodifiedby -- the user that modified the protocol
FROM
labprotocol
Pay attention to the name of the table: labprotocol (and not just protocol, which is the name of an
unrelated table).
The Protocolstep table represents the steps configured in a protocol, including the order they are
configured, and the nature of the step (via relationship to processtype).
SELECT
stepid,
processtypeid, -- the corresponding process type
protocolstepindex, -- the order of the step in the containing labprotocol
protocolid, -- the labprotocol that contains the step
qcprotocolstep -- whether the step is a QC step
FROM
protocolstep
Detailed configuration of individual protocol steps is determined by the stepconfiguration attribute,
which is a single JSON string representing several different aspects of step configuration. Values
set in the processtype.stepconfiguration can be used to control the configuration for all protocol
Workflow Configuration
28
steps with protocolstep.processtypeid equal to processtype.typeid. Values that are set in the
protocolstep.stepconfiguration but not in the processtype.stepconfiguration do not affect the
configuration of any other protocol steps.
SELECT
step.name as step_name, -- name of step
pt.displayname as processtype_name, -- name of processtype
-- postgres specific json function used here to access step details heading:
step.stepconfiguration::json#>>'{recordDetailsConfig,stepDetailsHeading}'
FROM
protocolstep step,
processtype pt
WHERE
pt.typeid = step.processtypeid
-- postgres specific, check where the step details heading is set, and is
-- determined by the processtype:
AND step.stepconfiguration::json#>>'{recordDetailsConfig,stepDetailsHeading}' != ''
AND pt.stepconfiguration::json#>>'{recordDetailsConfig,stepDetailsHeading}' != '';
A labprotocol can be part of multiple labworkflows. The Workflowsection table relates protocols to
worklows.
SELECT
sectionid,
workflowid, -- the workflow the section is part of
protocolid, -- the protocol the section corresponds to
sectionindex -- determines the position the section appears in the workflow
FROM
workflowsection
The Labworkflow table describes the basic properties for workflows, such as name and status.
SELECT
workflowid,
workflowname, -- the name of the workflow
workflowstatus -- the status of the workflow
-- (PENDING, ACTIVE, ARCHIVED)
FROM
labworkflow
Again, please note the name of the table: labworkflow (and not just workflow, which is a different,
unrelated table).
Workflow Configuration
29
10.3. Associated Data
The diagram below shows tables related to workflow configuration and individual step configuration.
Figure 10.1. Workflow Configuration Associated Data
10.4. Examples
10.4.1. Showing all workflows and their protocols
The following query returns a list of all workflows, including their state (pending, active, archived) and
protocols, and information on the last modification for each protocol.
SELECT
w.workflowname workflow,
w.workflowstatus status,
p.protocolname protocol,
p.displayablemodifieddate lastmodification,
u.username modifiedby
FROM labworkflow w
JOIN workflowsection ws ON ws.workflowid = w.workflowid
JOIN labprotocol p ON p.protocolid = ws.protocolid
LEFT JOIN principals u ON p.displayablemodifiedby = u.principalid
ORDER BY w.workflowid, ws.sectionindex
Workflow Configuration
30
10.4.2. Showing process stats for all active workflows
The following query returns a list of all workflows, protocols, and protocol steps and the aggregate
number of completed processes per step.
SELECT
w.workflowname as workflow,
p.protocolname as protocol,
pt.displayname as step,
count(pc.*) AS numberofprocesses
FROM labworkflow w
JOIN workflowsection ws ON ws.workflowid = w.workflowid
JOIN labprotocol p ON p.protocolid = ws.protocolid
JOIN protocolstep ps ON ps.protocolid = p.protocolid
JOIN processtype pt ON pt.typeid = ps.processtypeid
JOIN process pc ON pc.protocolstepid = ps.stepid
WHERE pc.workstatus = 'COMPLETE'
GROUP BY w.workflowid, w.workflowname, ws.sectionindex,
p.protocolname, ps.protocolstepindex,pt.displayname
ORDER BY w.workflowname,ws.sectionindex,ps.protocolstepindex
31
Chapter 11. Reagent Kits and Lots
11.1. General
Reagent kits form a part of the configuration and are stored in the reagentkit table. From reagent kits,
their specific reagent lots are created in the reagentlot table.
11.2. Attributes
The reagentkit table describes the available reagent kits:
SELECT
reagentkitid,
name,
supplier,
cataloguenumber,
website,
archived -- whether this kit has been archived and can no longer be used
FROM
reagentkit
The reagentlot table represents the individual lot for a reagent kit.
SELECT
reagentlotid,
name,
luid, -- the LIMS ID
status, -- can be one of PENDING, ACTIVE, ARCHIVED
lotnumber,
expirydate,
storagelocation,
notes,
reagentkitid -- the related kit the lot is for
FROM
reagentlot
Reagent Kits and Lots
32
11.3. Associated Data
Reagent kits can be configured to be used with protocol steps using the protocolstep_reagentkit_map
table.
Figure 11.1. Reagent Kit and Reagent Lot Associated Data
11.4. Examples
11.4.1. Showing all reagent kits and lots for protocol steps
The following query returns a list of all reagent kits and their related reagent lots for all protocol steps
that have been configured with them.
SELECT
pt.displayname protocolstepname,
kit.name reagentkitname,
lot.luid reagentlotlimsid,
lot.name reagentlotname
FROM
protocolstep step
JOIN processtype pt ON step.processtypeid = pt.typeid
JOIN protocolstep_reagentkit_map map ON step.stepid = map.stepid
JOIN reagentkit kit ON kit.reagentkitid = map.reagentkitid
JOIN reagentlot lot ON lot.reagentkitid = kit.reagentkitid
Reagent Kits and Lots
33
34
Chapter 12. User-Defined Field (UDF)
12.1. General
User-Defined Fields (UDFs), or Custom Fields in the BaseSpace Clarity LIMS UI, are a powerful part
of the data model that allow the users of the application to define arbitrary attributes for the collection of
custom data. These UDFs can be associated with a number of data entities in the system.
12.2. Attributes and Associated Data
User-Defined Fields can include various types of data as well as default values and validation rules
to control the values a user can save. These attributes are stored in the tables udf, udfvalidator,
udfvalidatorinstance and udfpreset.
Figure 12.1. User-Defined Fields Associated Data
The udf table stores general data about the configuration of the User-Defined Field such as the name of
the UDF and they type of data that can be stored. The following listing shows the fields in the udf table
and a short description for each one.
User-Defined Field (UDF)
35
SELECT
udfid, -- unique identifier
name, -- name for user visible reference
type, -- the datatype of the udf value
rowindex, -- index for storage row starting with zero
storagefield, -- name of the column name in the storage table in which
-- the value is stored
isvisible, -- determines visibility
showinlablink, -- determines visiility in lablink web interface
allownonpresetvalues, -- determine if values other than the defined presets
-- are allowed
firstpresetisdefaultvalue, -- determine if the first preset value acts as a
-- default value
attachtoclassid, -- link to classindex.classindexid
attachtosubtypeid, -- link to subtype of class linked to with attachtoclassid
showintables,
sequencenumber, -- sequence number for display
displayprecision, -- number of decimal places to use when displaying
-- numeric values
unitlabel, -- label text representing the unit for numeric UDFs
iseditable, -- if users can modify existing values
namespace, -- application internal used to ensure name uniqueness
-- for a specific entity the UDF is related to.
-- The value is the concatenation of the
-- following fields with a '-' in between
-- adjacent fields: name, attachtoclassid,
-- attachsubtypeid, udtid (-1 if it is null),
-- and internal data store identifier.
udtid, -- identifier of the associated user defined type (optional)
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby
FROM
udf
Note the type attribute. Each UDF can be of a specific type, and this type field defines the UDF's data-
type. The value for type can be one of the following:
JTextField
JTextArea
Numeric
Date
Boolean
List
HyperLinkText
The type defines how and where the value of the UDF is stored. See the section on decoding for more
details.
User-Defined Field (UDF)
36
udfpreset defines a default value or a list of predefined values in a many to one relationship to udf.
SELECT
presetid,
value ,
sequencenumber,
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby,
udfid
FROM
udfpreset
udfvalidator and udfvalidatorinstance define the validation characteristics for the User-Defined
Field. Validation can include making a UDF required or ensuring values are within a certain range.
SELECT
validatorid,
validatorclass,
fieldclass,
sequencenumber,
isdefault,
isvisible,
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby
FROM
validator
SELECT
validatorinstanceid,
xmlvalidationdef,
isvisible,
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby,
udfid,
validatorid
FROM
udfvalidatorinstance
User-Defined Field (UDF)
37
12.3. Value Storage
UDFs are defined using the tables, fields, and relationships described above. UDFs can be associated to
many different types of entities in the system, such as projects, processes, samples, and tasks. The type
of entity with which a UDF is associated will determine how the actual values for that UDF are stored.
A key concept is that the definition of a UDF is separate from the values for that UDF. For example,
suppose a UDF named “Freezer Location" is defined on "sample". The definition for “Freezer Location"
is stored once in the udf table, but values for that UDF are stored for each sample, with each value
referencing the one definition.
Depending on the type of entity to which the UDF is associated, the values stored in BaseSpace Clarity
LIMS are stored in one of several different tables. These tables are: artifactudfstorage for all User-
Defined Fields for artifacts; processudfstorage for processes; and entityudfstorage for all others
entities that can support UDFs, such as projects and tasks.
To maintain acceptable system performance, each row in the value storage tables can contain many UDF
values associated to a specific entity. The details about which column contains which UDF's value can
be derived from the UDF definition in the udf table. The field udf.storagefield has the name of the
storage table field that holds the value for a particular UDF.
If there is a large number of UDFs defined for an entity, more than one storage row may be required
to hold all the values. The field udf.rowindex has the value of the *udfstorage.rowindex to indicate
which row in the series of storage rows for an entity contains the value for a particular UDF.
The storage table that is used for the values of a UDF will depend on the class of the entity for which the
UDF is defined. Classes of entities can be found in the classindex table. The UDF is related to the entity
class by the fields udf.attachtoclassid and classindex.classindexid. The classindex.tablename
reveals the actual table in which an entity is stored. Examining the relationships of this table reveals if
an entity is an artifact, process, or another type of entity. The type of entity will determine the storage
table used for UDF values.
It is possible to look for references to other tables in terms of id field. The reference keys for the different
storage tables are:
artifactid for artifactudfstorage
processid for processudfstorage
attachtoclassid and attachtoid for entityudfstorage
By knowing which storage table to use for the entity you are interested in, and by knowing the values
of udf.storagefield and udf.rowindex, you can determine where to find the value for a UDF. The
following query does this for all UDFs defined in your system:
User-Defined Field (UDF)
38
SELECT
udf.name,
udf.type,
udf.storagefield,
udf.rowindex,
classindex.classname,
classindex.tablename
FROM udf JOIN classindex
ON udf.attachtoclassid = classindex.classindexid
An example of this is a UDF associated to an Analyte stored in the analyte table. In this example, the
table contains an artifactid linking to the artifact table, which indicates that the UDF values are
stored in the artifactudfstorage table.
When working with processes, an example of this is Configured Processes stored in the
configuredprocess table or indexing processes stored in the addmultiplereagents table. Both tables
contain a processid so UDF values for these entities are stored in the processudfstorage table.
All other entities in the system that do not point to one of the mentioned id fields use entityudfstorage.
For example, experiments are stored in the experiment table and projects are stored in the project table.
12.4. Decoding the UDF values for different UDF types
Different types of UDFs save their values in different fields in the storage tables. The different types will
also use different formats for the data in these fields. Examine any one of the UDF storage tables, such
as artifactudfstorage, and you will see the set of ten text* fields and fifteen numeric* fields that can
be used to store UDF values. These are the fields that can be named in udf.storagefield for a UDF.
text0
text1
text2
text3
text4
text5
text6
text7
text8
text9
numeric0
numeric1
numeric2
numeric3
numeric4
numeric5
numeric6
numeric7
User-Defined Field (UDF)
39
numeric8
numeric9
numeric10
numeric11
numeric12
numeric13
numeric14
JTextField and JTextArea are simple text UDF types and their values are stored as they are entered in
the LIMS. Similarly, HyperLinkText contains links and LocalProgram contains a path to a local program
on the server. All of these are stored in text* fields.
The Date UDF type also uses text* storage fields. Any query will return a simple text data type rather than
a date data type and adheres to the ISO 8601 format "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'". For example,
the 15th of March 2008 at 1:25pm looks like "2008-03-15T13:25:00.000Z".
Numeric UDF values are stored in numeric* fields using a numeric format. When formatting a numeric
UDF, the udf.displayprecision should be taken into account in order to display an appropriate number
of decimal places.
Boolean UDF values are also stored in numeric fields. A zero (0) value represents false and a one (1)
value represents true.
12.5. Examples
12.5.1. List of all UDFs defined in the system
In order to be able to query UDF values associated with the various entities in the system, a list of all
defined UDFs can be helpful. For example, the following query returns some basic information about a
UDF, as well as the optionally associated classindex. The classindex entries, as well as the UDF definition
fields, will help with the retrieval of the values stored with a UDF.
SELECT
udf.name AS udfname,
udf.storagefield,
udf.allownonpresetvalues,
udf.firstpresetisdefaultvalue,
udf.attachtoclassid,
udf.attachtosubtypeid,
classindex.classname,
classindex.tablename
FROM udf
LEFT OUTER JOIN classindex ON udf.attachtoclassid = classindex.classindexid
WHERE udtid IS NULL
User-Defined Field (UDF)
40
12.5.2. Result File UDF Names and Values
The system may be configured to have UDFs defined to represent extra attributes of result files. This
example shows how to query the database for all result file UDF name-value pairs.
select a.luid as "LIMSID", udf.name as "Name",
case
when udf.storagefield = 'text0' and udf.type = 'JTextField' then aus.text0
when udf.storagefield = 'text0' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text0, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text1' and udf.type = 'JTextField' then aus.text1
when udf.storagefield = 'text1' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text1, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text2' and udf.type = 'JTextField' then aus.text2
when udf.storagefield = 'text2' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text2, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text3' and udf.type = 'JTextField' then aus.text3
when udf.storagefield = 'text3' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text3, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text4' and udf.type = 'JTextField' then aus.text4
when udf.storagefield = 'text4' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text4, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text5' and udf.type = 'JTextField' then aus.text5
when udf.storagefield = 'text5' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text5, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text6' and udf.type = 'JTextField' then aus.text6
when udf.storagefield = 'text6' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text6, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text7' and udf.type = 'JTextField' then aus.text7
when udf.storagefield = 'text7' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text7, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text8' and udf.type = 'JTextField' then aus.text8
when udf.storagefield = 'text8' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text8, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text9' and udf.type = 'JTextField' then aus.text9
when udf.storagefield = 'text9' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text9, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'numeric0' then '' || aus.numeric0
when udf.storagefield = 'numeric1' then '' || aus.numeric1
when udf.storagefield = 'numeric2' then '' || aus.numeric2
when udf.storagefield = 'numeric3' then '' || aus.numeric3
when udf.storagefield = 'numeric4' then '' || aus.numeric4
when udf.storagefield = 'numeric5' then '' || aus.numeric5
when udf.storagefield = 'numeric6' then '' || aus.numeric6
when udf.storagefield = 'numeric7' then '' || aus.numeric7
when udf.storagefield = 'numeric8' then '' || aus.numeric8
when udf.storagefield = 'numeric9' then '' || aus.numeric9
when udf.storagefield = 'numeric10' then '' || aus.numeric10
when udf.storagefield = 'numeric11' then '' || aus.numeric11
when udf.storagefield = 'numeric12' then '' || aus.numeric12
when udf.storagefield = 'numeric13' then '' || aus.numeric13
User-Defined Field (UDF)
41
when udf.storagefield = 'numeric14' then '' || aus.numeric14
end as "Value", udf.isvisible as "Visible"
from udf
join classindex ci on udf.attachtoclassid = ci.classindexid and ci.classname = 'ResultFile'
join artifactudfstorage aus on udf.rowindex = aus.rowindex
join artifact a on aus.artifactid = a.artifactid
join resultfile rf on rf.artifactid = a.artifactid
where udf.udtid is null
order by a.luid, udf.sequencenumber;
12.5.3. Project UDF Names and Values
Projects will often need to have UDFs defined on them to represent a variety of information. This example
shows how to query the database for all UDF name-value pairs for projects. If you only want to see UDFs
for a particular project, you can add another clause to the query to match an attribute of that project, such
as project.projectid or project.name.
select p.name as "Project", udf.name as "Name",
case
when udf.storagefield = 'text0' and udf.type = 'JTextField' then eus.text0
when udf.storagefield = 'text0' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text0, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text1' and udf.type = 'JTextField' then eus.text1
when udf.storagefield = 'text1' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text1, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text2' and udf.type = 'JTextField' then eus.text2
when udf.storagefield = 'text2' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text2, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text3' and udf.type = 'JTextField' then eus.text3
when udf.storagefield = 'text3' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text3, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text4' and udf.type = 'JTextField' then eus.text4
when udf.storagefield = 'text4' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text4, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text5' and udf.type = 'JTextField' then eus.text5
when udf.storagefield = 'text5' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text5, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text6' and udf.type = 'JTextField' then eus.text6
when udf.storagefield = 'text6' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text6, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text7' and udf.type = 'JTextField' then eus.text7
when udf.storagefield = 'text7' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text7, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text8' and udf.type = 'JTextField' then eus.text8
when udf.storagefield = 'text8' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text8, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text9' and udf.type = 'JTextField' then eus.text9
when udf.storagefield = 'text9' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text9, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'numeric0' then '' || eus.numeric0
User-Defined Field (UDF)
42
when udf.storagefield = 'numeric1' then '' || eus.numeric1
when udf.storagefield = 'numeric2' then '' || eus.numeric2
when udf.storagefield = 'numeric3' then '' || eus.numeric3
when udf.storagefield = 'numeric4' then '' || eus.numeric4
when udf.storagefield = 'numeric5' then '' || eus.numeric5
when udf.storagefield = 'numeric6' then '' || eus.numeric6
when udf.storagefield = 'numeric7' then '' || eus.numeric7
when udf.storagefield = 'numeric8' then '' || eus.numeric8
when udf.storagefield = 'numeric9' then '' || eus.numeric9
when udf.storagefield = 'numeric10' then '' || eus.numeric10
when udf.storagefield = 'numeric11' then '' || eus.numeric11
when udf.storagefield = 'numeric12' then '' || eus.numeric12
when udf.storagefield = 'numeric13' then '' || eus.numeric13
when udf.storagefield = 'numeric14' then '' || eus.numeric14
end as "Value", udf.isvisible as "Visible"
from udf
join classindex ci on udf.attachtoclassid = ci.classindexid and ci.classname = 'Project'
join entityudfstorage eus on udf.rowindex = eus.rowindex
join project p on eus.attachtoid = p.projectid
where udf.udtid is null
order by p.projectid, udf.sequencenumber;
12.5.4. Process UDF Names and Values
Processes will often be distinguished from each other by the UDFs that have been defined. Knowing how
to retrieve this UDF information for a particular process type is essential for reporting. This example
shows how to query the database for all UDF name-value pairs for a process type. If you only want to
see UDFs for a particular process run, you can add another clause to the query to match an attribute of
that process, such as process.luid or process.rundate. To query the database for a different process
type, change the value used in the clause for processtype.displayname.
SELECT p.luid AS "LIMSID", p.daterun, udf.name AS "Name",
CASE
WHEN udf.storagefield = 'text0' AND udf.type = 'JTextField' THEN pus.text0
WHEN udf.storagefield = 'text0' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text0, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text1' AND udf.type = 'JTextField' THEN pus.text1
WHEN udf.storagefield = 'text1' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text1, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text2' AND udf.type = 'JTextField' THEN pus.text2
WHEN udf.storagefield = 'text2' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text2, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text3' AND udf.type = 'JTextField' THEN pus.text3
WHEN udf.storagefield = 'text3' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text3, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text4' AND udf.type = 'JTextField' THEN pus.text4
WHEN udf.storagefield = 'text4' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text4, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text5' AND udf.type = 'JTextField' THEN pus.text5
User-Defined Field (UDF)
43
WHEN udf.storagefield = 'text5' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text5, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text6' AND udf.type = 'JTextField' THEN pus.text6
WHEN udf.storagefield = 'text6' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text6, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text7' AND udf.type = 'JTextField' THEN pus.text7
WHEN udf.storagefield = 'text7' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text7, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text8' AND udf.type = 'JTextField' THEN pus.text8
WHEN udf.storagefield = 'text8' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text8, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text9' AND udf.type = 'JTextField' THEN pus.text9
WHEN udf.storagefield = 'text9' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text9, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'numeric0' THEN '' || pus.numeric0
WHEN udf.storagefield = 'numeric1' THEN '' || pus.numeric1
WHEN udf.storagefield = 'numeric2' THEN '' || pus.numeric2
WHEN udf.storagefield = 'numeric3' THEN '' || pus.numeric3
WHEN udf.storagefield = 'numeric4' THEN '' || pus.numeric4
WHEN udf.storagefield = 'numeric5' THEN '' || pus.numeric5
WHEN udf.storagefield = 'numeric6' THEN '' || pus.numeric6
WHEN udf.storagefield = 'numeric7' THEN '' || pus.numeric7
WHEN udf.storagefield = 'numeric8' THEN '' || pus.numeric8
WHEN udf.storagefield = 'numeric9' THEN '' || pus.numeric9
WHEN udf.storagefield = 'numeric10' THEN '' || pus.numeric10
WHEN udf.storagefield = 'numeric11' THEN '' || pus.numeric11
WHEN udf.storagefield = 'numeric12' THEN '' || pus.numeric12
WHEN udf.storagefield = 'numeric13' THEN '' || pus.numeric13
WHEN udf.storagefield = 'numeric14' THEN '' || pus.numeric14
end AS "Value", udf.isvisible AS "Visible"
FROM udf JOIN processtype pt ON udf.attachtosubtypeid = pt.typeid AND pt.displayname = 'Copy'
JOIN process p ON pt.typeid = p.typeid
JOIN processudfstorage pus ON udf.rowindex = pus.rowindex AND p.processid = pus.processid
WHERE udf.udtid IS NULL
ORDER BY p.daterun, udf.sequencenumber;
12.5.5. Process Output UDF Names and Values
There may be many UDFs defined for a process output type, such as analyte. Depending on the process
type configuration, some of those UDFs may be applicable to the process outputs. This example shows
how to query the database for all UDF name-value pairs for the outputs of a process type. If you only want
to see UDFs for a particular process run, you can add another clause to the query to match an attribute of
that process, such as, process.luid or process.rundate. To query the database for a different process
type, change the value used in the clause for processtype.displayname.
select p.luid AS "PROCESSLIMSID", a.luid as "OUTPUTLIMSID", udf.name as "Name",
case
when udf.storagefield = 'text0' and udf.type = 'JTextField' then aus.text0
when udf.storagefield = 'text0' and udf.type = 'Date' then
User-Defined Field (UDF)
44
TO_CHAR(TO_TIMESTAMP(aus.text0, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text1' and udf.type = 'JTextField' then aus.text1
when udf.storagefield = 'text1' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text1, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text2' and udf.type = 'JTextField' then aus.text2
when udf.storagefield = 'text2' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text2, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text3' and udf.type = 'JTextField' then aus.text3
when udf.storagefield = 'text3' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text3, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text4' and udf.type = 'JTextField' then aus.text4
when udf.storagefield = 'text4' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text4, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text5' and udf.type = 'JTextField' then aus.text5
when udf.storagefield = 'text5' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text5, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text6' and udf.type = 'JTextField' then aus.text6
when udf.storagefield = 'text6' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text6, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text7' and udf.type = 'JTextField' then aus.text7
when udf.storagefield = 'text7' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text7, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text8' and udf.type = 'JTextField' then aus.text8
when udf.storagefield = 'text8' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text8, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text9' and udf.type = 'JTextField' then aus.text9
when udf.storagefield = 'text9' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(aus.text9, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'numeric0' then '' || aus.numeric0
when udf.storagefield = 'numeric1' then '' || aus.numeric1
when udf.storagefield = 'numeric2' then '' || aus.numeric2
when udf.storagefield = 'numeric3' then '' || aus.numeric3
when udf.storagefield = 'numeric4' then '' || aus.numeric4
when udf.storagefield = 'numeric5' then '' || aus.numeric5
when udf.storagefield = 'numeric6' then '' || aus.numeric6
when udf.storagefield = 'numeric7' then '' || aus.numeric7
when udf.storagefield = 'numeric8' then '' || aus.numeric8
when udf.storagefield = 'numeric9' then '' || aus.numeric9
when udf.storagefield = 'numeric10' then '' || aus.numeric10
when udf.storagefield = 'numeric11' then '' || aus.numeric11
when udf.storagefield = 'numeric12' then '' || aus.numeric12
when udf.storagefield = 'numeric13' then '' || aus.numeric13
when udf.storagefield = 'numeric14' then '' || aus.numeric14
end as "Value", udf.isvisible as "Visible"
from processtype pt
JOIN process p ON pt.typeid = p.typeid AND pt.displayname = 'Copy'
JOIN processiotracker piot ON p.processid = piot.processid
JOIN outputmapping om ON piot.trackerid = om.trackerid
JOIN artifact a ON om.outputartifactid = a.artifactid
JOIN artifacttype at ON a.artifacttypeid = at.typeid
JOIN classindex ci ON at.classname LIKE '%' || ci.classname || '%'
JOIN udf ON ci.classindexid = udf.attachtoclassid
JOIN artifactudfstorage aus ON a.artifactid = aus.artifactid AND udf.rowindex = aus.rowindex
WHERE udf.udtid IS NULL
ORDER BY p.luid, a.luid, udf.sequencenumber;
User-Defined Field (UDF)
45
12.5.6. List of all UDF preset values for a specific UDF
UDFs can be configured to accept values from a list of presets. Understanding the available values for
a UDF with presets is helpful. This query returns a list of all UDFs and their optionally defined preset
values in the correct sequence.
SELECT
udf.udfid,
udf.name,
udf.type,
udfpreset.value
FROM udf
LEFT OUTER JOIN udfpreset ON udf.udfid = udfpreset.udfid
ORDER BY udf.udfid, udfpreset.sequencenumber
46
Chapter 13. User-Defined Type (UDT)
13.1. General
User-Defined Types (UDTs), or Custom Types in the BaseSpace Clarity LIMS UI, are a powerful part
of the Clarity LIMS data model that allow the users of the application to define arbitrary sets of User-
Defined Fields (UDFs or Custom Fields). Like UDFs, UDTs can be associated to a number of entities in
the system and act as a container for multiple UDFs, with specific UDF values per target instance. UDFs
that are contained under a particular UDT will not show up unless that UDT is selected. Only one UDT
can be selected at a time for a specific instance of a target entity.
For example, if samples are configured with two UDTs, one called "Tissue" and one called "Blood", a
sample cannot exist that has a type of both "Tissue" and "Blood". When "Tissue" is selected, only UDFs
defined under the "Tissue" UDT will be shown and all "Blood" UDFs will be hidden. Similarly, when
"Blood" is selected, only UDFs defined under the "Blood" UDT will be shown and all "Tissue" UDFs
will be hidden.
A UDT can be made mandatory for a target entity. A Mandatory UDT enforces that one of the UDTs
available for a target entity must be selected. UDT Mandatory Flags have the following attributes.
SELECT
targettypeid,
attachtoclassid,
attachtosubtypeid,
udtisrequired,
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby
FROM
udf_udt_targettype
If a record exists with true value for udtisrequired, then the UDT is required for the target entity type. If
there is no record or the udtisrequired value is false, then the UDT is not required.
13.2. Attributes
UDTs have the following attributes.
SELECT
udtid,
User-Defined Type (UDT)
47
name,
attachtoclassid,
attachtosubtypeid,
isvisible,
showinlablink,
sequencenumber,
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby
FROM
udt
A UDT is only defined as a holder for UDFs, and as such does not have any instance data or value. Only
the name attribute is displayed in the LIMS. Only the UDFs associated with the UDT have specific values.
13.3. Associated UDFs
As described above, a UDT aggregates multiple UDFs. The following query can be used to obtain an
overview of the UDFs for each UDT, as well as the type of entity to which they are attached.
SELECT
udt.name AS udtname,
udf.name AS udfname,
udf.type,
classindex.classname
FROM
udt JOIN udf ON udt.udtid = udf.udtid
JOIN classindex ON udt.attachtoclassid = classindex.classindexid
ORDER BY udt.udtid, udf.sequencenumber
The udtid field also exists in the various UDT storage tables. Use the reference from *udfstorage.udtid
to udt.udtid to get UDF values for a specific UDT instance.
13.4. Examples
13.4.1. Project UDT and UDF Names and Values
This example shows how to query the database for all UDT and UDF name-value pairs for projects. If
you only want to see UDTs and UDFs for a particular project, you can add another clause to the query
to match an attribute of that project, such as project.projectid or project.name.
select p.name as "Project", udt.name as "UDTNAME", udf.name as "UDFNAME",
User-Defined Type (UDT)
48
case
when udf.storagefield = 'text0' and udf.type = 'JTextField' then eus.text0
when udf.storagefield = 'text0' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text0, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text1' and udf.type = 'JTextField' then eus.text1
when udf.storagefield = 'text1' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text1, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text2' and udf.type = 'JTextField' then eus.text2
when udf.storagefield = 'text2' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text2, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text3' and udf.type = 'JTextField' then eus.text3
when udf.storagefield = 'text3' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text3, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text4' and udf.type = 'JTextField' then eus.text4
when udf.storagefield = 'text4' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text4, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text5' and udf.type = 'JTextField' then eus.text5
when udf.storagefield = 'text5' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text5, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text6' and udf.type = 'JTextField' then eus.text6
when udf.storagefield = 'text6' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text6, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text7' and udf.type = 'JTextField' then eus.text7
when udf.storagefield = 'text7' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text7, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text8' and udf.type = 'JTextField' then eus.text8
when udf.storagefield = 'text8' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text8, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'text9' and udf.type = 'JTextField' then eus.text9
when udf.storagefield = 'text9' and udf.type = 'Date' then
TO_CHAR(TO_TIMESTAMP(eus.text9, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
when udf.storagefield = 'numeric0' then '' || eus.numeric0
when udf.storagefield = 'numeric1' then '' || eus.numeric1
when udf.storagefield = 'numeric2' then '' || eus.numeric2
when udf.storagefield = 'numeric3' then '' || eus.numeric3
when udf.storagefield = 'numeric4' then '' || eus.numeric4
when udf.storagefield = 'numeric5' then '' || eus.numeric5
when udf.storagefield = 'numeric6' then '' || eus.numeric6
when udf.storagefield = 'numeric7' then '' || eus.numeric7
when udf.storagefield = 'numeric8' then '' || eus.numeric8
when udf.storagefield = 'numeric9' then '' || eus.numeric9
when udf.storagefield = 'numeric10' then '' || eus.numeric10
when udf.storagefield = 'numeric11' then '' || eus.numeric11
when udf.storagefield = 'numeric12' then '' || eus.numeric12
when udf.storagefield = 'numeric13' then '' || eus.numeric13
when udf.storagefield = 'numeric14' then '' || eus.numeric14
end as "Value", udf.isvisible as "Visible"
from udf
join classindex ci on udf.attachtoclassid = ci.classindexid and ci.classname = 'Project'
join entityudfstorage eus on udf.rowindex = eus.rowindex
join project p on eus.attachtoid = p.projectid
left join udt on udf.udtid = udt.udtid
order by p.projectid, udt.udtid, udf.sequencenumber;
User-Defined Type (UDT)
49
13.4.2. Process UDT and UDF Names and Values
This example shows how to query the database for all UDT and UDF name-value pairs for a process
type. If you only want to see UDTs and UDFs for a particular process run, you can add another clause to
the query to match an attribute of that process, such as process.luid or process.rundate. To query the
database for a different process type, change the value used in the clause for processtype.displayname.
SELECT p.luid AS "LIMSID", p.daterun, udt.name AS "UDTNAME", udf.name AS "UDFNAME",
CASE
WHEN udf.storagefield = 'text0' AND udf.type = 'JTextField' THEN pus.text0
WHEN udf.storagefield = 'text0' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text0, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text1' AND udf.type = 'JTextField' THEN pus.text1
WHEN udf.storagefield = 'text1' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text1, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text2' AND udf.type = 'JTextField' THEN pus.text2
WHEN udf.storagefield = 'text2' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text2, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text3' AND udf.type = 'JTextField' THEN pus.text3
WHEN udf.storagefield = 'text3' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text3, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text4' AND udf.type = 'JTextField' THEN pus.text4
WHEN udf.storagefield = 'text4' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text4, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text5' AND udf.type = 'JTextField' THEN pus.text5
WHEN udf.storagefield = 'text5' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text5, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text6' AND udf.type = 'JTextField' THEN pus.text6
WHEN udf.storagefield = 'text6' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text6, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text7' AND udf.type = 'JTextField' THEN pus.text7
WHEN udf.storagefield = 'text7' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text7, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text8' AND udf.type = 'JTextField' THEN pus.text8
WHEN udf.storagefield = 'text8' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text8, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'text9' AND udf.type = 'JTextField' THEN pus.text9
WHEN udf.storagefield = 'text9' AND udf.type = 'Date' THEN
TO_CHAR(TO_TIMESTAMP(pus.text9, 'YYYY-MM-DD' ), 'YYYY-MM-DD')
WHEN udf.storagefield = 'numeric0' THEN '' || pus.numeric0
WHEN udf.storagefield = 'numeric1' THEN '' || pus.numeric1
WHEN udf.storagefield = 'numeric2' THEN '' || pus.numeric2
WHEN udf.storagefield = 'numeric3' THEN '' || pus.numeric3
WHEN udf.storagefield = 'numeric4' THEN '' || pus.numeric4
WHEN udf.storagefield = 'numeric5' THEN '' || pus.numeric5
WHEN udf.storagefield = 'numeric6' THEN '' || pus.numeric6
WHEN udf.storagefield = 'numeric7' THEN '' || pus.numeric7
WHEN udf.storagefield = 'numeric8' THEN '' || pus.numeric8
WHEN udf.storagefield = 'numeric9' THEN '' || pus.numeric9
WHEN udf.storagefield = 'numeric10' THEN '' || pus.numeric10
WHEN udf.storagefield = 'numeric11' THEN '' || pus.numeric11
WHEN udf.storagefield = 'numeric12' THEN '' || pus.numeric12
User-Defined Type (UDT)
50
WHEN udf.storagefield = 'numeric13' THEN '' || pus.numeric13
WHEN udf.storagefield = 'numeric14' THEN '' || pus.numeric14
end AS "Value", udf.isvisible AS "Visible"
FROM udf JOIN processtype pt ON udf.attachtosubtypeid = pt.typeid AND pt.displayname = 'Copy'
JOIN process p ON pt.typeid = p.typeid
JOIN processudfstorage pus ON udf.rowindex = pus.rowindex AND p.processid = pus.processid
LEFT JOIN udt ON udf.udtid = udt.udtid
ORDER BY p.daterun, udt.udtid, udf.sequencenumber;
51
Chapter 14. Glsfile
14.1. General
A glsfile is used to represent a file of any number of different file types (e.g. dat, xml, pdf, csv) used
by the system to represent raw input data, intermediate results, output data, reports, etc.
14.2. Attributes
Glsfile has the following attributes:
SELECT
fileid, -- internal identifier
server, -- name of the file server, used to look up configuration details
-- about the server from the platform properties file and produce
-- a base URI for content stored on that server
contentUri, -- a relative URI to the file content. This URI will be a relative
-- URI to the base URI produced for the configuration settings
-- for the server
luid, -- LIMS identifier
originallocation, -- original (absolute) location of the file on a client system
ispublished, -- [deprecated] boolean for whether file is published to LabLink
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby,
attachtoid, -- references the pk of the attached entity
attachtoclassid, -- references the classindex.classindexid for the attached entity to
-- discriminate the entity type
istemporary -- boolean that indicates if the file is temporary
FROM
glsfile
14.2.1. File Server Name
The server attribute contains the name of the file server, which is used to look up configuration details
about the server from the platform properties file and produce a base URI for content stored on that server.
14.2.2. File URI
The contentUri attribute contains a relative URI to the file content. This URI will be a relative URI to
the base URI produced for the configuration settings for the server.
Glsfile
52
14.2.3. Original Location
The originallocation attribute contains the absolute path and original filename of the file from a client
system.
14.2.4. Is Published [deprecated]
The ispublished attribute contains 'true' if the file is published to LabLink, or 'false' otherwise.
14.2.5. Is Temporary
The istemporary attribute contains 'true' if the file is temporary. Temporary files do not have Attach To
ID or Class ID values, as they have not yet been associated with an entity in the system. When association
does occur, the istemporary attribute is set to 'false' and Attach To ID and Class ID values are set.
Temporary files are periodically cleaned up by the application.
14.2.6. Attach To ID / Class ID
This is discussed in the 'Concepts' chapter.
14.3. Associated Data
A glsfile is associated with exactly one other entity of arbitrary type (e.g. project, process, etc.). This
relationship is usually 1:n reflecting that, for example, a project can involve multiple files, but each file
is associated with only one (project) entity. The exceptions that use a 1:1 relationship with glsfile are
processparameter, capturedfile, resultfile.
The following query displays all files, and the type and id of the entity attached.
SELECT
glsfile.luid AS file_luid,
glsfile.contentUri,
glsfile.server,
classindex.tablename AS attachtoentity_type,
glsfile.attachtoid AS attachtoentity_id
FROM
glsfile
JOIN
classindex ON glsfile.attachtoclassid = classindex.classindexid
ORDER BY
glsfile.fileid
Glsfile
53
14.4. Examples
14.4.1. New Files
The following query simply returns the glsfile records for files modified in the specified time.
SELECT
*
FROM
glsfile
WHERE
glsfile.lastmodifieddate >= '2008-01-01'
ORDER BY
glsfile.lastmodifieddate
14.4.2. Project Files
The following query finds all files that are associated directly with a project.
SELECT
glsfile.luid AS file_luid,
glsfile.contentUri,
glsfile.server,
project.luid AS project_luid
FROM glsfile
JOIN project ON glsfile.attachtoid = project.projectid
JOIN classindex ON glsfile.attachtoclassid = classindex.classindexid
WHERE
classindex.tablename='project'
ORDER BY
project.luid
54
Chapter 15. Software, Instrument andmore
15.1. General
When some process interacts with an external system including an instrument with some associated
software, the respective information is kept in the instrument, installation, software and vendor
associated tables and linked to the processtype.
15.2. Attributes
The following diagram documents the relationships within the equipment related tables. The
software_proctype table provides the link to processtype and with it to the rest of the system.
Figure 15.1. Equipment related tables and their relationships
Installation represents a particular instrument in the lab along with the software installed on it.
SELECT
Software, Instrument and more
55
id, -- Internal unique identifier
isvisible,
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby,
instrumentid, -- Identifier of associated Instrument
softwareid -- Identifier of associated Software
FROM
installation
An Instrument in the lab. Paired with software in an installation.
SELECT
instrumentid, -- Internal unique identifier
name, -- Name of the instrument
isvisible,
luid,
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby,
typeid -- Identifier of associated instrument type
FROM
instrument
itype a type of instrument.
SELECT
typeid, -- Internal unique identifier
name, -- Name of the type of instrument
isvisible,
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby,
vendorid -- Identifier of the associated Vendor of this instrument type
FROM
itype
Software that can be paired with an instrument to create an installation.
SELECT
softwareid, -- Internal unique identifier
name, -- Name of the software
Software, Instrument and more
56
isvisible,
version, -- Version of the software
issupported, -- Legacy flag for software types the operations interface parsed or
-- generated driver files for.
resulturl, -- Legacy operations interface specific URL for opening web result
-- pages for Protein Search Result Files.
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby,
filetypedriverid, -- [deprecated] Identifier of associated driver file type
filetypeoutputid, -- [deprecated] Identifier of associated output file type
vendorid -- Identifier of associated vendor
FROM
software
The valid pairings between software and instruments of a particular itype.
SELECT
softwareid,
instrumenttypeid
FROM
software_instrtype
vendor manufacturer of itype and software.
SELECT
vendorid, -- Internal Unique Identifier
name, -- Name of the the software or instrument vendor
isvisible,
ownerid,
createddate,
lastmodifieddate,
lastmodifiedby
FROM
vendor
The valid pairings between software and processtype.
SELECT
softwareid,
processtypeid
FROM
software_proctype
57
Chapter 16. UDF-Related Views
16.1. General
Data pertaining to User Defined Field (UDF) values for various classes of UDTs and entities is aggregated
into 4 database views which abstract details of the underlying database schema and simplify querying
and reporting.
16.2. ViewsFour UDF views, outlined in the table below, correspond to four classes of entities.
Table 16.1. Summary of the UDF Views
Entity Class Database View Name
Samples sample_udf_view
Artifacts
(artifact, analyte, resultfile )
artifact_udf_view
Processes
(process, configuredprocess, addmultiplereagents,
transferprocess)
process_udf_view
Other Entities
(e.g. project, clientresearcher, etc.)
entity_udf_view
16.3. Attributes
The sample_udf_view view provides data to link samples with associated UDF values.
SELECT
sampleid, -- identifies the sample the User Defined Field is associated with
udtname, -- name of the User Defined Type for the User Defined Field
udfid, -- id of the User Defined Field
udfname, -- name of the User Defined Field
udftype, -- data type of the User Defined Field
udfvalue, -- value of the User Defined Field
udfunitlabel -- units label for the User Defined Field (for configured numeric-type
-- UDFs only, null otherwise)
FROM
UDF-Related Views
58
sample_udf_view
The artifact_udf_view view provides data to link the different classes of artifacts with associated UDF
values.
SELECT
artifactid, -- identifies the artifact the User Defined Field is associated with
udtname, -- name of the User Defined Type for the User Defined Field
udfid, -- id of the User Defined Field
udfname, -- name of the User Defined Field
udftype, -- data type of the User Defined Field
udfvalue, -- value of the User Defined Field
udfunitlabel -- units label for the User Defined Field (for configured numeric-type
-- UDFs only, null otherwise)
FROM
artifact_udf_view
The process_udf_view view provides data to link various classes of processes with associated UDF
values.
SELECT
processid, -- identifies the process the User Defined Field is associated with
typeid, -- identifies the type of the process the User Defined Field is
-- associated with
udtname, -- name of the User Defined Type for the User Defined Field
udfid, -- id of the User Defined Field
udfname, -- name of the User Defined Field
udftype, -- data type of the User Defined Field
udfvalue, -- value of the User Defined Field
udfunitlabel -- units label for the User Defined Field (for configured numeric-type
-- UDFs only, null otherwise)
FROM
process_udf_view
The entity_udf_view view provides data to link other entity types with associated UDF values.
SELECT
attachtoid, -- identifies the entity the User Defined Field is associated with
attachtoclassid, -- identifies the class of the entity the User Defined Field is
-- associated with
udtname, -- name of the User Defined Type for the User Defined Field
udfid, -- id of the User Defined Field
udfname, -- name of the User Defined Field
udftype, -- data type of the User Defined Field
UDF-Related Views
59
udfvalue, -- value of the User Defined Field
udfunitlabel -- units label for the User Defined Field (for configured numeric-type
-- UDFs only, null otherwise)
FROM
entity_udf_view
16.4. Usage
A typical usage may entail querying for information regarding UDFs on a particular sample. For example:
SELECT
udfname,
udfvalue,
udfunitlabel
FROM
sample_udf_view suv
JOIN
sample s
ON
suv.sampleid = s.sampleid
WHERE
s.name = 'Cancer Sample-12'
60
Chapter 17. Auditing
17.1. General
BaseSpace Clarity LIMS has 2 primary aspects to audit logging, namely an audit event log and an audit
change log. The audit event log is able to tell a story of how BaseSpace Clarity LIMS is being used. At
the event level, we’re able to report that Joe Technician started step 1 “DNA Extraction (Hamilton) 2.0”
at 10am on 12 samples. The event log is focused on easy-to- understand, human readable information that
reflects actions that are familiar to Clarity users. The audit change log will record exacting information
about changes that are the results of the actions recorded in the event log. Each entry specifies which row
of a table was changed and how it was affected (e.g. insert, update, or delete). For database updates, this
information will include both old and new values. Together, the audit event and change logs provide a
clear history of Clarity users, samples, and workflows.
17.2. Attributes
Audit Event Log has the following attributes:
SELECT
eventid, -- Identifier
applicationuserid, -- The application user ID that logged the event
applicationusername, -- The application user name that logged the event
applicationname, -- The name of the application where the change was initiated
applicationversion, -- The application version for the event
message, -- The application message for the event
eventtype, -- The event type
eventdate -- The event date/time
FROM
auditeventlog
Change Event has the following attributes:
SELECT
changeid, -- Identifier
eventid, -- Foreign Key to business defined auditevent
transactionid, -- Identifier of the transaction that made the change
databaseusername, -- The database user associated with the session
schemaname, -- The database schema the changed table is in
tablename, -- The table name the changed record is in
rowpk, -- The primary key value of the record that was changed.
rowlimsid, -- The Clarity LimsId for the changed record (if applicable)
applicationuserid, -- The application user ID that logged the event
applicationusername, -- The application user name that logged the event
applicationname, -- The name of the application where the change was initiated
Auditing
61
changetype, -- Code for type of event: (I)nsert, (U)pdate or (D)elete.
rowdata, -- Key value pairs for the record columns
changedfields, -- Key value pairs showing the new values for changed records
changedate -- The event date/time
FROM
auditchangelog
17.3. Associated Data
Audit Event has no direct relationships. An Audit Change is related to an Audit Event via its eventid
field.
Figure 17.1. Audit Event Associated Data
Auditing
62
17.4. Examples
17.4.1. Audit Events for a particular user
The following query returns audit events with associated change logs for a specified user.
SELECT
ae.eventid as event,
ae.message as message,
ae.eventtype as eventtype,
ac.rowdata as rowdata,
ac.changedfields as changes,
ac.changedate as changedate
FROM auditeventlog ae
JOIN auditchangelog ac ON ae.eventid = ac.eventid
WHERE ae.applicationusername = 'admin'
ORDER BY ae.eventid