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 and date. 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 specified name (my_session_name) and date (my_session_date)

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.6.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)
# 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_name) exists. If it doesn't exist, a new session is created with the specified
# name (my_session_name) and date (my_session_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_session_name = "YYYY-MM-DD" # session name, e.g. 2025-09-05
my_session_date = "YYYY-MM-DD" # typically the same as 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_name:
        session_id = session['id']
        session = api.getSessionById(session_id) # get all required info for that session
        session_found = True
        print(f"Session {my_session_name} already exists")
        break

## Create new session if no match was found
if not session_found:
    session_path = "/" + subject_details['name'] + "/" + my_session_name + "/"
    session = api.createSession(my_project, session_path, subject_details['id'], my_session_date)
    session_id = session['id']
       

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.