Create session – Moveshelf

This section explains how to create a new session for a subject with a specified MRN on Moveshelf using the Moveshelf API, based on the session's name. Before creating a new session, the script first checks whether a session with the specified name already exists for that subject on Moveshelf.

If a matching session is found, it is retrieved
If no existing session is found, a new session is created and assigned the name and date specified in my_session

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 create a new session or retrieve an existing one, add the following lines of code to your processing script:

## README: this example shows how we can create a session on Moveshelf 
# using the Moveshelf 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 subject name (my_subject_name) within a given project (my_project),
# and that you have access to the subject ID
# For that subject, we check if a session with the specified name 
# (my_session) exists. If it doesn't exist, a new session is created with 
# the name and date specified in my_session (where the date serves as both
# the session's name and session's date).


## 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 = "YYYY-MM-DD" # session name, e.g. 2025-09-05

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

## Find existing session
sessions = subject_details.get('sessions', [])
session_found = False
for session in sessions:
    try:
        session_name = session['projectPath'].split('/')[2]
    except:
        session_name = ""
    if session_name == my_session:
        session_id = session['id']
        session = api.getSessionById(session_id) # get all required info for that session
        session_found = True
        print(f"Session {my_session} already exists")
        break

## Create new session if no match was found
if not session_found:
    session_path = "/" + subject_details['name'] + "/" + my_session + "/"
    session = api.createSession(my_project, session_path, subject_details['id']) # Tries to
    # extract and set the session date from session_path
    session_id = session['id']
       

Note: it is also possible to explicitly set the session date instead of extracting it from the session name my_session. To do so, provide an optional fourth parameter, e.g., my_session_date (in "YYYY-MM-DD" format), to createSession, i.e.,
session = api.createSession(my_project, session_path, subject_details['id'], my_session_date)
In this way it is possible to have a session name that is not a date and different from my_session_date.
This session date can be extracted from a JSON file stored on your local machine, e.g., 'moveshelf_config_import.json'. The JSON file should have the key "sessionDate" that stores the session date in "YYYY-MM-DD" format. The key "sessionDate" must be at the same level as keys "subjectMetadata" and "sessionMetadata". You can then extract the session date using:
my_session_date = local_metadata.get("sessionDate", None)
where local_metadata is the loaded JSON file.

Validation

To verify that the new session has been successfully created, 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 and subject to check if the new session appears with the correct name. If you prefer an automated method, add the following lines of code to your processing script, right after creating the new session, to check the session’s details programmatically:

# Fetch session details using the session ID
new_session = api.getSessionById(session_id)
print(
    f"Found session with projectPath: {new_session['projectPath']},\n"
    f"and id: {new_session['id']}"
)

This code will retrieve the newly created session's details, including the project path (that includes the subject name and the session name), and ID, and print them for verification.