11.2. Results Service

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

The service enables pipelines to register results for an agent. Each received request is converted into a task and queued in the service. The exporters could simply query the Tasks API for any results that it’s assigned for.

11.2.1. Task States

Each Task stored in the Results Service has a State associated and State is defined as follows:

State

Value

Description

Pending

1

Task is waitng for an agent to process.

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 section for additional details.

11.2.2. Definitions

Term

Definition

Agent or Exporter

An agent or exporter is a service or process that delivers results generated by a pipeline to an external service or device.

Agent Name

A name used to uniquely identify an agent used by the services to register results or retrieve tasks. The name allows alphanumeric and hyphen (-) characters, must begin with a letter and must not end with a hyphen.

11.2.3. Requirements

This container requires Docker 18.09.2 or higher.

11.2.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.

11.2.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.

#. Open a command prompt and paste the pull command. The pulling of the container image begins. Ensure the pull completes successfully before proceeding to the next step. #.

Create a data directory with the following command:

mkdir -p data

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

  1. Create a network for the Results Service.

    docker network create claranet
    
  2. Configure the Results Service.

  3. 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 container’s port to host (here, we map 5000 on the host to 80 in the container)

    • -v mounts the host folder to container folder

    • <x.x.x&gt; 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 Usages for additional details.

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

    docker stop resultsservice
    docker network rm claranet
    

11.2.5. API Usage

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

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

11.2.5.1.1. Parameters

Name

Required

Type

Description

Example

pipelineId

string

The unique ID representing a pipeline published by the user.

85065833-c555-4080-afd1-328a99cfb762

jobId

string

The unique ID representing the job generated by Clara.

53c398f2-9130-4a58-bee8-86075d5c33dd

payloadId

string

The unique ID representing the payload associated with a job where the results are stored.

7a21712c-334c-482d-b033-489548009a17

agentName

string (max length 32)

The name of the exporter that will be responsible for delivering the results. Note: 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: parameters comes from the pipeline definition with the --data switch and must be a valid JSON formatted string.

["PACS1", "ReadingWorkstation"], mys3bucketname

uris

string[]

Array of URIs to locate results in the specified payload.

["/recon-op/mhd/series1.mhd",  "/recon-op/mhd/series1.raw","/dicom-op/series1.dcm"]

11.2.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.

11.2.5.1.3. Example Request

curl -i \
     -X POST "http://localhost:5000/api/Tasks/register/erf"  \
     -H "accept: application/json" \
     -H "Content-Type: application/json-patch+json" \
     -d "{ \"pipelineId\": \"89b5e6ce-3eb2-4c82-b7fd-4130ae5e2db0\", \
       \"jobId\": \"05a63002-71ba-49a2-9bc8-0fd4af328b6c\", \
       \"payloadId\": \"6e4dd28c-e789-46fc-8978-73c58cf623e6\", \
       \"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

11.2.5.1.4. Example Response

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

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

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

11.2.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

Filters tasks based on state. If not specified, all tasks for agents are returned.

pending, inProgress

size

int

Number of tasks to retrieve. Default is 10.

25

11.2.5.2.2. Responses

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

Name

Type

Description

Examples

taskId

GUID

The unique ID representing the task.

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

jobId

string

The unique ID representing the job generated by Clara.

53c398f2-9130-4a58-bee8-86075d5c33dd

pipelineId

string

The unique ID representing a pipeline published by the user.

85065833-c555-4080-afd1-328a99cfb762

payloadId

string

The unique ID representing the payload associated with a job where the results are stored.

7a21712c-334c-482d-b033-489548009a17

parameters

string

Arguments that will be passed to the exporter. Note: 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

Current state of the task. See Task States for complete list.

Pending, Failed

retries

int

Number of retries performed on the task.

3

uris

string[]

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 found for the specified agent.

204

No tasks found for the specified agent.

11.2.5.2.3. Example Request

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

11.2.5.2.4. Example Response

[
  {
    "taskId": "85065833-c555-4080-afd1-328a99cfb762",
    "jobId": "53c398f2-9130-4a58-bee8-86075d5c33dd",
    "pipelineId": "7a21712c-334c-482d-b033-489548009a17",
    "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": "3478c9d8-3243-4b12-ae7f-1a36cce2f592",
    "pipelineId": "7a21712c-334c-482d-b033-489548009a17",
    "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"
    ]
  }
]

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

Marks the specified task Succeeded.

11.2.5.3.1. Parameters

Name

Required

Type

Description

Example

taskId

GUID

The unique ID representing the task

85065833-c555-4080-afd1-328a99cfb762

11.2.5.3.2. Responses

Response Content Type: N/A

Code

Description

200

Task marked as successful.

404

No matching task found

11.2.5.3.3. Example Request

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

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

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

Marks the specified task Pending or Failed.

11.2.5.4.1. Parameters

Name

Required

Type

Description

Example

taskId

GUID

The unique ID representing the task

85065833-c555-4080-afd1-328a99cfb762

retryLater

bool

Indicates the task will be retried at a later time. true if not specified.

false

11.2.5.4.2. Responses

Response Content Type: N/A

Code

Description

200

Tasks marked as Pending if retryLater is set to true. Marked Failed otherwise.

404

No matching task found

11.2.5.4.3. Example Request

# Mark task as successful
curl -i -d true -H "Content-Type: application/json" -X PUT http://localhost:5000/api/tasks/failure/b52c6172-37ed-421b-b731-6bbd5012f0bf

# Mark task as failed
curl -i -d false -H "Content-Type: application/json" -X PUT http://localhost:5000/api/tasks/failure/b52c6172-37ed-421b-b731-6bbd5012f0bf

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

11.2.6. Database

Results Service uses sqlite to persist results and is built using Microsoft Entity Framework Core with Code First approach.

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

Reference: Entity Framework Core Docs

11.2.7. License

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

11.2.7.1. Third Party Licenses

11.2.8. Suggested Reading

For Release Notes, Getting Started Guide and Clara Deploy SDK, please visit the NVIDIA Developer forum at https://developer.nvidia.com/clara. Use the NVIDIA Devtalk forum at https://devtalk.nvidia.com/default/board/362/clara-sdk/ for questions regarding this release.