Get in touch

Get in touch

Prefer using email? Say hi at hello@moveshelf.com

This section explains how to create a new subject on Moveshelf using the Moveshelf API, based on the subject's MRN/EHR-ID. Before creating a new subject, the script first checks whether a subject with the given MRN/EHR-ID already exists on Moveshelf.
  • If a matching subject is found, it is retrieved
  • If no existing subject is found, a new subject is created and assigned the specified MRN/EHR-ID
Prerequisites
Before implementing this example, ensure that your processing script includes all necessary setup steps. In particular, you should have:
Implementation
To create a new subject or retrieve an existing one, add the following lines of code to your processing script:
## README: this example shows how we can create a subject on Moveshelf 
# using the Moveshelf Python API.
# For a given project (my_project), first check if there already exists
# a subject with a given MRN (my_subject_mrn) or name (my_subject_name). If it doesn't exist, 
# we create a new subject with name my_subject_name, and assign my_subject_mrn if provided.

## 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", set to None if not needed.
my_subject_name = "<subjectName>"  # subject name, e.g. Subject1

## Get available projects
projects = api.getUserProjects()

## Select the project
project_names = [project["name"] for project in projects if len(projects) > 0]
idx_my_project = project_names.index(my_project)
my_project_id = projects[idx_my_project]["id"]

## Find the subject based on MRN or name
subject_found = False
if my_subject_mrn is not None:
    subject = api.getProjectSubjectByEhrId(my_subject_mrn, my_project_id)
    if subject is not None:
        subject_found = True
if not subject_found and my_subject_name is not None:
    subjects = api.getProjectSubjects(my_project_id)
    for subject in subjects:        
        if my_subject_name == subject['name']:
            subject_found = True
            break
if my_subject_mrn is None and my_subject_name is None:
    print("We need either subject mrn or name to be defined to be able to search for the subject.")

## Retrieve subject details if there was a match. Create new subject if there is no match
if subject_found:
    subject_details = api.getSubjectDetails(subject["id"])
    subject_metadata = json.loads(subject_details.get("metadata", "{}"))
    print(
        f"Found subject with name: {subject_details['name']},\n"
        f"id: {subject_details['id']}, \n"
        f"and MRN: {subject_metadata.get('ehr-id', None)}"
    )
else:
    print(
        f"Couldn't find subject with MRN: {my_subject_mrn},\n"
        f"in project: {my_project}"
    )
    new_subject = api.createSubject(my_project, my_subject_name)
    if my_subject_mrn is not None:
        subject_updated = api.updateSubjectMetadataInfo(
            new_subject["id"], json.dumps({"ehr-id": my_subject_mrn})
        )
Validation
To verify that the new subject 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 to check if the new subject appears with the correct MRN/EHR-ID. If you prefer an automated method, add the following lines of code to your processing script, right after creating the new subject, to check the subject’s details programmatically:
# Fetch subject details using the subject ID
new_subject_details = api.getSubjectDetails(new_subject["id"])
new_subject_metadata = json.loads(new_subject_details.get("metadata", "{}"))

# Print the subject details
print(f"Created subject with name: {new_subject_details['name']},\n"
        f"id: {new_subject_details['id']}, \n"
        f"and MRN: {new_subject_metadata.get('ehr-id', None)}")
This code will retrieve the newly created subject's details, including the name, ID, and MRN/EHR-ID, and print them for verification.