14.1. Clara Results Service

The Results Service for Clara Deploy SDK is designed to bridge the gap between the pipelines generating results and the services (data exporters) delivering the results to external devices.

The service allows pipelines to register results for an agent. Each received request is converted into a task and queued in the service. Exporters can simply query the Tasks API for any results that they are assigned to.

14.1.1. Task States

Each Task stored in the Results Service has an associated State, which can have one of the following values:

State Value Description
Pending 1 Task is waiting for an agent to process it.
InProgress 2 Task is being processed by an agent.
Succeeded 3 Task has been processed and delivered to specified destination(s).
Failed 4 Agent was unable to deliver the results.

In addition to tracking the State of each task, the service tracks the number of Retries performed on a task. The user of the API may simply report failure and retry at a later time. See the API Usage section for additional details.

14.1.2. Definitions

Term Definition
Agent or Exporter A service or process that delivers results generated by a pipeline to an external service or device.
Agent Name A unique identifier for an agent used by the services to register results or retrieve tasks. The name can include alphanumeric and hyphen (-) characters; it must begin with a letter and must not end with a hyphen.

14.1.3. Requirements

This container requires Docker 18.09.2 or higher.

14.1.4. Running the Results Service

Before running the container, use docker pull to ensure an up-to-date image is installed. Once the pull is complete, you can run the container image.

14.1.4.1. Run the Results Service

  1. In the Tags section, locate the container image release that you want to run.

  2. In the PULL TAG column in the table, click the icon to copy the docker pull command.

  3. Open a command prompt and paste the pull command. Ensure the pull completes successfully before proceeding to the next step.

  4. Create a data directory with the following command:

    mkdir -p data
    

    That directory will be mounted to the container in subsequent steps and used for the persistent sqlite database file.

  5. Create a network for the Results Service.

    docker network create claranet
    
  6. Configure the Results Service.

  7. Run the Results Service with the following commands:

    docker run -it --rm -d \
      --name resultsservice \
      --network claranet \
      -p 5000:80 \
      -v /{path-to-appsettings.json}:/app/appsettings.json \
      -v {path-to-the-data-dir-from-step-4}:/database \
      resultsservice:<x.x.x>
    

    Where:

    • -it keeps STDIN open even if not attached, and allocating a pseudo-TTY
    • --rm deletes the container when finished
    • -d specifies Detached mode: Run containers in the background
    • --name assigns a name to the container; in this case, resultsservice
    • --network connects a container to a network
    • -p publishes the container port to host (here, we map 5000 on the host to 80 in the container)
    • -v mounts the host folder to the container folder
    • \<x.x.x\\> is the container version. For example, 0.3.0.

    Once the container is launched, you may access the Swagger API documentation or check the API Usage section for additional details.

  8. Stop the container and remove the network with the following commands:

    docker stop resultsservice
    docker network rm claranet
    

14.1.5. API Usage

14.1.5.1. POST /api/tasks/register/[agent-name]

Registers results with the Results Service. Results are converted into tasks for the specified agent.

14.1.5.1.1. Parameters

Name Required Type Description Example
pipelineId
string A unique ID representing a pipeline published by the user 85065833c5554080afd1328a99cfb762
jobId
string A unique ID representing a job generated by Clara 53c398f291304a58bee886075d5c33dd
payloadId
string A unique ID representing the payload associated with the job where the results are stored 7a21712c334c482db033489548009a17
agentName
string (max length 32) The name of the exporter that will be responsible for delivering the results. Note that agentName comes from the pipeline definition with the --agent switch. dicom-export, s3-uploader
parameters   string Arguments that will be passed to the exporter. Note that parameters comes from the pipeline definition with the --data switch and must be a valid JSON-formatted string. ["PACS1", "ReadingWorkstation"], mys3bucketname
uris
string[] An array of URIs to locate results in the specified payload ["/recon-op/mhd/series1.mhd",  "/recon-op/mhd/series1.raw","/dicom-op/series1.dcm"]

14.1.5.1.2. Responses

Response Content Type: JSON

Returns a string ID representing the newly created task.

Code Description
200 Results registered with the service successfully.

14.1.5.1.3. Example Request

curl -i \
     -X POST "http://localhost:8088/api/Tasks/register/erf"  \
     -H "accept: application/json" \
     -H "Content-Type: application/json-patch+json" \
     -d "{ \"pipelineId\": \"89b5e6ce3eb24c82b7fd4130ae5e2db0\", \
       \"jobId\": \"05a6300271ba49a29bc80fd4af328b6c\", \
       \"payloadId\": \"6e4dd28ce78946fc897873c58cf623e6\", \
       \"parameters\": \"[\\\"PACS1\\\", \\\"ReadingWorkstation\\\"]\", \
       \"uris\": ['/recon-op/mhd/series1.mhd', '/recon-op/mhd/series1.raw','/dicom-op/series1.dcm']}"

# -i Prints HTTP response code
# -d HTTP PUT data
# -H HTTP header
# -X Request command

14.1.5.1.4. Example Response

"0a12ef41-e9d9-4a92-a3e6-2e1be82151f7"

14.1.5.2. GET /api/tasks/[agent-name]/[state]

Retrieves tasks associated with the specified [agent-name]. Note that when the API is called with state=pending, tasks found with the Pending state are updated to InProgress immediately and returned.

14.1.5.2.1. Parameters

Name Required Type Description Example
agentName
string (max length 32) The name of the exporter that will be responsible for delivering the results dicom-export, s3-uploader
state   string A filter for tasks based on state. If not specified, all tasks for agents are returned. pending, inProgress
size   int The number of tasks to retrieve. The default value is 10. 25

14.1.5.2.2. Responses

Response Content Type: JSON Returns an array of TaskResponse objects:

Name Type Description Examples
taskId GUID A unique ID representing the task 0a12ef41-e9d9-4a92-a3e6-2e1be82151f7
jobId string A unique ID representing a job generated by Clara 53c398f291304a58bee886075d5c33dd
pipelineId string A unique ID representing a pipeline published by the user 85065833c5554080afd1328a99cfb762
payloadId string A unique ID representing the payload associated with the job where the results are stored 7a21712c334c482db033489548009a17
parameters string Arguments that will be passed to the exporter. Note that parameters comes from the --data switch defined in the pipeline definition and must be a valid JSON-formatted string. ["PACS1", "ReadingWorkstation"], mys3bucketname
state Enum string The current state of the task. See the Task States section for a complete list. Pending, Failed
retries int The number of retries performed on the task 3
uris string[] An array of URIs to locate results in the specified payload ["/recon-op/mhd/series1.mhd",  "/recon-op/mhd/series1.raw","/dicom-op/series1.dcm"]
Code Description
200 Tasks have been found for the specified agent.
204 No tasks have been found for the specified agent.

14.1.5.2.3. Example Request

curl http://localhost:8088/api/tasks/dicom/pending

14.1.5.2.4. Example Response

[
  {
    "taskId": "85065833-c555-4080-afd1-328a99cfb762",
    "jobId": "53c398f291304a58bee886075d5c33dd",
    "pipelineId": "7a21712c334c482db033489548009a17",
    "payloadId": "dicom-export",
    "parameters": "[\"orthanc-pacs\",\"modality-viewer-2\"]",
    "state": "Pending",
    "retries": 1,
    "agent": "dicom",
    "uris": [
      "dicom-op/series1.dcm",
      "dicom-op/series2.dcm"
    ]
  },
  {
    "taskId": "8c7121e9-c88a-43d1-abce-df5f95de76bd",
    "jobId": "3478c9d832434b12ae7f1a36cce2f592",
    "pipelineId": "7a21712c334c482db033489548009a17",
    "payloadId": "dicom-export",
    "parameters": "[\"dcm4chee-pacs\",\"modality-viewer-5\"]",
    "state": "Pending",
    "agent": "dicom",
    "retries": 0,
    "uris": [
      "dicom-export/study123/series456.dcm",
      "dicom-export/study234/series567.dcm"
    ]
  }
]

14.1.5.3. PUT /api/tasks/success/[taskId]

Marks the specified task as Succeeded.

14.1.5.3.1. Parameters

Name Required Type Description Example
taskId
GUID The unique ID representing the task 85065833-c555-4080-afd1-328a99cfb762

14.1.5.3.2. Responses

Response Content Type: N/A

Code Description
200 Task has been marked as successful.
404 No matching task has been found.

14.1.5.3.3. Example Request

curl -i -H "Transfer-Encoding: chunked" -X PUT http://localhost:8088/api/tasks/success/85065833-c555-4080-afd1-328a99cfb762

# -i Prints HTTP response code
# -H HTTP header
# -X Request command

14.1.5.4. PUT /api/tasks/failure/[taskId]

Marks the specified task as Pending or Failed.

14.1.5.4.1. Parameters

Name Required Type Description Example
taskId
GUID The unique ID representing the task 85065833-c555-4080-afd1-328a99cfb762
retryLater   bool A flag indicating that the task will be retried at a later time. false

14.1.5.4.2. Responses

Response Content Type: N/A

Code Description
200 Tasks have been marked as Pending if retryLater is set to true. They are marked Failed otherwise.
404 No matching tasks have been found.

14.1.5.4.3. Example Request

# Mark task as failure and retry later
curl -i --data-raw '{ "retryLater": true }' -H "Content-Type: application/json" -X PUT http://localhost:8088/api/tasks/failure/b52c6172-37ed-421b-b731-6bbd5012f0bf

# Mark task as failure without retry
curl -i --data-raw '{ "retryLater": false }' -H "Content-Type: application/json" -X PUT http://localhost:8088/api/tasks/failure/d5746994-a357-4d52-b6f4-f68128883c95

# -i Prints HTTP response code
# -d HTTP PUT data
# -H HTTP header
# -X Request command

14.1.6. Database

The Results Service uses sqlite to persistently store results. It is built using Microsoft Entity Framework Core with the Code First approach.

Entity Framework Core supports many other database providers and may be easily swapped by configuring ./Data/ResultsContext.cs and ./Data/*Configuration.cs files.

Reference: Entity Framework Core Docs

14.1.7. License

Licenses and model files are available. They can be pulled as part of the procedure described above or are available in the Clara Deploy SDK. By pulling and using the container, you accept the terms and conditions of these licenses.

14.1.7.1. Third Party Licenses