Import session metadata

This example demonstrates how to import session metadata for an existing session on Moveshelf via the Moveshelf API. First we retrieve the subject from Moveshelf via its MRN/EHR-ID. Then, we retrieve the session via its session date, and update its 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 session, or made sure a session with the specified date already exists on Moveshelf

Implementation

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

## README: this example shows how we can import session metadata to an existing
# session on Moveshelf using the Moveshelf Python API.
# This code assumes you have implemented the 'Create session' example, and
# that you have found the session (my_session) for a 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 session ID and session_name
# For that session, update session metadata (my_session_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
my_session = "<sessionDate>" # "YYYY-MM-DD" format

# Manually define the session metadata dictionary you would like to import
my_session_metadata = {
    "interview-fms5m": "1",
    "vicon-leg-length": [
            {
                "value": "507",
                "context": "left"
            },
            {
                "value": "510",
                "context": "right"
            }
        ],
    # ... Add additional fields you would like to import
}

## Add here the code to retrieve the project and find an existing subject 
## and existing session
# loop over sessions until we find session_found = True

session_id = session["id"]
session = api.getSessionById(session_id)    # get all required info for that session
updated_session = api.updateSessionMetadataInfo(
    session_id,
    session_name,
    json.dumps({"metadata": my_session_metadata})
)
print(f"Updated session {session_name}: {updated_session}")

It is also possible to load session metadata from a JSON file stored on your local machine, e.g., 'moveshelf_config_import.json'. Instead of defining my_subject_mrn and my_session_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 sessionMetadata dictionary from metadata JSON
my_session_metadata = local_metadata.get("sessionMetadata", {})

Validation

To verify that the session 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 session appears with the correct session metadata. If you prefer an automated method, add the following lines of code to your processing script, right after updating session metadata, to check the session’s metadata programmatically:

# Fetch session details using the session ID
updated_session_details = api.getSessionById(session_id)
updated_session_metadata = updated_session_details.get("metadata", None)

# Print updated session metadata
print(
    f"Updated session with projectPath: {session['projectPath']},\n"
    f"id: {session_id}.\n"
    f"New metadata: {updated_session_metadata}"
)

This code will retrieve the updated session's details, including the projectPath, ID, and session metadata, and print them for verification.