Import subject metadata

This example demonstrates how to import subject metadata for an existing subject on Moveshelf via the Moveshelf API. First we retrieve the subject from Moveshelf via its MRN/EHR-ID. Then, we update its subject metadata.

Important: The keys in the metadata dictionary to be imported must match the metadata template that is configured for the Moveshelf project you want to import to. You can download the configured metadata template from the project overview.

Prerequisites

Before implementing this example, ensure that your processing script includes all necessary setup steps. In particular, you should have:

Configured the Moveshelf API (version >= 1.4.0)
Created the subject, or made sure a subject with the specified MRN already exists on Moveshelf

Implementation

To import subject metadata to an existing subject, add the following lines of code to your processing script:

## README: this example shows how we can import subject metadata to an existing
# subject on Moveshelf using the Moveshelf Python API.
# This code assumes you have implemented the 'Create subject' example, and
# that you have found the subject with a given EHR-id/MRN (my_subject_mrn)
# or name (my_subject_name) within a given project (my_project), and that 
# you have access to the subject ID
# For that subject, update subject metadata (my_subject_metadata)

## General configuration. Set values before running the script
my_project = "<organizationName/projectName>"  # e.g. support/demoProject
my_subject_mrn = "<subjectMRN>"  # subject MRN, e.g. "1234567" or None
my_subject_name = "<subjectName>"  # subject name, e.g. Subject1

# Manually define the subject metadata dictionary you would like to import
my_subject_metadata = {
    "subject-first-name": "<subjectFirstName>",
    "subject-middle-name": "<subjectMiddleName>",
    "subject-last-name": "<subjectLastName>",
    "ehr-id": my_subject_mrn,
    "interventions": [ # List of interventions
        {
            "id": 0, # <idInterv1>
            "date": "<dateInterv1>", # "YYYY-MM-DD" format
            "site": "<siteInterv1>",
            "surgeon": "<surgeonInterv1>",
            "procedures": [
                {
                    "side": "<sideProc1Interv1>",
                    "location": "<locationProc1Interv1>",
                    "procedure": "<procedureProc1Interv1>",
                    "location-modifier": "<locationModProc1Interv1>",
                    "procedure-modifier": "<procedureModProc1Interv1>"
                },
                {
                    "side": "<sideProc2Interv1>",
                    # ... You can add multiple procedures
                }
            ],
            "surgery-dictation": "<surgeryDictationInterv1>"
        },
        # ... Additional interventions can be added here, each represented as a dictionary
        # Increment the "id" for each new intervention (e.g., 1, 2, 3,...)
        # Ensure each intervention contains a complete set of fields
    ]
    # ... Add additional fields you would like to import
}

## Add here the code to retrieve the project and find an existing subject and its "subject_details"
# ... subject_found = True

# Import subject metadata
subject_updated = api.updateSubjectMetadataInfo(
    subject["id"], json.dumps(my_subject_metadata)
)
 

It is also possible to load subject metadata from a JSON file stored on your local machine, e.g., 'moveshelf_config_import.json'. Instead of defining my_subject_mrn and my_subject_metadata manually, you can load them from a JSON file located in your root folder as shown below:

# Define the path to the local JSON file
local_metadata_json = os.path.join(parent_folder, "moveshelf_config_import.json")

# Load JSON file
with open(local_metadata_json, "r") as file:
    local_metadata = json.load(file)

# Extract subjectMetadata dictionary from metadata JSON
my_subject_metadata = local_metadata.get("subjectMetadata", {})
my_subject_mrn = my_subject_metadata.get("ehr-id", "")

# Extract interventionMetadata list from metadata JSON
my_subject_metadata["interventions"] = local_metadata.get("interventionMetadata", [])

Validation

To verify that the subject metadata has been successfully imported, you can either check directly on Moveshelf or programmatically via the Moveshelf API. For the manual validation, log in to Moveshelf and navigate to the relevant project to check if the subject appears with the correct subject metadata. If you prefer an automated method, add the following lines of code to your processing script, right after updating subject metadata, to check the subject’s metadata programmatically:

# Fetch subject details using the subject ID
subject_details = api.getSubjectDetails(subject["id"])
subject_metadata = json.loads(subject_details.get("metadata", "{}"))

# Print the subject details
print(f"Created subject with name: {subject_details['name']},\n"
        f"id: {subject_details['id']}, \n"
        f"and metadata: {subject_metadata}") 

This code will retrieve the subject's details, including the name, ID, and subject metadata, and print them for verification.