Task

Tasks are essential to reporting workflow inside Atticus. There are two types of tasks to distinguish:

Complete Questionnaire tasks: a programmatic way of telling Atticus that a practitioner has to create and complete a report. This report will be attached as a QuestionnaireResponse to the output of the task.
Process Response tasks: a programmatic way of telling Atticus that it should process a report in a specific way. This task can cover "forwarding to an EHR" or "loading into a data warehouse".

In the following sections, we'll dive into the data structure of Tasks and the different Task endpoints you can use to manage tasks programmatically.

The 'Complete Questionnaire' Task model

The Complete Questionnaire Task model allows systems to create structured reporting tasks in Atticus that practitioners need to complete. These tasks appear in practitioners' worklists and guide them through completing specific questionnaires (forms).

Properties

The Task model conforms to the FHIR Task resource and implements the SDC Task Questionnaire profile. The following properties are supported:

Name
resourceType*
Type
'Task'
Description
The FHIR resource type. This must be set to 'Task'.
Name
intent*
Type
code
Description
The intent of the task. For Complete Questionnaire tasks, this is must be set to 'order'.
Name
description
Type
string
Description
A human-readable description of the task, displayed to practitioners in their worklists.
Name
code*
Type
CodeableConcept
Description
Identifies the task type. For Complete Questionnaire tasks, this should be set to the code complete-questionnaire with system http://fhir.tiro.health/CodeSystem/task-type
Note that the text property of the code is used as title of the task.
Name
identifier
Type
Identifier[]
Description
An array of identifiers for this task. This is useful for referencing tasks in external systems. More information about identifiers can be found here.
Name
status
Type
code
Description
The current status of the task. Possible values include:
- draft: Task is created but not yet ready for action.
  This occurs when a questionnaire input is missing.
- ready: Task is ready to be completed by a practitioner.
- in-progress: Task is being worked on. The questionnaire-response output is available but may not be complete.
- completed: Task has been completed successfully including the forwarding to other systesm like the EHR.
The status affects how the task appears in practitioners' worklists (the reports overview page) and is automatically updated as they interact with it.
Name
for*
Type
Reference(Patient)
Description
A FHIR Reference to the patient who is the subject of the questionnaire to be completed.
Name
encounter
Type
Reference(Encounter)
Description
A FHIR Reference to the encounter during which the questionnaire should be completed.
Name
input
Type
BackboneElement[]
Description
Input parameters for the task. See Task Inputs and Output Types section below for details on available input types.
Some parameters like questionnaire can be completed by a practitioner through the user interface.
Name
output
Type
BackboneElement[]
Description
Output parameters from the task execution. This captures the results produced by the task. This can only be added by the Tiro.health and should not be provided by the client.

Input and Output Types

The Task resource uses the input and output arrays to configure the task and capture the results of the task execution. Each input or output has a type that identifies its purpose and a value[x] that contains the actual data.

The following table details the available input types for Complete Questionnaire tasks:

Input Type	Required	Purpose	Data Type	Code
Questionnaire	optional	Specifies which questionnaire form the practitioner should complete	Canonical reference to a Questionnaire	`questionnaire`
Initial Response	optional	Provides a partial QuestionnaireResponse to pre-fill the form with initial data	Reference to a QuestionnaireResponse	`initial-response`

All codes assume to have system http://fhir.tiro.health/CodeSystem/task-input

Example of a task input for specifying a questionnaire:

{
  "type": {
    "coding": [
      {
        "system": "http://fhir.tiro.health/CodeSystem/task-input",
        "code": "questionnaire"
      }
    ]
  },
  "valueCanonical": "http://templates.tiro.health/templates/adfb513febd7|1.0.1"
}

The following table details the available output types for Complete Questionnaire tasks:

Output Type	Purpose	Data Type	Coding
QuestionnairResponse	Contains the reference to the completed form	Reference to QuestionnaireResponse	`questionnaire-response`
OperationOutcome	Contains errors or issues encountered during task processing	Reference to OperationOutcome	`operation-outcome`

All codes assume to have system http://fhir.tiro.health/CodeSystem/task-output

Example of a task output containing a completed questionnaire response:

{
  "type": {
    "coding": [
      {
        "system": "http://fhir.tiro.health/CodeSystem/task-output",
        "code": "questionnaire-response"
      }
    ]
  },
  "valueReference": {
    "reference": "QuestionnaireResponse/789"
  }
}

Task Status Workflow

The status of a Complete Questionnaire task progresses through several stages as practitioners interact with it:

draft Task appears in practitioners' worklists as available for completion The questionnaire input is optional, if provided the task status will be set to ready automatically.
ready The questionnaire input is present either through the API or through the user interface. The task is ready to be fullfilled.
in-progress Practitioner has started filling out the questionnaire. A incomplete QuestionnairResponse is present in the output.
completed Practitioner has successfully submitted the completed questionnaire. All processing steps have been full-filled.

Each status change affects how and where the task appears in the practitioner's interface.

POST/Task

Request a Questionnaire to be completed

Prerequesities: This request requires a Patient resource to be present.

This endpoint allows you to create a new Complete Questionnaire task. The task will appear in practitioners' worklists based on the specified parameters.

Request

POST

/Task

curl -X POST https://reports.tiro.health/fhir/r5/Task \
-H "Authorization: Basic {apikey}" \
-H "Content-Type: application/fhir+json" \
-d '{
    "resourceType": "Task",
    "intent": "order",
    "status": "draft",
    "description": "Task tracking the completion of a CT scan report for patient with id='123'.",
    "code": {
        "text": "CT scan report",
        "coding": [
            {
                "system": "http://fhir.tiro.health/CodeSystem/task-type",
                "code": "complete-questionnaire"
            }
        ]
    },
    "for": {
        "reference": "Patient/123"
    }
}'

Response

{
  "resourceType": "Task",
  "id": "456",
  "meta": {
    "lastUpdated": "2023-04-01T14:30:22Z",
    "extension": [
      {
        "url": "http://hl7.org/fhir/StructureDefinition/firstCreated",
        "valueInstant": "2023-03-28T09:12:45Z"
      }
    ]
  },
  "intent": "order",
  "description": "Complete CT scan report for patient",
  "code": {
    "text": "CT scan report",
    "coding": [
      {
        "system": "http://fhir.tiro.health/CodeSystem/task-type",
        "code": "complete-questionnaire"
      }
    ]
  },
  "status": "draft",
  "for": {
    "reference": "Patient/123"
  }
}

GET/Task/:id

Get a Task

This endpoint allows you to retrieve a specific task by its ID. This is useful for checking the status of a task or retrieving the completed QuestionnaireResponse once the task is completed.

Request

GET

/Task/456

curl -G https://reports.tiro.health/fhir/r5/Task/456 \
-H "Authorization: Basic {{apikey}}" \
-H "Content-Type: application/fhir+json"

Response

{
  "resourceType": "Task",
  "id": "456",
  "meta": {
    "lastUpdated": "2023-04-01T14:30:22Z",
    "extension": [
      {
        "url": "http://hl7.org/fhir/StructureDefinition/firstCreated",
        "valueInstant": "2023-03-28T09:12:45Z"
      }
    ]
  },
  "intent": "order",
  "description": "Complete CT scan report for patient",
  "code": {
    "coding": [
      {
        "system": "http://fhir.tiro.health/CodeSystem/task-type",
        "code": "complete-questionnaire"
      }
    ]
  },
  "status": "completed",
  "for": {
    "reference": "Patient/123"
  },
  "input": [
    {
      "type": {
        "coding": [
          {
            "system": "http://fhir.tiro.health/CodeSystem/task-input",
            "code": "questionnaire"
          }
        ]
      },
      "valueCanonical": "Questionnaire/ct-scan-report"
    }
  ],
  "output": [
    {
      "type": {
        "coding": [
          {
            "system": "http://fhir.tiro.health/CodeSystem/task-output",
            "code": "questionnaire-response"
          }
        ]
      },
      "valueReference": {
        "reference": "QuestionnaireResponse/789"
      }
    }
  ]
}

GET/Task

Search for Tasks

This endpoint allows you to search for tasks based on various criteria. This is useful for finding tasks for a specific patient or tasks of a certain status.

Common search parameters

status: Filter tasks by status
patient: Filter tasks by patient reference
code: Filter tasks by type
identifier: Filter tasks by identifier

Request

GET

/Task?patient=Patient/123&status=requested

curl -G https://reports.tiro.health/fhir/r5/Task \
--data-urlencode "patient=Patient/123" \
--data-urlencode "status=completed" \
--data-urlencode "code=complete-questionnaire" \
-H "Authorization: Basic {{apikey}}" \
-H "Content-Type: application/fhir+json"

Response

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://reports.tiro.health/fhir/r5/Task/456",
      "resource": {
        "resourceType": "Task",
        "id": "456",
        "meta": {
          "lastUpdated": "2023-04-01T14:30:22Z",
          "extension": [
            {
              "url": "http://hl7.org/fhir/StructureDefinition/firstCreated",
              "valueInstant": "2023-03-28T09:12:45Z"
            }
          ]
        },
        "intent": "order",
        "description": "Complete CT scan report for patient",
        "code": {
          "coding": [
            {
              "system": "http://fhir.tiro.health/CodeSystem/task-type",
              "code": "complete-questionnaire"
            }
          ]
        },
        "status": "requested",
        "for": {
          "reference": "Patient/123"
        },
        "input": [
          {
            "type": {
              "coding": [
                {
                  "system": "http://fhir.tiro.health/CodeSystem/task-input",
                  "code": "questionnaire"
                }
              ]
            },
            "valueCanonical": "Questionnaire/ct-scan-report"
          }
        ]
      }
    }
  ]
}