basespace clarity lims 5.1 data model documentation€¦ · ii preface ..... vi

BaseSpace Clarity LIMS 5.1Data Model Documentation

GenoLogics, An Illumina Company

ii

Preface ........................................................................................................................................ vi

1. How to Use this Guide .................................................................................................... vi

2. Intended Audience and Prerequisites ................................................................................ vi

3. Your Feedback ................................................................................................................ vi

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. Introduction ................................................................................................................... 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.1 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 ......................................................................................................... 31

11.4. Examples ................................................................................................................... 32

11.4.1. Showing all reagent kits and lots for protocol steps ........................................... 32

12. Reagent Types ...................................................................................................................... 33

12.1. General ...................................................................................................................... 33

12.2. Attributes ................................................................................................................... 33

12.3. Associated Data ......................................................................................................... 33

13. User-Defined Field (UDF) .................................................................................................... 35

13.1. General ...................................................................................................................... 35

13.2. Attributes and Associated Data ................................................................................... 35

13.3. Value Storage ............................................................................................................ 38

13.4. Decoding the UDF values for different UDF types ....................................................... 39


iv

13.5. Examples ................................................................................................................... 40

13.5.1. List of all UDFs defined in the system ............................................................. 40

13.5.2. Result File UDF Names and Values ................................................................. 41

13.5.3. Project UDF Names and Values ....................................................................... 42

13.5.4. Process UDF Names and Values ...................................................................... 43

13.5.5. Process Output UDF Names and Values ........................................................... 44

13.5.6. List of all UDF preset values for a specific UDF ............................................... 46

14. User-Defined Type (UDT) .................................................................................................... 47

14.1. General ...................................................................................................................... 47

14.2. Attributes ................................................................................................................... 47

14.3. Associated UDFs ....................................................................................................... 48

14.4. Examples ................................................................................................................... 48

14.4.1. Project UDT and UDF Names and Values ........................................................ 48

14.4.2. Process UDT and UDF Names and Values ....................................................... 50

15. Glsfile .................................................................................................................................. 52

15.1. General ...................................................................................................................... 52

15.2. Attributes ................................................................................................................... 52

15.2.1. File Server Name ............................................................................................ 52

15.2.2. File URI ......................................................................................................... 52

15.2.3. Original Location ............................................................................................ 53

15.2.4. Is Published [deprecated] ................................................................................. 53

15.2.5. Is Temporary .................................................................................................. 53

15.2.6. Attach To ID / Class ID .................................................................................. 53

15.3. Associated Data ......................................................................................................... 53

15.4. Examples ................................................................................................................... 54

15.4.1. New Files ....................................................................................................... 54

15.4.2. Project Files .................................................................................................... 54

16. Software, Instrument and more .............................................................................................. 55

16.1. General ...................................................................................................................... 55

16.2. Attributes ................................................................................................................... 55

17. UDF-Related Views .............................................................................................................. 58

17.1. General ...................................................................................................................... 58

17.2. Views ........................................................................................................................ 58

17.3. Attributes ................................................................................................................... 58

17.4. Usage ........................................................................................................................ 60

18. Auditing ............................................................................................................................... 61

18.1. General ...................................................................................................................... 61

18.2. Attributes ................................................................................................................... 61

18.3. Associated Data ......................................................................................................... 62

18.4. Examples ................................................................................................................... 63


v

18.4.1. Audit Events for a particular user ..................................................................... 63

vi

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,



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. Terminology

2.1. Introduction

Many 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 or general 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

Labels reagenttype

Labels that have been applied reagentlabel

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.


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.lastname

FROM

project,

researcher

WHERE

project.researcherid = researcher.researcherid

ORDER BY project.name

Samples are associated to projects in a n:1 relationship:

SELECT


sample.name AS samplename

FROM

project,

sample

WHERE

project.projectid = sample.projectid


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'


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.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


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


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,


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,


instrument.name AS instrumentname,

software.name AS softwarename

FROM process



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


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


process.luid,

process.daterun

FROM


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


process.daterun,

process.luid

FROM


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


process.daterun,

process.luid,



researcher.lastname

FROM process


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,


instrument.name AS instrumentname,

software.name AS softwarename

FROM process



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,


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;


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


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


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;


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).


29


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


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 can be configured to be used with protocol steps using the protocolstep_reagentkit_map

table.

Reagent Kits and Lots

32

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

33

Chapter 12. Reagent Types

12.1. General

Reagent types are referred to as Labels in the user interface. These are the configurable aspect of Labels.

They are stored in the reagenttype table.

12.2. Attributes

The reagenttype table describes the available reagenttypes (Labels):

SELECT

reagenttypeid,

name,

specialtype, -- The special type is 'Index' for Labels

metadata, -- The metadata contains the sequence in xml

reagentcategoryid, -- The id of the associated category

ownerid,

lastmodifieddate,

lastmodifiedby

FROM

reagenttype

WHERE

isvisible = '1' -- label has not been deleted


Reagent types can be applied to Submitted Samples or other artifacts. When a reagent type is applied for

the first time, for example, to a Submitted Sample, an entry is made in the reagentlabel table.

SELECT

labelid, -- pk of this reagent label

name, -- name of the reagent label

ownerid,

createddate,

lastmodifieddate,

lastmodifiedby

FROM

reagentlabel

Reagent Types

34

Reagent categories are referred to as Groups of Labels in the user interface. A reagenttype may or may

not belong to a reagentcategory, as reflected in the reagenttype.reagentcategoryid column. The

reagentcategory table represents the grouping for a set of Labels.

SELECT

reagentcategoryid,

name,

ownerid,

createddate,

lastmodifieddate,

lastmodifiedby

FROM

reagentcategory

WHERE

isvisible = '1' -- filters out any deleted group

35

Chapter 13. User-Defined Field (UDF)

13.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.

13.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 13.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)

36

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.


37

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


38

13.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:


39

SELECT

udf.name,

udf.type,

udf.storagefield,

udf.rowindex,


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.

13.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


40

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.

13.5. Examples

13.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.tablename

FROM udf

LEFT OUTER JOIN classindex ON udf.attachtoclassid = classindex.classindexid

WHERE udtid IS NULL


41

13.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 = 'numeric0' then '' || aus.numeric0















42


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;

13.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


TO_CHAR(TO_TIMESTAMP(eus.text0, 'YYYY-MM-DD' ), 'YYYY-MM-DD')




























when udf.storagefield = 'numeric0' then '' || eus.numeric0


43
















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;

13.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')















44















WHEN udf.storagefield = 'numeric0' THEN '' || pus.numeric0















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;

13.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




45













































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;


46

13.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

47

Chapter 14. User-Defined Type (UDT)

14.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.

14.2. Attributes

UDTs have the following attributes.

SELECT

udtid,

User-Defined Type (UDT)

48

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.

14.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.

14.4. Examples

14.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",


49

case















































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;


50

14.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













































51



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;

52

Chapter 15. Glsfile

15.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.

15.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

15.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.

15.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

53

15.2.3. Original Location

The originallocation attribute contains the absolute path and original filename of the file from a client

system.

15.2.4. Is Published [deprecated]

The ispublished attribute contains 'true' if the file is published to LabLink, or 'false' otherwise.

15.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.

15.2.6. Attach To ID / Class ID

This is discussed in the 'Concepts' chapter.


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

54

15.4. Examples

15.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

15.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

55

Chapter 16. Software, Instrument andmore

16.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.

16.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 16.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

56

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

57

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

58

Chapter 17. UDF-Related Views

17.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.

17.2. ViewsFour UDF views, outlined in the table below, correspond to four classes of entities.

Table 17.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

17.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

59

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








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








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





UDF-Related Views

60




FROM

entity_udf_view

17.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'

61

Chapter 18. Auditing

18.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.

18.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

62

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


Audit Event has no direct relationships. An Audit Change is related to an Audit Event via its eventid

field.

Figure 18.1. Audit Event Associated Data

Auditing

63

18.4. Examples

18.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

basespace clarity lims 5.1 data model documentation€¦ · ii preface ..... vi

Documents