Sample Code To Reserve and Unreserve Specimens

Introduction

In OpenSpecimen, users are restricted from updating any information about specimens marked as "Reserved." This restriction applies to both default and custom fields at the specimen level, ensuring that no changes are made to quantitative or qualitative data after a specimen is marked as reserved for distribution. This maintains data integrity and ensures consistency in distribution protocols.

Occasionally, however, users may encounter scenarios requiring updates to reserved specimens in bulk. The standard process involves first unreserving the specimens, making the necessary updates, and then re-reserving them if they still meet the distribution protocol requirements.

This wiki page outlines the instructions for using a Python script to streamline this process. The script interacts with the OpenSpecimen API to reserve or unreserve specimens in bulk, based on a provided CSV input file.

Prerequisites

Before running the script, ensure that you have the following:

• Python 3.x installed on your system.

• The required Python libraries (e.g., requests) installed.

• Access to the OpenSpecimen API with admin credentials.

• A valid CSV input file with the distribution protocol and specimen ID to be reserved or unreserved.

Parameters

The scripts accept four parameters:

1. OpenSpecimen API URL: The URL where your OpenSpecimen instance is hosted.

2. Username: The username for logging into OpenSpecimen.

3. Password: The password for logging into OpenSpecimen.

4. CSV File: The CSV file containing the distribution protocol and specimen ID information.
   Example CSV Format:

   "Distribution Protocol","Specimen Identifier" "DP1",13627 "DP1",5273 "DP2",738 "DP2",17283

Reserve/Unreserve Specimens Script

This script reserves specimens based on the distribution protocol and specimen ID provided in the CSV input file.

To generate the CSV file you can use a OpenSpecimen Query module.

Steps to create a parametrized query to get distribution protocol short title and specimen identifier are:
A. Login to OpenSpeicmen → Navigate To → Query → Create
B. Select Specimen → Label → ALL as shown in the below image.

Open

C. Click on View Records → Actions → Columns → Select Only Needed Columns → Done
Output:

Open