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.

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

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.

This container requires Docker 18.09.2 or higher.

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:

   Copy

   Copied!

               
   
               
   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.

   Copy

   Copied!

               
   
               
   docker network create claranet
           

6. Configure the Results Service.

7. Run the Results Service with the following commands:

   Copy

   Copied!

               
   
               
   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:

   Copy

   Copied!

               
   
               
   docker stop resultsservice
   docker network rm claranet
           

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

14.1.5.1.2. Responses

Response Content Type: JSON

Returns a string ID representing the newly created task.

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

14.1.5.2.2. Responses

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

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

14.1.5.3.2. Responses

Response Content Type: N/A

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

14.1.5.4.2. Responses

Response Content Type: N/A

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
        

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

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

• Microsoft .NET Core MIT
• Microsoft Entity Framework Core Apache 2.0
• Microsoft.Extensions Apache 2.0
• Serilog Apache 2.0
• YamlDotNet MIT