imaging_api.services.projects

Attributes

XNAT_URL

Functions

`get_project_from_central_hub_project_id`(...)	Gets the XNAT project from a central hub project ID (corresponds to XNAT project secondary ID)
`get_project`(→ imaging_api.routers.schemas.Project)	Fetches a specific XNAT project by selecting from all projects.
`get_all_projects`(...)	Fetches all XNAT projects using the correct REST API endpoint.
`create_payload_for_project_creation`(→ str)	Creates the payload for creating a new project in XNAT.
`create_project`(→ imaging_api.routers.schemas.Project)	Core function to create a new project in XNAT.
`to_create_project`(...)	Maps Central Hub project information to XNAT project input to make a request to create a project.
`set_project_prearchive_settings`(→ None)	Set Project Prearchive Settings.
`get_command_info`(→ tuple[int, str])	Fetches the XNAT command ID and wrapper name for a given container image.
`create_project_event_subscription`(→ None)	Creates a project-scoped event subscription in XNAT that auto-triggers a command on scan upload.
`add_central_hub_users_to_project`(...)	Adds list of central hub users to an imaging project on XNAT.
`delete_queued_import_requests`(→ bool)	Deletes queued import requests from PACS for a specific project.
`delete_project`(→ imaging_api.routers.schemas.Project)	Deletes an existing project in XNAT.
`get_subjects`(→ list[imaging_api.routers.schemas.Subject])	Retrieves a list of subjects in a specific project in XNAT.
`get_experiments`(...)	Fetches all XNAT experiments from a project.
`get_experiment`(→ dict)	Fetches a specific XNAT experiment from a project.
`get_subject_id_from_experiment_response`(→ str)	Extracts the XNAT subject ID from the XNAT experiment response JSON.

Module Contents

imaging_api.services.projects.XNAT_URL

imaging_api.services.projects.get_project_from_central_hub_project_id(central_hub_project_id: str, headers: dict[str, str]) → imaging_api.routers.schemas.Project

Gets the XNAT project from a central hub project ID (corresponds to XNAT project secondary ID)

Parameters:

central_hub_project_id (str) – Central hub project ID
headers (dict[str, str]) – XNAT authentication headers

Returns:

XNAT project object

Return type:

Project

Raises:

imaging_api.utils.exceptions.NotFoundError – If no XNAT project has a matching secondary_ID.
Exception – If the upstream get_all_projects call fails.

imaging_api.services.projects.get_project(project_id: str, headers: dict[str, str]) → imaging_api.routers.schemas.Project

Fetches a specific XNAT project by selecting from all projects.

Parameters:

project_id (str) – Unique identifier for the project
headers (dict[str, str]) – XNAT authentication headers

Returns:

XNAT project object

Return type:

Project

Raises:

imaging_api.utils.exceptions.NotFoundError – If no XNAT project matches project_id.
Exception – If the upstream get_all_projects call fails.

imaging_api.services.projects.get_all_projects(headers: dict[str, str]) → list[imaging_api.routers.schemas.Project]

Fetches all XNAT projects using the correct REST API endpoint.

Parameters:: headers (dict[str, str]) – XNAT authentication headers
Returns:: List of XNAT project objects
Return type:: list[Project]
Raises:: Exception – If the HTTP request to XNAT fails, or if XNAT returns a non-200 response.

imaging_api.services.projects.create_payload_for_project_creation(xnat_projects_uri: str, project_id: str, project_secondary_id: str, project_name: str, project_description: str = '') → str

Creates the payload for creating a new project in XNAT.

Builds the XML using xml.etree.ElementTree so that XML control characters (<, >, &, ", ') in any field are escaped as entity references rather than interpolated raw — this defeats XML injection that could otherwise mutate the projectData document sent to XNAT.

Parameters:

xnat_projects_uri (str) – XNAT projects URI.
project_id (str) – Unique identifier for the project.
project_secondary_id (str) – Secondary ID for the project.
project_name (str) – Name of the project.
project_description (str, optional) – Description of the project.

Returns:

XML payload for creating the project.

Return type:

str

imaging_api.services.projects.create_project(project_id: str, project_secondary_id: str, project_name: str, project_description: str, headers: dict[str, str]) → imaging_api.routers.schemas.Project

Core function to create a new project in XNAT.

Note that ID, secondary_ID and name are required.

Uses the XNAT REST API endpoint: POST - /data/projects Note this endpoint only accepts XML payload, not JSON. See also https://wiki.xnat.org/xnat-api/project-api#ProjectAPI-Createoneormoreprojects

Parameters:

project_id (str) – Unique identifier for the project.
project_secondary_id (str) – Secondary ID for the project.
project_name (str) – Name of the project.
project_description (str) – Description of the project.
headers (dict[str, str]) – XNAT authentication headers.

Returns:

XNAT project object.

Return type:

Project

Raises:

AlreadyExistsError – If a project with the same ID already exists in XNAT.
Exception – If there is an error during the creation of the project.

imaging_api.services.projects.to_create_project(imaging_project: imaging_api.routers.schemas.CentralHubProject) → imaging_api.routers.schemas.CreateProject

Maps Central Hub project information to XNAT project input to make a request to create a project.

Parameters:: imaging_project (imaging_api.routers.schemas.CentralHubProject) – Central Hub project object.
Returns:: XNAT create project request object.
Return type:: CreateProject

imaging_api.services.projects.set_project_prearchive_settings(project_id: str, headers: dict[str, str]) → None

Set Project Prearchive Settings. See also https://wiki.xnat.org/xnat-api/prearchive-api#PrearchiveAPI-SetProjectPrearchiveSettings

Parameters:

project_id (str) – Unique identifier for the project
headers (dict[str, str]) – XNAT authentication headers

Returns:

None

Raises:

Exception – If there is an error during the process of setting the project prearchive settings.

imaging_api.services.projects.get_command_info(container: str, headers: dict[str, str]) → tuple[int, str]

Fetches the XNAT command ID and wrapper name for a given container image.

Parameters:

container (str) – Container image name, e.g. “xnat/dcm2niix:latest”.
headers (dict[str, str]) – XNAT authentication headers.

Returns:

A tuple of (command_id, wrapper_name).

Return type:

tuple[int, str]

Raises:

Exception – If the command cannot be fetched from XNAT.

imaging_api.services.projects.create_project_event_subscription(project_id: str, container: str, active: bool, headers: dict[str, str]) → None

Creates a project-scoped event subscription in XNAT that auto-triggers a command on scan upload.

The subscription listens for ScanEvent:CREATED events within the specified project and triggers the given container command when a scan with DICOM resources is created. The active flag controls whether the subscription is enabled or deactivated on creation.

Parameters:

project_id (str) – XNAT project ID to scope the subscription to.
container (str) – Container image name, e.g. “xnat/dcm2niix:latest”.
headers (dict[str, str]) – XNAT authentication headers.
active (bool) – If True, the subscription is active immediately. If False, it is created but deactivated (can be toggled later via the XNAT API).

Raises:

Exception – If the subscription creation fails.

imaging_api.services.projects.add_central_hub_users_to_project(central_hub_project: imaging_api.routers.schemas.CentralHubProject, project_id: str, headers: dict[str, str]) → tuple[list[imaging_api.routers.schemas.CreatedUser], list[imaging_api.routers.schemas.User]]

Adds list of central hub users to an imaging project on XNAT.

Note users that are disabled will not be created or added to the XNAT project. TODO reassess this decision.

Parameters:

central_hub_project (imaging_api.routers.schemas.CentralHubProject) – Central Hub project object
project_id (str) – Unique identifier for the project
headers (dict[str, str]) – XNAT authentication headers

Returns:

List of created users and added users.

Return type:

tuple[list[imaging_api.routers.schemas.CreatedUser], list[imaging_api.routers.schemas.User]]

async imaging_api.services.projects.delete_queued_import_requests(project_id: str, headers: dict[str, str]) → bool

Deletes queued import requests from PACS for a specific project.

Does not raise an exception if it fails to delete the queued imports.

Parameters:

project_id (str) – Unique identifier for the project
headers (dict[str, str]) – XNAT authentication headers

Returns:

True if deletion was successful, False otherwise

Return type:

bool

async imaging_api.services.projects.delete_project(project_id: str, headers: dict[str, str]) → imaging_api.routers.schemas.Project

Deletes an existing project in XNAT.

Parameters:

project_id (str) – Unique identifier for the project
headers (dict[str, str]) – XNAT authentication headers

Returns:

XNAT project object

Return type:

Project

Raises:

imaging_api.utils.exceptions.NotFoundError – If the project does not exist on XNAT.
Exception – If XNAT returns a non-200 response for the delete call.

imaging_api.services.projects.get_subjects(project_id: str, headers: dict[str, str]) → list[imaging_api.routers.schemas.Subject]

Retrieves a list of subjects in a specific project in XNAT.

Parameters:

project_id (str) – Unique identifier for the project.
headers (dict[str, str]) – XNAT authentication headers.

Returns:

List of XNAT subject objects.

Return type:

list[Subject]

Raises:

Exception – If there is an error while fetching the subjects from XNAT.

imaging_api.services.projects.get_experiments(project_id: str, headers: dict[str, str]) → list[imaging_api.routers.schemas.Experiment]

Fetches all XNAT experiments from a project.

Parameters:

project_id (str) – Unique identifier for the project.
headers (dict[str, str]) – XNAT authentication headers.

Returns:

List of XNAT experiment objects.

Return type:

list[Experiment]

Raises:

Exception – If there is an error while fetching the experiments from XNAT.

imaging_api.services.projects.get_experiment(project_id: str, experiment_id_or_label: str, headers: dict[str, str]) → dict

Fetches a specific XNAT experiment from a project.

Note the XNAT Experiment API supports getting an experiment by either its label or ID:

GET - /data/projects/{project-id}/experiments/{experiment-label | experiment-id}

Parameters:

project_id (str) – Unique identifier for the project.
experiment_id_or_label (str) – Unique identifier or label for the experiment.
headers (dict[str, str]) – XNAT authentication headers.

Returns:

XNAT experiment dictionary response

Return type:

dict

Raises:

imaging_api.utils.exceptions.NotFoundError – If the experiment with the given ID or label is not found in the
project. –
Exception – If there is an error during the fetch process.

imaging_api.services.projects.get_subject_id_from_experiment_response(experiment_response: dict[str, Any]) → str

Extracts the XNAT subject ID from the XNAT experiment response JSON.

Parameters:: experiment_response (dict[str, Any]) – XNAT experiment response JSON.
Returns:: Subject ID
Return type:: str
Raises:: Exception – If there is an error during the parsing of the experiment response JSON.