Introduction
OpenSpecimen allows to configure graphical dashboards with various counters and graphs. This helps users to get a summary view of the data collected for the protocol. A default dashboard is shipped with OpenSpecimen which is set for all protocols. But users can change this to update the dashlets as per requirement. Dashboard feature is available as an enterprise plugin.
Default dashboard
When OpenSpecimen is deployed with dashboard plugin, all protocols are set with a default dashboard with below elements:
- Metrics(Counts)
- Total participants
- Total primary specimens
- Total available specimens
- Total distributed specimens
- Graphs
- Specimens by type
- Specimens by anatomic site
- Specimens collected vs distributed in previous quarter
- Specimens stored by freezer
Creating dashlets
Each of the above elements - metrics and graphs are considered as dashlets. These dashlets can either be created using query interface or REST API.
Create dashlet via UI
For details on creating using query interface, refer to Dashboard changes using query.
Create dashlet via API
URL: http[s]:<host>:<port>/openspecimen/rest/ng/dashlet-configs
| URL | |
| Method | POST |
| Request | application/json |
| Example1 json for Metric | Dashlet to include metric : Count of completed visits {
"name":"visit_count",
"title":"Visits",
"type":"COUNTER",
"dataSource":{
"options":{
"criteria":" SpecimenCollectionGroup.activityStatus = \"Active\" and SpecimenCollectionGroup.collectionStatus = \"Complete\" and Specimen.collectionStatus = \"Collected\" ",
"metric":{
"expr":"count(distinct SpecimenCollectionGroup.name)",
"title":"Visits"
}
},
"type":"AQL"
},
"chartOpts":{},
"activityStatus":"Active"
}
|
| Example2 json for graph | Dashlet to include graph : Available aliquots by type {
"name": "dash_1_20161215_0251537",
"title": "Available aliquots by type",
"type": "CHART",
"dataSource": {
"options": {
"criteria": " Specimen.collectionStatus = \"Collected\" and Specimen.lineage = \"Aliquot\" and Specimen.specimenPosition.containerName exists ",
"metric": {
"expr": "count(distinct Specimen.id)",
"title": "Aliquots"
},
"category": {
"expr": "Specimen.type",
"title": "Type"
}
},
"type": "AQL"
},
"chartOpts": {"type":"Pie","showSectionValuePct":true},
"activityStatus": "Active"
}
|
| Example3 JSON for SQL based count dashlet | {
"name": "dash-sys-active-dps",
"title": "Distribution Protocols",
"type": "COUNTER",
"dataSource": {
"type":"SQL",
"options": {
"metrics": [{"columnIndex": 0,"title": "Active Distribution Protocols"}],
"sql": "select count(dp.identifier) from catissue_distribution_protocol dp where dp.activity_status = 'Active'"
}
},
"chartOpts": {},
"activityStatus": "Active"
}
|
| Example4 JSON for SQL based graph dashlet | {
"name": "specimensByAnatomicSiteGroup",
"title": "Collected specimens by anatomic site group",
"type": "CHART",
"dataSource": {
"type":"SQL",
"options": {
"category": {"columnIndex":0,"title":"Anatomic Site"},
"metrics":[{"columnIndex":1,"title":"Collected Specimens"}],
"sql": "select a.value, count(s.identifier) from catissue_specimen s inner join catissue_collection_protocol cp on cp.identifier = s.collection_protocol_id inner join catissue_permissible_value pv on pv.value = s.tissue_site inner join os_pvs_hierarchy h on h.descendant_id = pv.identifier inner join catissue_permissible_value a on a.identifier = h.ancestor_id where %sql_cp_restriction% and (a.parent_identifier is null and s.collection_status = 'Collected' and s.lineage = 'Aliquot' and s.available_quantity > 0 and pv.public_id = 'anatomic_site' and a.public_id = 'anatomic_site' and s.activity_status != 'Disabled') group by a.value order by count(s.identifier) desc",
"restrictionOpts":{"type":"sql_cp_restriction","opts":{"cpIdExpr":"cp.identifier"}}
}
},
"chartOpts": {"type":"Pie","showSectionValuePct":true},
"activityStatus": "Active"
}
columnIndex in category and metrics specify what column of SQL result set should be used. In above example, first column of result set (i.e. columnIndex: 0) is used to create categories and second column of result set is used to show the count of each category. |
To edit existing dashlets, use 'Get' method to get the dashlets. Edit the JSON code for the specific dashlet section and use 'Put' to update it.
When 'showSectionValuePct' is set to true like example2 above, it shows percent of each section in the legends. See below graph:
Configuring dashboards to CP
Different dashboards can be set per CP. To change settings per CP, go to individual protocol settings and edit the dashlets to be included or excluded.
To set default dashboard for all CPs, follow the below steps:
| URL | http://<host>:<port>/openspecimen/rest/ng/dashboards/{dashboardId} |
| Method | PUT |
| Request | application/json |
| Example json | {
"view": "CollectionProtocol",
"viewParams": {
"cpId": "-1"
},
"dashlets": [
{
"config": {
"name": "dash-sys-participants"
},
"sortOrder": 1
},
{
"config": {
"name": "visit_count"
},
"sortOrder": 2
},
{
"config": {
"name": "dash_1_20161214_0406950"
},
"sortOrder": 3
},
{
"config": {
"name": "dash_1_20161214_0357273"
},
"sortOrder": 4
},
{
"config": {
"name": "dash_1_20161215_0251537"
},
"sortOrder": 5
},
{
"config": {
"name": "dash-spmns-by-anatomic"
},
"sortOrder": 6
},
{
"config": {
"name": "dash-sys-coll-dist"
},
"sortOrder": 7
},
{
"config": {
"name": "dash-sys-coll-dist-yr"
},
"sortOrder": 8
},
{
"config": {
"name": "dash-spmns-by-path"
},
"sortOrder": 9
}
],
"activityStatus": "Active"
}
|
Configuring dashboards to SpecimenCatalog
Query existing dashboard set for public SpecimenCatalog:
Method: Get
URL: http://<host>:<port>/rest/ng/dashboards?view=SpecimenCatalog
JSON for making changes to SpecimenCatalog dashboard is similar to CP dashboard. Only the 'view' has to be replaced with 'SpecimenCatalog'.