Managing Dashlets

How to Create Dashlets

You can create dashlets using OpenSpecimen's query module. For detailed steps, see: https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/83791234

Alternatively, create dashlets using JSON. Refer to the 'JSON' section below for examples.

Editing Dashlets:

A dashlet can be edited to change the name and/or description.

Click on the 'Edit' icon beside the dashlet title.
Enter the updated title/description and click on 'Update'.

Delete Dashlets

You can delete a dashlet that is not required anymore.

Click on the 'Delete' icon.

Note:

It should not be attached at any protocol level or system level.
Check that the value under the 'Dashboards' column is 0. If not, you will first need to remove the dashlet from all the dashboards to delete it.

Export/Import Dashlets

Export Dashlet

Import Dashlet

You can modify the exported dashlet definitions and import the JSON back.
Also, the dashlets can be exported from one instance and imported to another instance of OpenSpecimen.

Click on the 'Import' button.
Choose the updated JSON file → 'Import'.

JSON Examples

In the JSON examples below, you will notice OpenSpecimen internal variable names used in criteria/expr to create the Dashlets. Please read this page to learn how to quickly get these internal names.

Pie Chart: Total Available Specimen Subdivided by Specimen Type

Below is an example JSON to show the top 5 counts of specimens per type.

If you want counts for all specimen types, then remove line#16, i.e., "maxN": "5" from the JSON or alter the value as per the requirement.

{
  "name" : "dash_902_20250811_0359271",
  "title" : "Pie Chart: Total Specimen",
  "type" : "CHART",
  "dataSource" : {
    "options" : {
      "criteria" : "Specimen.type exists  and  Specimen.collectionStatus = \"Collected\" and  Specimen.availableQty > 0",
      "metric" : {
        "expr" : "count(distinct Specimen.id)",
        "title" : "Specimen Count"
      },
      "category" : {
        "expr" : "Specimen.type",
        "title" : "Type"
      },
      "maxN" : "5"
    },
    "type" : "AQL"
  },
  "chartOpts" : {
    "legend" : {
      "display" : true
    },
    "type" : "pie"
  },
  "activityStatus" : "Active"
}

Preview:

JSON File:

Bar Graph: Specimen Count by Type and Gender

Below is an example JSON showing specimen types and their counts by gender.

The example covers only Gender = ['Male', 'Female'] and Specimen Types = ['Whole Blood', 'Urine', 'Fresh Tissue'].
Adjust line #7, “criteria,” if you want counts for other genders and specimen types to get the desired dashlet.

{
  "name" : "countSpecimenByTypeAndGender",
  "title" : "Specimen Count by Type and Gender",
  "type" : "CHART",
  "dataSource" : {
    "options" : {
      "criteria" : "Participant.gender in (\"Female\",\"Male\") and  Specimen.type in (\"Whole Blood\",\"Fresh Tissue\",\"Urine\") and  Specimen.collectionStatus = \"Collected\"",
      "metric" : {
        "expr" : "count(distinct Specimen.id)",
        "title" : "Specimen Count"
      },
      "category" : {
        "expr" : "Specimen.type",
        "title" : "Type"
      },
      "series" : {
        "expr" : "Participant.gender",
        "title" : "Gender"
      }
    },
    "type" : "AQL"
  },
  "chartOpts" : {
    "legend" : {
      "display" : true,
      "position" : "bottom"
    },
    "scales" : {
      "yAxes" : [ {
        "ticks" : {
          "beginAtZero" : true
        }
      } ],
      "xAxes" : [ ]
    },
    "type" : "bar"
  },
  "activityStatus" : "Active"
}

Preview:

JSON File:

Pie Chart: Visit Count by Collection Department (Custom Field)

{
  "name" : "dash_1627_20251219_0605040",
  "title" : "Count Of Visits Per Department",
  "type" : "CHART",
  "dataSource" : {
    "options" : {
      "criteria" : "(SpecimenCollectionGroup.customFields.dwhs_visit_custom_field.collection_department any ) and CollectionProtocol.id = 1992",
      "metric" : {
        "expr" : "count(distinct SpecimenCollectionGroup.name)",
        "title" : "Visit Count"
      },
      "category" : {
        "expr" : "SpecimenCollectionGroup.customFields.dwhs_visit_custom_field.collection_department",
        "title" : "Collection Department"
      }
    },
    "type" : "AQL"
  },
  "chartOpts" : {
    "type" : "Pie"
  },
  "activityStatus" : "Active"
}

Preview:

JSON File:

Pie Chart: Visit Count by Fasting Status (Custom Form)

Explanation:

Expression to use a form field: SpecimenCollectionGroup.extensions.dwhs_visit_custom_field.fasting_status

Attribute	Description

Attribute	Description
SpecimenCollectionGroup	Internal object name for “Visit” level
extensions	Denotes “Custom Form” level
dwhs_visit_custom_field	Form variable name
fasting_status	Field variable name

Example:

{
  "name" : "dash_1627_20251219_0610022",
  "title" : "Count Of Visits Per Fasting Status",
  "type" : "CHART",
  "dataSource" : {
    "options" : {
      "criteria" : "(SpecimenCollectionGroup.extensions.dwhs_visit_custom_field.fasting_status any ) and CollectionProtocol.id = 1992",
      "metric" : {
        "expr" : "count(distinct SpecimenCollectionGroup.name)",
        "title" : "Visit Count"
      },
      "category" : {
        "expr" : "SpecimenCollectionGroup.extensions.dwhs_visit_custom_field.fasting_status",
        "title" : "Fasting Status"
      }
    },
    "type" : "AQL"
  },
  "chartOpts" : {
    "type" : "Pie"
  },
  "activityStatus" : "Active"
}

JSON File:

#3 and #4 are visit-level examples, if you wish to know the expression for ‘Participant’ or ‘Specimen’ refer below table:

The key-difference in the custom form v/s custom field is extensions vs customFields in the expressions.

Level	Expression

Level	Expression
Participant Form	`Participant.extensions.<form_name>.<field_name>`
Participant Custom Field	`Participant.customFields.<form_name>.<field_name>`
Visit Form	`SpecimenCollectionGroup.extensions.<form_name>.<field_name>`
Visit Custom Field	`SpecimenCollectionGroup.customFields.<form_name>.<field_name>`
Specimen Form	`Specimen.extensions.<form_name>.<field_name>`
Specimen Custom Field	`Specimen.customFields.<form_name>.<field_name>`