workflow-manager.app.api.scanhub_requests
=========================================

.. py:module:: workflow-manager.app.api.scanhub_requests

.. autoapi-nested-parse::

   Handler for exam requests.

   This module defines functions to interact with the exam manager service,
   including fetching tasks, sequences, and results. It provides a way to
   create and update acquisition tasks and results, ensuring that the data
   is properly formatted and authenticated.

   Copyright (C) 2023, BRAIN-LINK UG (haftungsbeschränkt). All Rights Reserved.
   SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-ScanHub-Commercial



Attributes
----------

.. autoapisummary::

   workflow-manager.app.api.scanhub_requests.TASK_URI
   workflow-manager.app.api.scanhub_requests.RESULT_URI
   workflow-manager.app.api.scanhub_requests.WORKFLOW_URI


Functions
---------

.. autoapisummary::

   workflow-manager.app.api.scanhub_requests.get_task
   workflow-manager.app.api.scanhub_requests.set_task
   workflow-manager.app.api.scanhub_requests.create_blank_result
   workflow-manager.app.api.scanhub_requests.set_result
   workflow-manager.app.api.scanhub_requests.get_result
   workflow-manager.app.api.scanhub_requests.delete_result
   workflow-manager.app.api.scanhub_requests.get_exam_id


Module Contents
---------------

.. py:data:: TASK_URI
   :value: 'http://exam-manager:8000/api/v1/exam/task'


.. py:data:: RESULT_URI
   :value: 'http://exam-manager:8000/api/v1/exam/result'


.. py:data:: WORKFLOW_URI
   :value: 'http://exam-manager:8000/api/v1/exam'


.. py:function:: get_task(task_id: str | uuid.UUID, user_access_token: str) -> scanhub_libraries.models.AcquisitionTaskOut | scanhub_libraries.models.DAGTaskOut

   Fetch acquisition task by ID from the exam manager service.

   Args
   ----
       task_id (str | UUID): The unique identifier of the task to retrieve.
       user_access_token (str): The user's access token for authentication.

   Returns
   -------
       AcquisitionTaskOut | None: The acquisition task object if found and valid.

   Raises
   ------
       HTTPException: If the task is not found (404) or is not an acquisition task (400).


.. py:function:: set_task(task_id: str | uuid.UUID, payload: scanhub_libraries.models.AcquisitionTaskOut | scanhub_libraries.models.DAGTaskOut, user_access_token: str) -> scanhub_libraries.models.AcquisitionTaskOut | scanhub_libraries.models.DAGTaskOut

   Update an acquisition task on the task service with the provided payload.

   Parameters
   ----------
   task_id : str | UUID
       The unique identifier of the task to update.
   payload : AcquisitionTaskOut
       The updated task data to send to the task service.
   user_access_token : str
       The access token used for authorization with the task service.

   Returns
   -------
   AcquisitionTaskOut
       The updated task object returned from the task service.

   Raises
   ------
   HTTPException
       If the task update fails (e.g. non-200 response from the task service).


.. py:function:: create_blank_result(task_id: str, user_access_token: str) -> scanhub_libraries.models.ResultOut

   Create a blank result in the exam manager service.

   Returns
   -------
       ResultOut: The created blank result object.

   Raises
   ------
       HTTPException: If the result creation fails (status code not 201).


.. py:function:: set_result(result_id: str | uuid.UUID, payload: scanhub_libraries.models.SetResult | scanhub_libraries.models.ResultOut, user_access_token: str) -> scanhub_libraries.models.ResultOut

   Update a result in the exam manager service.

   Args
   ----
       result_id (str): The unique identifier of the result to update.
       payload (SetResult): The data to update the result with.
       user_access_token (str): The user's access token for authentication.

   Returns
   -------
       ResultOut: The updated result object.

   Raises
   ------
       HTTPException: If the result update fails (status code not 200).


.. py:function:: get_result(result_id: str | uuid.UUID, user_access_token: str) -> scanhub_libraries.models.ResultOut

   Fetch a result by ID from the exam manager service.

   Args
   ----
       result_id (str): The unique identifier of the result to retrieve.
       user_access_token (str): The user's access token for authentication.

   Returns
   -------
       ResultOut: The result object if found.

   Raises
   ------
       HTTPException: If the result is not found (404).


.. py:function:: delete_result(result_id: str | uuid.UUID, user_access_token: str) -> None

   Fetch a result by ID from the exam manager service.

   Args
   ----
       result_id (str): The unique identifier of the result to retrieve.
       user_access_token (str): The user's access token for authentication.

   Returns
   -------
       ResultOut: The result object if found.

   Raises
   ------
       HTTPException: If the result is not found (404).


.. py:function:: get_exam_id(workflow_id: str, user_access_token: str) -> str

   Fetch acquisition task by ID from the exam manager service.

   Args
   ----
       task_id (str): The unique identifier of the task to retrieve.
       user_access_token (str): The user's access token for authentication.

   Returns
   -------
       AcquisitionTaskOut | None: The acquisition task object if found and valid.

   Raises
   ------
       HTTPException: If the task is not found (404) or is not an acquisition task (400).