Argonaut Questionnaire Implementation Guide (Release 1.0.0 )

This page is part of the Argonaut Questionnaire Implementation Guide (v1.0.0: Release) based on FHIR R3. This is the current published version. For a full list of available versions, see the Directory of published versions

Static Forms

Introduction

The Argonaut Questionnaire Implementation Guide defines a series of interactions which cover the basic workflow for the creation, discovery and retrieval of simple static text-based forms using FHIR Questionnaire and QuestionnaireResponse and the FHIR API. The reader is encouraged to familiarize herself with the capabilities of the Questionnaire and QuestionnaireResponse Response resources by reviewing the guidance given in the FHIR specification and the Argonaut Questionnaire Profile and Argonaut QuestionnaireResponse Profile pages.

Each assessment tool (i.e., set of questions and answer choices) is created once as FHIR Questionnaires and centrally stored in an Assessment Bank which can be accessed by the Provider EHR. The Client Application can then render the form for the end user to complete. The form responses are captured and processed by the Client and can be stored using the QuestionnaireResponse in an Answer Bank and subsequently retrieved by the Providers for review. Although out of scope for this guide, these results can be aggregated and shared within or across systems.

These basic workflow steps and API are detailed below. This guidance covers more basic scenarios, but can be scaled up towards more complex scenarios ( for example, see the Structured Data Capture Initiative). Note that the search guidance below is applicable to the completed Adaptive forms as well.

Example Scenario

This simple scenario serves as an effective means to describe the Argonaut Questionnaire basic workflow and API

A Jurisdiction (e.g, state or region) publicly funds a program to improve population health. The program is instituted and a set of standard assessments are to filled out by the program participants (“subjects”) periodically in order to monitor the program’s success or failure.

Example list of Assessment Categories:

  1. Demographic information
  2. Physical health review
  3. Substance use review
  4. Housing assessment
  5. Suicide risk assessment
  6. Universal screening using depression screening

Each assessment tool (i.e., set of questions and answer choices) is created once as FHIR Questionnaires and centrally stored in an “Assessment Bank” which can be accessed the program participants (provider EHRS). The provider can then use them to create online questionnaires for their patients. The responses are captured and processed by the provider EHRS and retrieved by the providers for review. These results are shared with the Agency overseeing the program.

Workflow Steps

Form Author Creates Assessment

Before an assessment can retrieved it must be created. This step MAY include updating or deprecation of an assessment. The Form Author/Editor creates a Questionnaire resource based on a set of assessment questions and answers and associated scores as defined by the program coordinators. The Questionnaire conforms to the Argonaut Questionnaire Profile. How these questions and answer and scores are defined and how the Questionnaire is created are out of scope.

Form Author Posts to Assessment Bank

st-step1.jpg

The Author/Editor is able to upload the Questionnaires to a FHIR server which serves as a repository where all the program participants can search and download the standard assessment when they need them. Multiple version of each assessment may be available.

This transaction use the standard FHIR RESTful API to created, update, and delete Questionnaires from the Assessment bank:

APIs

The following Argonaut Questionnaire artifacts are used in this transaction:

Usage

To create a Questionnaire:

POST [base]/Questionnaire/...

Request

POST http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 201 (Created)
Content-Type: application/fhir+json; charset=utf-8
Content-Location: http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire/c644fc509ad84aebb8315b4c587bfcd0/_history/1
[other headers]

    
{
   "resourceType": "Questionnaire",
   "id": "c644fc509ad84aebb8315b4c587bfcd0",
   "meta": {
      "versionId": "1",
      "lastUpdated": "2019-02-13T08:03:46.927+00:00",
      "profile": [
         "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
      ]
   },
   "text": {
      "status": "generated",
      "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">\r\n\t<b>Argonaut Questionnaire Sampler</b>\r\n\t<hr/>\r\n\t\t<span style=\"color: gray;\">Publisher:</span> Argonaut Project\r\n</div>\r\n"
   },
   "extension": [
      {
         "url": "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/extension-timeLimit",
         "valueDuration": {
            "value": 5,
            "unit": "minute",
        ...[snipped for brevity]....


To update a Questionnaire:

PUT [base]/Questionnaire/[id]

Request

PUT http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire/questionnaire-example-search

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
Content-Location: http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire/questionnaire-example-search/_history/17
[other headers]

    
{
   "resourceType": "Questionnaire",
   "id": "questionnaire-example-search",
   "meta": {
      "versionId": "17",
      "lastUpdated": "2019-02-13T08:03:48.115+00:00",
      "profile": [
         "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
      ]
   },
   "text": {
      "status": "generated",
      "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">\r\n\t<b>Argonaut Questionnaire Sampler</b>\r\n\t<hr/>\r\n\t\t<span style=\"color: gray;\">Publisher:</span> Argonaut Project\r\n</div>\r\n"
   },
   "extension": [
      {
         "url": "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/extension-timeLimit",
         "valueDuration": {
            "value": 5,
            "unit": "minute",
        ...[snipped for brevity]....


to delete a Questionnaire:

DELETE [base]/Questionnaire/[id]

Request

DELETE http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire/questionnaire-example-delete

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 204 (No Content)
[other headers]


Provider EHR Fetches Form

st-step2.jpg

When it is time to perform an assessment of the program participants(subjects), the Provider EHR fetches the appropriate Questionnaire(s) from the Assessment-Bank.

The standard FHIR RESTful search API is used with the following standard and custom search parameters:

and the following optional search parameters

APIs

The following Argonaut Questionnaire artifacts are used in this transaction:

Note that all ValueSets used are contained resources within the Questionnaire

Usage

Fetching a single Questionnaire:

  • based on its id:

    GET [base]/Questionnaire/[id] or GET [base]/Questionnaire?_id=[id]

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?_id=questionnaire-example-search

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
Content-Location: http://sqlonfhir-stu3.azurewebsites.net/fhir/Bundle/urn:uuid:ce7769e8aac54f5084f059626d6c32de
[other headers]

    
{
   "resourceType": "Bundle",
   "id": "urn:uuid:ce7769e8aac54f5084f059626d6c32de",
   "meta": {
      "lastUpdated": "2019-02-13T08:38:57.477+00:00"
   },
   "type": "searchset",
   "total": 1,
   "link": [
      {
         "relation": "self",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?_id=questionnaire-example-search&_snapshot=636856439374771977"
      }
   ],
   "entry": [
      {
         "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire/questionnaire-example-search",
         "resource": {
            "resourceType": "Questionnaire",
            "id": "questionnaire-example-search",
            "meta": {
               "versionId": "19",
               "lastUpdated": "2019-02-13T08:37:05.202+00:00",
        ...[snipped for brevity]....


  • based on its url (note the QuestionnaireResponse uses the url to reference the assessment upon which it is based):

    GET [base]/Questionnaire?url=[uri]

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?url=http%3A%2F%2Ffhir.org%2Fguides%2Fargonaut-questionnaire%2FQuestionnaire%2Fquestionnaire-example-search

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
Content-Location: http://sqlonfhir-stu3.azurewebsites.net/fhir/Bundle/urn:uuid:334db1311eea4e4b80f5560aed8b6d1f
[other headers]


{
   "resourceType": "Bundle",
   "id": "urn:uuid:334db1311eea4e4b80f5560aed8b6d1f",
   "meta": {
      "lastUpdated": "2019-02-13T08:38:57.977+00:00"
   },
   "type": "searchset",
   "total": 1,
   "link": [
      {
         "relation": "self",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?url=http%3A%2F%2Ffhir.org%2Fguides%2Fargonaut-questionnaire%2FQuestionnaire%2Fquestionnaire-example-search&_snapshot=636856439379772204"
      }
   ],
   "entry": [
      {
         "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire/questionnaire-example-search",
         "resource": {
            "resourceType": "Questionnaire",
            "id": "questionnaire-example-search",
            "meta": {
               "versionId": "19",
               "lastUpdated": "2019-02-13T08:37:05.202+00:00",
    "profile": [
        "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
    ]
    },
    "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">\r\n\t<b>Argonaut Questionnaire Sampler</b>\r\n\t<hr/>\r\n\t\t<span style=\"color: gray;\">Publisher:</span> Argonaut Project\r\n</div>\r\n"
    },
    "extension": [
    {
        "url": "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/extension-timeLimit",
        "valueDuration": {
            "value": 5,
            "unit": "minute",
            "system": "http://unitsofmeasure.org",
            "code": "min"
        }
    }
    ],
    "url": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-search",
        ...[snipped for brevity]....


  • based on its title (the supplied parameter can equals or starts with the title ):

    GET [base]/Questionnaire?title=[title]

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?title=Argonaut+Questionnaire+Sampler

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
Content-Location: http://sqlonfhir-stu3.azurewebsites.net/fhir/Bundle/urn:uuid:a12707826ee74b3f8787c87c437fe583
[other headers]

    
{
   "resourceType": "Bundle",
   "id": "urn:uuid:a12707826ee74b3f8787c87c437fe583",
   "meta": {
      "lastUpdated": "2019-02-13T08:38:58.57+00:00"
   },
   "type": "searchset",
   "total": 26,
   "link": [
      {
         "relation": "self",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?title=Argonaut+Questionnaire+Sampler&_snapshot=636856439385709973"
      },
      {
         "relation": "first",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?title=Argonaut+Questionnaire+Sampler&_snapshot=636856439385709973"
      },
      {
         "relation": "next",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?title=Argonaut+Questionnaire+Sampler&_snapshot=636856439385709973&_page=1"

        ...[snipped for brevity]....


  • based on its title and version:

    GET [base]/Questionnaire?title=[title]&version=[version]

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?title=Argonaut+Questionnaire+Sampler&version=3.0.0

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
Content-Location: http://sqlonfhir-stu3.azurewebsites.net/fhir/Bundle/urn:uuid:b5e40cf4865f46b3a00524b3dac8e364
[other headers]


{
   "resourceType": "Bundle",
   "id": "urn:uuid:b5e40cf4865f46b3a00524b3dac8e364",
   "meta": {
      "lastUpdated": "2019-02-13T08:38:59.164+00:00"
   },
   "type": "searchset",
   "total": 1,
   "link": [
      {
         "relation": "self",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?title=Argonaut+Questionnaire+Sampler&version=3.0.0&_snapshot=636856439391647462"
      }
   ],
   "entry": [
      {
         "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire/questionnaire-example-search",
         "resource": {
            "resourceType": "Questionnaire",
            "id": "questionnaire-example-search",
            "meta": {
               "versionId": "19",
               "lastUpdated": "2019-02-13T08:37:05.202+00:00",
               "profile": [
        "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
    ]
    },
    "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">\r\n\t<b>Argonaut Questionnaire Sampler</b>\r\n\t<hr/>\r\n\t\t<span style=\"color: gray;\">Publisher:</span> Argonaut Project\r\n</div>\r\n"
    },
    "extension": [
    {
        "url": "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/extension-timeLimit",
        "valueDuration": {
            "value": 5,
            "unit": "minute",
            "system": "http://unitsofmeasure.org",
            "code": "min"
        }
    }
    ],
    "url": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-search",
    "identifier": [
    {
        "system": "http://acme.org/q-identifiers",
        "value": "questionnaire-example-sampler"
    }
    ],
    "version": "3.0.0",
    "title": "Argonaut Questionnaire Sampler",
    "status": "draft",
        ...[snipped for brevity]....


Searching for all the active Questionnaires:

GET [base]/Questionnaire?status=active

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?status=active

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
Content-Location: http://sqlonfhir-stu3.azurewebsites.net/fhir/Bundle/urn:uuid:abcbf2f079c74fab991edf1ad77cdbc6
[other headers]

    
{
   "resourceType": "Bundle",
   "id": "urn:uuid:abcbf2f079c74fab991edf1ad77cdbc6",
   "meta": {
      "lastUpdated": "2019-02-13T08:38:59.852+00:00"
   },
   "type": "searchset",
   "total": 23,
   "link": [
      {
         "relation": "self",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?status=active&_snapshot=636856439398527001"
      },
      {
         "relation": "first",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?status=active&_snapshot=636856439398527001"
      },
      {
         "relation": "next",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?status=active&_snapshot=636856439398527001&_page=1"
      },
      {
         "relation": "last",
        ...[snipped for brevity]....


Searching for all the active Questionnaires by a particular publisher :

GET [base]/Questionnaire?status=active&publisher=[publisher]

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?_count=75&status=draft&publisher=Argonaut+Project

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
[other headers]


{
   "resourceType": "Bundle",
   "id": "urn:uuid:0037e580968f40d494a9afcc19e3ce2d",
   "meta": {
      "lastUpdated": "2019-02-27T02:59:42.676+00:00"
   },
   "type": "searchset",
   "total": 30,
   "link": [
      {
         "relation": "self",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?_count=75&status=draft&publisher=Argonaut+Project&_snapshot=636868331826761687"
      }
   ],
   "entry": [
      {
         "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire/questionnaire-example-search",
         "resource": {
            "resourceType": "Questionnaire",
            "id": "questionnaire-example-search",
            "meta": {
               "versionId": "19",
               "lastUpdated": "2019-02-13T08:37:05.202+00:00",
               "profile": [
                  "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
               ]
            },
            "text": {
               "status": "generated",
               "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><b>Argonaut Questionnaire Sampler</b><hr /><span style=\"color: gray;\">Publisher:</span> Argonaut Project\r\n</div>"
            },
            "extension": [
               {
                  "url": "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/extension-timeLimit",
                  "valueDuration": {
                     "value": 5,
                     "unit": "minute",
                     "system": "http://unitsofmeasure.org",
                     "code": "min"
                  }
               }
            ],
            "url": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-search",
            "identifier": [
               {
                  "system": "http://acme.org/q-identifiers",
                  "value": "questionnaire-example-sampler"
               }
            ],
            "version": "3.0.0",
            "title": "Argonaut Questionnaire Sampler",
            "status": "draft",
            "date": "2018-07-26",
            "publisher": "Argonaut Project",
            "useContext": [
               {
                  "code": {
                     "system": "http://hl7.org/fhir/usage-context-type",
                     "code": "task",
                     "display": "Workflow Task"
                  },
                  "valueCodeableConcept": {
                     "coding": [
                        {
                           "system": "http://acme.org",
        ...[snipped for brevity]....


Searching for a collection of Questionnaires based on context-type and context-value(think category):

GET [base]/Questionnaire?context-code-value=[code]&[value]

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire?context-code=task&value=example

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
Content-Location: http://sqlonfhir-stu3.azurewebsites.net/fhir/Bundle/urn:uuid:f43f23115d954cd28716556d7bb26287
[other headers]


{
    "resourceType": "Bundle",
    "id": "urn:uuid:f43f23115d954cd28716556d7bb26287",
    "meta": {
        "lastUpdated": "2019-02-27T02:15:12.686+00:00"
    },
    "type": "searchset",
    "total": 67,
    "link": [
        {
            "relation": "self",
            "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire??context-code=task&value=example&_snapshot=636868305126868471"
        }
    ],
    "entry": [
        {
            "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/Questionnaire/questionnaire-example-search",
            "resource": {
                "resourceType": "Questionnaire",
                "id": "questionnaire-example-search",
                "meta": {
                    "versionId": "19",
                    "lastUpdated": "2019-02-13T08:37:05.202+00:00",
                    "profile": [
                        "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
                    ]
                },
                "text": {
                    "status": "generated",
                    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><b>Argonaut Questionnaire Sampler</b><hr /><span style=\"color: gray;\">Publisher:</span> Argonaut Project\r\n</div>"
                },
                "extension": [
                    {
                        "url": "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/extension-timeLimit",
                        "valueDuration": {
                            "value": 5,
                            "unit": "minute",
                            "system": "http://unitsofmeasure.org",
                            "code": "min"
                        }
                    }
                ],
                "url": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-search",
                "identifier": [
                    {
                        "system": "http://acme.org/q-identifiers",
                        "value": "questionnaire-example-sampler"
                    }
                ],
                "version": "3.0.0",
                "title": "Argonaut Questionnaire Sampler",
                "status": "draft",
                "date": "2018-07-26",
                "publisher": "Argonaut Project",
                "useContext": [
                    {
                        "code": {
                            "system": "http://hl7.org/fhir/usage-context-type",
                            "code": "task",
                            "display": "Workflow Task"
                        },
                        "valueCodeableConcept": {
                            "coding": [
                                {
                                    "system": "http://acme.org",
                                    "code": "example",
                                    "display": "Example of Use"
                                }
                            ]
                        }
                    }
                ],

        ...[snipped for brevity]....


Client Application Renders And Displays The Form

The assessment is rendered and displayed to the end user (for example, as an online form ) to be completed by the subject or the provider administrator. How the form is rendered and displayed are out of scope for this guide.

End User Completes The Assessment

The responses to the assessment are captured by the Client Application. It may also calculate a scored based on the associated values associated with each item via the Questionnaire Ordinal Value Extension. How the score is calculated may be described within the Questionnaire, often as a hidden display item. The actual logic and calculation is an implementation detail outside of scope of this Implementation Guide.

The QuestionnaireResponse resource may be used to capture, exchange and persist the response data. It represents the response data to the individual questions on the form and is ordered and grouped corresponding to the structure and grouping of the Questionnaire being responded to. How the QuestionnaireResponse gets populated is beyond the scope of this IG.

Time limits for completion of a questionnaire or individual question can be defined in the Argonaut Questionnaire Time Limit Extension. The Client Application may record the start and stop date-times in the Argonaut QuestionnaireResponse Response Period Extension which can be used to determine whether the questionnaire or items were answered within the prescribed time limit. How this information modifies the behavior of the Form-filler or interpretation of results is an implementation detail outside of scope of this Implementation Guide.

Provider EHR Posts to Answer Bank

st-step3.jpg

The responses captured as QuestionnaireResponse are are uploaded to an Answer Bank where they can be retrieved for subsequent use and analysis. As is defined in the Argonaut QuestionnaireResponse Profile, a contained Patient resource may inserted in order to facilitate subsequent analysis as described below. The QuestionnaireResponse resource can be validated against the corresponding Questionnaire to verify that required groups and questions are answered and that answers fit constraints in terms of cardinality, data type, etc.

APIs

The following Argonaut Questionnaire artifacts are used in this transaction:

Usage

create a single QuestionnaireResponse:

POST [base]/QuestionnaireResponse

Request

POST http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 201 (Created)
Content-Type: application/fhir+json; charset=utf-8
Content-Location: http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse/2dcdb4a057b941c9b3ad0c8d5bf68d42/_history/1
[other headers]

    
{
   "resourceType": "QuestionnaireResponse",
   "id": "2dcdb4a057b941c9b3ad0c8d5bf68d42",
   "meta": {
      "versionId": "1",
      "lastUpdated": "2019-02-13T09:07:09.672+00:00",
      "profile": [
         "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaireresponse"
      ]
   },
   "text": {
      "status": "generated",
      "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">\n    <h3>Response Summary</h3>\n    <strong>Questionnaire URL:</strong> http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-sampler<br />\n    <strong>Date Completed:</strong> 2019-02-13T00:39:38.320181Z<br />\n    <hr /> <br /><strong>The Argonaut Questionnaire Sampler is designed to show all the question types that can be used in the Argonaut Questionnaire Project:\n\n1 boolean\n2 decimal\n3 int
        ...[snipped for brevity]....


update a single QuestionnaireResponse::

PUT [base]/QuestionnaireResponse/[id]

Request

PUT http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse/questionnaireresponse-example-search

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 201 (Created)
Content-Type: application/fhir+json; charset=utf-8
Content-Location: http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse/questionnaireresponse-example-search/_history/1
[other headers]

    
{
   "resourceType": "QuestionnaireResponse",
   "id": "questionnaireresponse-example-search",
   "meta": {
      "versionId": "1",
      "lastUpdated": "2019-02-13T09:07:10.464+00:00",
      "profile": [
         "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaireresponse"
      ]
   },
   "text": {
      "status": "generated",
      "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">\n    <h3>Response Summary</h3>\n    <strong>Questionnaire URL:</strong> http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-sampler<br />\n    <strong>Date Completed:</strong> 2019-02-13T00:39:38.320181Z<br />\n    <hr /> <br /><strong>The Argonaut Questionnaire Sampler is designed to show all the question types that can be used in the Argonaut Questionnaire Project:\n\n1 boolean\n2 decimal\n3
        ...[snipped for brevity]....


create multiple QuestionnaireResponses using a [batch] transaction:

POST/[base]

Request

POST http://sqlonfhir-stu3.azurewebsites.net/fhir

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
[other headers]

    
{
   "resourceType": "Bundle",
   "type": "transaction-response",
   "total": 14,
   "entry": [
      {
         "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse/questionnaire-example-delete",
         "resource": {
            "resourceType": "QuestionnaireResponse",
            "id": "questionnaire-example-delete",
            "meta": {
               "versionId": "8",
               "lastUpdated": "2019-02-13T09:55:57.695+00:00",
               "profile": [
                  "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaireresponse"
               ]
            },
            "text": {
               "status": "generated",
               "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><h3>Response Summary</h3><strong>Questionnaire URL:</strong> http://fhir.org/guides
        ...[snipped for brevity]....


Provider EHR Searches Answer Bank

st-step4.jpg

Responses to the assessment are retrieved for a variety of purposes. QuestionnaireResponse can be searched using the standard QuestionnaireResponse search parameters listed below. If the Answer Bank has access to the Questionnaire resource, searches may fetch the Questionnaire at the same time as well using the _include parameter. Note that individual responses are not directly searchable using the FHIR RESTful API. In order to search directly on responses, they must be “downloaded” into a searchable form - i.e. to a local FHIR or non-FHIR data store such as a database or FHIR Observations.

It is common to search for responses based on patient demographic information such as such as age, sex, race, location. There are three options for searching based on the subject demographics:

  1. If the Answer Bank has access the subject’s Patient resource, a [chained] query can be performed using the subject reference parameter as detailed below.

  2. When the Answer Bank does not have access to the subject’s Patient resource, a contained patient resource in the QuestionnaireResponse can be used to allow for searching on the Patient. If the Answer Bank is in an untrusted environment such as a external shared server, the contained patient resource should only represent the minimum de-identified data necessary to perform the search - e.g. a resource with month/year of birth, sex, race/ethnicity, and first two or three digits of US zip code. The search syntax is detailed below.

  3. As stated above, individual responses to answers to questions like age, race, sex and location are not directly searchable through QuestionnaireResponse and can be converted to a searchable form for direct access. This approach to search is outside the scope of this implementation guide.

The standard FHIR RESTful search API is used with the following mandatory search parameters:

and the following optional search parameters:

and the following optional chained search parameters:

  • patient.gender
  • patient.birthdate (with support for date prefixes le and ge and )
  • patient.race
  • patient.ethnicity
  • patient.address-postalcode

For the convenience of the client, the Answer Bank may support including the Questionnaire using the following optional search parameter:

  • _include Note that this path references a resource on the Assessment Bank server which is typically another server.

APIs

The following Argonaut Questionnaire artifacts are used in this transaction:

Usage

Fetching a single QuestionnaireResponse:

  • based on its id:

    GET [base]/QuestionnaireResponse/[id] or GET [base]/QuestionnaireResponse?_id=[id]

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?_id=questionnaireresponse-example-search

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
[other headers]

    
{
   "resourceType": "Bundle",
   "id": "urn:uuid:c10d8e84d0924f25a832868b9581670d",
   "meta": {
      "lastUpdated": "2019-02-13T10:28:27.237+00:00"
   },
   "type": "searchset",
   "total": 1,
   "link": [
      {
         "relation": "self",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?_id=questionnaireresponse-example-search&_snapshot=636856505072374718"
      }
   ],
   "entry": [
      {
         "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse/questionnaireresponse-example-search",
         "resource": {
            "resourceType": "QuestionnaireResponse",
            "id": "questionnaireresponse-example-search",
            "meta": {
               "versionId": "1",
        ...[snipped for brevity]....


  • based on its id and include the Questionnaire:

    GET [base]/QuestionnaireResponse?_id=[id]&_include=QuestionnaireResponse:questionnaire

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?_id=questionnaireresponse-example-search&_include=QuestionnaireResponse%3Aquestionnaire

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
[other headers]


{
   "resourceType": "Bundle",
   "id": "urn:uuid:25162d3c0d1241348e129bf592fe20a0",
   "meta": {
      "lastUpdated": "2019-02-13T10:28:28.112+00:00"
   },
   "type": "searchset",
   "total": 1,
   "link": [
      {
         "relation": "self",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?_id=questionnaireresponse-example-search&_include=QuestionnaireResponse%3Aquestionnaire&_snapshot=636856505081124854"
      }
   ],
   "entry": [
      {
         "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse/questionnaireresponse-example-search",
         "resource": {
            "resourceType": "QuestionnaireResponse",
            "id": "questionnaireresponse-example-search",
            "meta": {

        ...[snipped for brevity]....


   "resourceType": "Questionnaire",
   "id": "questionnaire-example-sampler",
   "meta": {
      "versionId": "1",
      "lastUpdated": "2019-02-13T05:57:59.507-05:00",
      "profile": [
        "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
      ]
    },
  "text": {

        ...[snipped for brevity]....


Searching for all the completed QuestionnaireResponses

  • based on particular assessment:

    GET [base]/QuestionnaireResponse/?status=completed&questionnaire=[questionnaire url]

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?status=completed&questionnaire=questionnaire-example-search

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
[other headers]

    
{
   "resourceType": "Bundle",
   "id": "urn:uuid:1e79af295b464c7a95e037ed445bd03b",
   "meta": {
      "lastUpdated": "2019-02-13T10:28:30.82+00:00"
   },
   "type": "searchset",
   "total": 2,
   "link": [
      {
         "relation": "self",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?status=completed&questionnaire=questionnaire-example-search&_snapshot=636856505108205642"
      }
   ],
   "entry": [
      {
         "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse/questionnaireresponse-example-search",
         "resource": {
            "resourceType": "QuestionnaireResponse",
            "id": "questionnaireresponse-example-search",
            "meta": {
               "versionId": "1",
        ...[snipped for brevity]....


  • based on a patient encounter:

    GET [base]/QuestionnaireResponse/?status=completed&patient=Patient/[patient]&context=Encounter/[encounter]

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?status=completed&patient=subject1&context=encounter2

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
[other headers]


{
   "resourceType": "Bundle",
   "id": "urn:uuid:e9a87fdd8b244ca4ab4ee4a29caef4b1",
   "meta": {
      "lastUpdated": "2019-02-13T11:15:50.915+00:00"
   },
   "type": "searchset",
   "total": 1,
   "link": [
      {
         "relation": "self",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?status=completed&patient=subject1&context=encounter2&_snapshot=636856533509154158"
      }
   ],
   "entry": [
      {
         "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse/questionnaireresponse-example-phq9-enc2",
         "resource": {
            "resourceType": "QuestionnaireResponse",
            "id": "questionnaireresponse-example-phq9-enc2",
            "meta": {
               "versionId": "2",
               "lastUpdated": "2018-07-27T20:36:40.103+00:00",
               "profile": [
                  "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaireresponse"
               ]
            },
            "identifier": {
               "value": "test"
            },
            "questionnaire": {
               "reference": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-phq9"
            },
            "status": "completed",
            "subject": {
               "reference": "Patient/subject1"
            },
            "context": {
               "reference": "Encounter/encounter2"
            },
            "authored": "2018-07-27T04:04:33.927848",
            "author": {

        ...[snipped for brevity]....


Searching for all QuestionnaireResponses with any status

  • based on who administered it:

    GET [base]/QuestionnaireResponse/?source=Practitioner/[practitioner]

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?source=prov-admin1

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
[other headers]


{
   "resourceType": "Bundle",
   "id": "urn:uuid:f32aa17a75c8422199796e30761b5c47",
   "meta": {
      "lastUpdated": "2019-02-13T11:34:49.427+00:00"
   },
   "type": "searchset",
   "total": 1,
   "link": [
      {
         "relation": "self",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?source=prov-admin1&_snapshot=636856544894273541"
      }
   ],
   "entry": [
      {
         "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse/05b19f1aa2bb42049e0876912ec7880b",
         "resource": {
            "resourceType": "QuestionnaireResponse",
            "id": "05b19f1aa2bb42049e0876912ec7880b",
            "meta": {
               "versionId": "1",
               "lastUpdated": "2019-02-13T11:28:34.913+00:00",
               "profile": [

        ...[snipped for brevity]....

          "authored": "2019-02-13T00:39:38.320181Z",
          "author": {
              "reference": "Practitioner/prov-admin1"
          },
          "source": {
              "reference": "Practitioner/prov-admin1"
          },

        ...[snipped for brevity]....


GET [base]/QuestionnaireResponse/?author=Practitioner/[practitioner]

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?author=prov-admin1

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
[other headers]


{
   "resourceType": "Bundle",
   "id": "urn:uuid:fde5eb3ec033455f9d482bd37cde379c",
   "meta": {
      "lastUpdated": "2019-02-13T11:34:49.958+00:00"
   },
   "type": "searchset",
   "total": 75,
   "link": [
      {
         "relation": "self",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?author=prov-admin1&_snapshot=636856544899585969"
      },
      {
         "relation": "first",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?author=prov-admin1&_snapshot=636856544899585969"
      },
      {
         "relation": "next",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?author=prov-admin1&_snapshot=636856544899585969&_page=1"
      },
      {
         "relation": "last",
         "url": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireRe

        ...[snipped for brevity]....

          "authored": "2019-02-13T00:39:38.320181Z",
          "author": {
              "reference": "Practitioner/prov-admin1"
          },
          "source": {
              "reference": "Practitioner/prov-admin1"
          },

        ...[snipped for brevity]....


Searching for all QuestionnaireResponses based upon patient demographics

  • based on sex and age range:

    GET [base]/QuestionnaireResponse/?patient.gender=[gender]&patient.birthdate=ge[date]{&patient.birthdate=lt[date]}

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?patient.gender=male&patient.birthdate=le1975

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
[other headers]


{
   "resourceType": "Bundle",
   "id": "urn:uuid:1e79af295b464c7a95e037ed445bd03b",
   "meta": {
      "lastUpdated": "2019-02-13T10:28:30.82+00:00"
   },
   "type": "searchset",
   "total": 25,
   "link": [
        ...[snipped for brevity]....
   ],
   "entry": [
      {
         "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse/questionnaireresponse-example-patient-search",
         },
         "contained": [
            {
               "id": "deid-p",
               "extension": [
                  {
                     "extension": [
                        {
                           "url": "text",
                           "valueString": "Asian"
                        },
                        {
                           "url": "ombCategory",
                           "valueCoding": {
                              "code": "asian",
                              "display": "Asian",
                              "system": "urn:oid:2.16.840.1.113883.6.238"
                           }
                        }
                     ],
                     "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race"
                  }
               ],
               "address": [
                  {
                     "postalCode": "945"
                  }
               ],
               "birthDate": "1969",
               "gender": "male",
               "resourceType": "Patient"
            }
         ],
        ...[snipped for brevity]....
         "questionnaire": {
            "reference": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-sampler"
         },
         "source": {
            "reference": "Patient/subject1"
         },
         "status": "completed",
         "subject": {
            "reference": "#deid-p"
         },
         "resourceType": "QuestionnaireResponse"
      }


  • based on location:

    GET [base]/QuestionnaireResponse/?patient.address-postalcode=[zip]

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?patient.address-postalcode=945

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
[other headers]


{
   "resourceType": "Bundle",
   "id": "urn:uuid:1e79af295b464c7a95e037ed445bd03b",
   "meta": {
      "lastUpdated": "2019-02-13T10:28:30.82+00:00"
   },
   "type": "searchset",
   "total": 25,
   "link": [
        ...[snipped for brevity]....
   ],
   "entry": [
      {
         "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse/questionnaireresponse-example-patient-search",
         },
         "contained": [
            {
               "id": "deid-p",
               "extension": [
                  {
                     "extension": [
                        {
                           "url": "text",
                           "valueString": "Asian"
                        },
                        {
                           "url": "ombCategory",
                           "valueCoding": {
                              "code": "asian",
                              "display": "Asian",
                              "system": "urn:oid:2.16.840.1.113883.6.238"
                           }
                        }
                     ],
                     "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race"
                  }
               ],
               "address": [
                  {
                     "postalCode": "945"
                  }
               ],
               "birthDate": "1969",
               "gender": "male",
               "resourceType": "Patient"
            }
         ],
        ...[snipped for brevity]....
         "questionnaire": {
            "reference": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-sampler"
         },
         "source": {
            "reference": "Patient/subject1"
         },
         "status": "completed",
         "subject": {
            "reference": "#deid-p"
         },
         "resourceType": "QuestionnaireResponse"
      }


  • based on race or ethnicity:

    GET [base]/QuestionnaireResponse/?patient.race=[race code] GET [base]/QuestionnaireResponse/?patient.ethnicity=[ethnicity code]

Request

GET http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse?patient.patient.race=2028-9

User-Agent: python-requests/2.20.0
Accept: application/fhir+json
Content-Type: application/fhir+json
[other headers]

Response

Response Code: 200 (OK)
Content-Type: application/fhir+json; charset=utf-8
[other headers]


{
   "resourceType": "Bundle",
   "id": "urn:uuid:1e79af295b464c7a95e037ed445bd03b",
   "meta": {
      "lastUpdated": "2019-02-13T10:28:30.82+00:00"
   },
   "type": "searchset",
   "total": 25,
   "link": [
        ...[snipped for brevity]....
   ],
   "entry": [
      {
         "fullUrl": "http://sqlonfhir-stu3.azurewebsites.net/fhir/QuestionnaireResponse/questionnaireresponse-example-patient-search",
         },
         "contained": [
            {
               "id": "deid-p",
               "extension": [
                  {
                     "extension": [
                        {
                           "url": "text",
                           "valueString": "Asian"
                        },
                        {
                           "url": "ombCategory",
                           "valueCoding": {
                              "code": "2028-9",
                              "display": "Asian",
                              "system": "urn:oid:2.16.840.1.113883.6.238"
                           }
                        }
                     ],
                     "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race"
                  }
               ],
               "address": [
                  {
                     "postalCode": "945"
                  }
               ],
               "birthDate": "1969",
               "gender": "male",
               "resourceType": "Patient"
            }
         ],
        ...[snipped for brevity]....
         "questionnaire": {
            "reference": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-sampler"
         },
         "source": {
            "reference": "Patient/subject1"
         },
         "status": "completed",
         "subject": {
            "reference": "#deid-p"
         },
         "resourceType": "QuestionnaireResponse"
      }


Examples and Reference Implementation

Examples of Questionnaires and QuestionnaireResponses which demonstrate use of many of the the extensions and supported elements and question types can be found on the Argonaut Questionnaire Profile and Argonaut QuestionnaireResponse Profile page. In addition, the Argonaut Questionnaire Test Renderer simulates of the static form workflow.

Amending and Revising Forms

End User wishes to go back and revise an answer to Question

For static forms this is a rendering issue for the Client Application which may allow the user to go back and change answer prior to submitting the form. Retrieving and resuming or correcting a form is currently out of scope for Argonaut Questionnaire but is covered in the SDC (Structured Data Capture) implementation Guide.

Answer in Error and Needs to be Reentered

If the answer is ‘wrong” and needs to be reentered, it is the function of the Client Application to prompt the end user to re-answer the question. For example, if an answer is incomplete or incorrectly formatted such as a date or telephone number. How this done is out of scope for Argonaut Questionnaire.

Technical Error

Technical errors are typically handled by lower level protocols or manual processes. How the client or server would resubmit the QuestionnaireResponse is out of scope for Argonaut Questionnaire