OpenSpecimen

Overview

Developed and maintained by Krishagni Solutions

What is Openspecimen?

Open Specimen is a bio-banking platform to collect, store, process, annotate and distribute bio-specimens in a cohesive bio-banking database.

Features - Biorepository Management - OpenSpecimen - Clinical Research Informatics FAQs - SC CTSI Clinical Research Informatics

Link - Getting Started - OpenSpecimen - Confluence
Video - https://www.youtube.com/watch?v=Cy7tSOWT9jI

Modes of Query

Get Raw Data

Get Counts (Pivot Table)

AQL

AQL is Krishagni's proprietary query language to query data without knowing the relational model of the underlying database. Traditional database query languages like SQL require users to know the physical data schema (the structure of tables and columns) to write queries. However, OpenSpecimen stores complex, detailed biospecimen data using a multi-level model which makes the data structure more complex and less intuitive for a typical database query. AQL was designed to overcome this limitation by allowing queries to be written in a way that aligns with the semantic meaning of the biospecimen data, rather than its physical storage structure.

API Calls

Authentication

URL	https://keckbiobank.med.usc.edu/openspecimen/rest/ng/sessions

URL	https://keckbiobank.med.usc.edu/openspecimen/rest/ng/sessions
Method	POST
Content-Type	application/json
Request Body	{ "loginName": " ", "password": " ", "domainName": "openspecimen" }
Response	HTTP 200 OK response with following body { "id": <>, "firstName": " ", "lastName": " ", "loginName": " ", "token": " ", "admin": <>, "instituteAdmin": <> }

Authorization of user with roles

Participant Count and Details

URL	https://keckbiobank.med.usc.edu/openspecimen/rest/ng/query

URL	https://keckbiobank.med.usc.edu/openspecimen/rest/ng/query
Method	POST
Content-Type	application/json
Request Body	{"aql": " ", "caseSensitive": false, "cpId": <>, "drivingForm": "Participant", "runType": "Count", "savedQueryId": <> }
Response	HTTP 200 OK response with following body JSON Column Data

URL	https://keckbiobank.med.usc.edu/openspecimen/rest/ng/query

URL	https://keckbiobank.med.usc.edu/openspecimen/rest/ng/query
Method	POST
Content-Type	application/json
Request Body	{"aql": " ", … "drivingForm": "Participant", "runType": "Data", … }
Response	HTTP 200 OK response with following body JSON Participant Data

Specimen Count and Details

URL	https://keckbiobank.med.usc.edu/openspecimen/rest/ng/query

URL	https://keckbiobank.med.usc.edu/openspecimen/rest/ng/query
Method	POST
Content-Type	application/json
Request Body	{"aql": " ", "caseSensitive": false, "cpId": <>, "drivingForm": "Participant", "runType": "Count", "savedQueryId": <> }
Response	HTTP 200 OK response with following body JSON Column Data

URL	https://keckbiobank.med.usc.edu/openspecimen/rest/ng/query

URL	https://keckbiobank.med.usc.edu/openspecimen/rest/ng/query
Method	POST
Content-Type	application/json
Request Body	{"aql": " ", … "drivingForm": "Participant", "runType": "Data", … }
Response	HTTP 200 OK response with following body JSON Specimen Data

Index

Term	Values	Description

Term	Values	Description
ppid		Participant Protocol ID.
cpId		Collection protocol ID. If specified, limits the results to specified CP records. Useful when AQL contains CP specific custom fields.
aql		Valid AQL string that needs to be executed.
wideRowMode	Default - OFF SHALLOW, DEEP	Specifies whether multi-valued attributes result in a single row or one row per value.
drivingForm	Participant, Specimen	Driving form determines the search perspective. When left empty, it defaults to Participant. (For example when drivingForm is Participant, the root table is 'catissue_coll_prot_reg' which is then used to join with the other tables.Similarly when drivingForm is Specimen, the root table will be catissue_specimen, which will be joined with the other tables.)
outputColumnExprs		Specifies whether the column labels or AQL expression needs to be included in the query response. By default, user friendly column labels are included in query response.
outputIsoDateTime		Specifies how the date column values needs to be serialised in the query response. If true, then date/time values are serialised using ISO format: yyyy-MM-dd'T'HH:mm:ss. Otherwise, date/time values are serialised using the format specified in OS locale settings.
timeoutInSeconds		Specifies how long to wait for the query to complete before aborting it. When not specified, this field defaults to 55 seconds. This is a guard against the run away query that hog the system resources, eventually resulting in service disruption. To wait forever for the query to complete, use -1. This should be avoided unless you are aware about the consequences of allowing a runaway query.