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

13.1.1. Cleanup Service

The Cleanup Service, which is part of the Results Service, is responsible for removing any payloads from the system after the results are exported. The Cleanup Service can be enabled or disabled via appsettings.json. The service removes jobs eight hours after all tasks are in the Succeeded or Failed state.

By default, Cleanup Service would retain processed results for 8 hours. 8 hours after all registered tasks are exported, its associated payloads will be removed from the disk. This value may be adjusted in the configuration file in ~/.clara/charts/clara/files/appsettings.json.

...
"Cleanup": {
  "enabled": true,
  "retainDataForMinutes": 480
},
...

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

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

13.1.4. Requirements

This container requires Docker 18.09.2 or higher.

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

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

13.1.6. API Usage

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

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

13.1.6.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"]

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

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

13.1.6.1.4. Example Response

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

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

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

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

13.1.6.2.3. Example Request

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

13.1.6.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"
    ]
  }
]

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

Marks the specified task as Succeeded.

13.1.6.3.1. Parameters

Name

Required

Type

Description

Example

taskId

GUID

The unique ID representing the task

85065833-c555-4080-afd1-328a99cfb762

13.1.6.3.2. Responses

Response Content Type: N/A

Code

Description

200

Task has been marked as successful.

404

No matching task has been found.

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

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

Marks the specified task as Pending or Failed.

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

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

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

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

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

13.1.8.1. Third Party Licenses