Task

Tasks are essential to reporting workflow inside Atticus. There is one relevant Task in API integrations:

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.

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.
- ready: Task is ready to be completed by a practitioner.
  Creating a task with this status requires a questionnaire input.
- 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.
On create, only draft and ready are accepted: in-progress and completed return 501 Not Implemented, and failed returns 400. Omitting the status returns a 422.
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. Note that inputs are only processed when the task is created with status: "ready": a questionnaire input provided on a draft task is ignored and will not be visible when reading the task back.
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`
Post Submit Redirect	optional	URL to send the user back to once they submit the report. The resulting response is appended as a `response` query parameter. A session's `post_submit_redirect` takes precedence over this input.	url	`post-submit-redirect`

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`
Composition	References a resource extracted from the completed form — the report Composition, and any `Observation` or other resource the template extracts	Reference to the extracted resource	`composition`
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. A task created as draft stays draft, even when a questionnaire input is provided.
ready The task was created with status: "ready" and a questionnaire input, or a practitioner selected a questionnaire 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.

Posting a task whose body identifier already exists returns a 409 Conflict (issue code duplicate) with a Location header pointing to the existing task. To create a task only if it doesn't exist yet, use a conditional create: POST /Task?identifier=<token> returns 200 with the existing task on a match, or 201 when a new task is created.

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",
    "identifier": [
        {
            "system": "http://hospital.example.com/task-id",
            "value": "complete-questionnaire"
        }
    ],
    "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": {
    "text": "CT scan report",
    "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": "https://tiro.health/fhir/Questionnaire/ct-scan-report|1.0.0"
    }
  ],
  "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 with a specific identifier.

Supported search parameters

identifier: Filter tasks by identifier
code: Filter tasks by type (use code:text to match on the code's text)
subject: Filter tasks by patient reference (e.g. subject=Patient/123)
encounter: Filter tasks by encounter reference
output: Filter tasks by output reference
_id: Filter tasks by resource id
sort, offset, limit: Control ordering and pagination of the results

Unsupported parameters (such as status or patient) are silently ignored rather than rejected. A query containing only ignored parameters returns all tasks in the tenant, up to the default limit of 1000.

Request

GET

/Task?subject=Patient/123

curl -G https://reports.tiro.health/fhir/r5/Task \
--data-urlencode "subject=Patient/123" \
-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": {
          "text": "CT scan report",
          "coding": [
            {
              "system": "http://fhir.tiro.health/CodeSystem/task-type",
              "code": "complete-questionnaire"
            }
          ]
        },
        "status": "ready",
        "for": {
          "reference": "Patient/123"
        },
        "input": [
          {
            "type": {
              "coding": [
                {
                  "system": "http://fhir.tiro.health/CodeSystem/task-input",
                  "code": "questionnaire"
                }
              ]
            },
            "valueCanonical": "https://tiro.health/fhir/Questionnaire/ct-scan-report|1.0.0"
          }
        ]
      }
    }
  ]
}