Versions Compared

Version Old Version 4 New Version 5
Changes made by

James Price

James Price

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Table of Contents
minLevel1
maxLevel6
outlinefalse
typelist
printablefalse

Triggering a questionnaire request

Organisations can use the $send-questionnaire-request custom operation to send questionnaires to patients via our APIs. During phase 1, this will be the only way to send questionnaires to patients.

This section contains the OperationDefinition of our $send-questionnaire-request custom operation and an example workflow.

OperationDefinition

name

"send-questionnaire-request"

...

  • parameter[0]

    • name = "target"

    • use = "in"

    • min = 1

    • max = “500“

    • type = "Reference(Patient|Organization)"

    • documentation = “the target references can be either represented as a URL reference or through the use of an identifier representing the national health number. If a target is represented twice, only one request will be created per API call.“

  • parameter[1]

    • name = “additionalIdentifier”

    • use = “in”

    • min = 0

    • max = “1”

    • type = “Identifier”

  • parameter[2]

    • name = "request"

    • use = "out"

    • min = 0

    • max = "*"

    • type = "Reference(ServiceRequest)"

Endpoint

Method

RequestBody

Auth header

FHIRWALL_BASE_URL/Questionnaire/questionnaireID/$send-questionnaire-request

POST

Parameters Resource

parameters:

0..* target

0..1 additionalIdentifier

 

Authorization: Bearer <Keycloak token>

x-team-id: <UUID>

Example

This example demonstrates how to trigger a questionnaire request for a specific Patient using their national ID. 

...

To include an external identifier, which can then be used to retrieve the associated QuestionnaireResponse resources, add the additionalIdentifier parameter shown in the example request body.

Example request URL

Code Block
POST FHIRWALL_BASE_URL/Questionnaire/questionnaireId/$send-questionnaire-request

Example request header

Authorisation: Bearer aaaaa-bbbbb

x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314

Example request body

Code Block
{
	"resourceType": "Parameters",
	"parameter": [
		{
			"name": "target",
			"valueReference": {
				"identifier": {
				"system": "https://fhir.nhs.uk/Id/nhs-number",
				"value": "5193233945"} 
			}
		},
		{
			"name": "additionalIdentifier", 
			"valueIdentifier": {
			"system": "https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest",
			"value": "12345"
			}
		}
	]
}

 

Example request (raw)

curl -X POST --header "Accept: application/fhir+json" --header "Content-Type: application/fhir+json" --header "Authorization: Bearer aaaaa-bbbbb" --header “x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314” "FHIRWALL_URL/Questionnaire/bd17e556-20e3-4f01-8078-30e5f675b0f2/$send-questionnaire-request" --data "{ \"resourceType\":\"Parameters\", \"parameter\":[ { \"name\":\"target\", \"valueReference\":{ \"identifier\":{ \"system\":\"https://fhir.nhs.uk/Id/nhs-number\", \"value\":\"5193233945\" } } }, { \"name\":\"additionalIdentifier\", \"valueIdentifier\":{ \"system\":\"https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest\", \"value\":\"12345\" } } ] }"

Differences between the current and new API calls

Current API call for triggering a questionnaire request

curl -X POST --header "Accept: application/fhir+json" --header "Content-Type: application/fhir+json" --header "Authorization: Bearer aaaaa-bbbbb" --header "X-Org-Public-Id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" "https://sandbox.patientsknowbest.com/fhir/Questionnaire/bd17e556-20e3-4f01-8078-30e5f675b0f2/$send-questionnaire-request" --data "{ \"resourceType\":\"Parameters\", \"parameter\":[ { \"name\":\"target\", \"valueReference\":{ \"identifier\":{ \"system\":\"https://fhir.nhs.uk/Id/nhs-number\", \"value\":\"5193233945\" } } }, { \"name\":\"requestor\", \"valueReference\":{ \"reference\":\"Practitioner/bdaa24d0-3cd5-469c-aa69-db676fa31bbe\" } }, { \"name\":\"notificationFlag\", \"valueCode\":\"EMAIL_NOTIFICATION_DISABLED\" }, { \"name\":\"additionalIdentifier\", \"valueIdentifier\":{ \"system\":\"https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest\", \"value\":\"294672281\" } } ] }"

New API call for triggering a questionnaire request

curl -X POST --header "Accept: application/fhir+json" --header "Content-Type: application/fhir+json" --header "Authorization: Bearer aaaaa-bbbbb" --header “x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314” "FHIRWALL_URL/Questionnaire/bd17e556-20e3-4f01-8078-30e5f675b0f2/$send-questionnaire-request" --data "{ \"resourceType\":\"Parameters\", \"parameter\":[ { \"name\":\"target\", \"valueReference\":{ \"identifier\":{ \"system\":\"https://fhir.nhs.uk/Id/nhs-number\", \"value\":\"5193233945\" } } }, { \"name\":\"additionalIdentifier\", \"valueIdentifier\":{ \"system\":\"https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest\", \"value\":\"12345\" } } ] }"

Summary of the differences

  • requestor/practitioner ID is no longer required. This is because, during phase 1, the questionnaire is not being sent from a specific professional user.

  • X-Org-Public-ID is replaced by x-team-id in the header. x-team-id is the UUID of the FHIR organisation resource that represents the PKB team. This can be retrieved from the PKB Support team initially, but will soon be available via our APIs.

  • notificationFlag is no longer required. This is because, during phase 1, the questionnaire is not being sent from a specific professional user and there is therefore nobody for the email notification to go to.

Searching for a Questionnaire resource

Organisations can retrieve Questionnaire resources using search operations to the Questionnaire endpoint.

...

The following search parameters can be used to search for Questionnaire resources:

  • title

  • questionnaireId

Example

This example demonstrates how to search for all Questionnaire resources that a team has access to.

...

 curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header "x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" “FHIRWALL_URL/Questionnaire/"

Differences between the current and new API calls

Current API call for searching for a Questionnaire

curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header "X-Org-Public-Id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" "https://sandbox.patientsknowbest.com/fhir/Questionnaire"

New API call for searching for a Questionnaire

 curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header "x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" “FHIRWALL_URL/Questionnaire/"

Summary of the differences

  • X-Org-Public-ID is no longer required as a header. This has been replaced by x-team-id.

Searching for a QuestionnaireResponse resource

Organisations can retrieve QuestionnaireResponse resources based on patient, additionalId, questionnaireId and date, using search operations to the QuestionnaireResponse endpoint.

...

  • subject

  • questionnaireId

  • authored

Example

Retrieving all QuestionnaireResponse resources for a specific patient

This example demonstrates how to retrieve all questionnaire responses for a specific patient

...

curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header “x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314” "FHIRWALL_URL/QuestionnaireResponse?patient=Patient/3d8afd18-0844-459a-b3c2-355d02e54c0a"

Retrieving a QuestionnaireResponse using a business identifier

This example demonstrates how to retrieve a questionnaire response based on a business identifier provided when the questionnaire request was triggered.

...

curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header “x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314” "FHIRWALL_URL/QuestionnaireResponse?based-on:ProcedureRequest.identifier=https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest%7C12345&_include=QuestionnaireResponse:basedOn:ProcedureRequest"

Differences between the current and new API calls

Current API call for searching for QuestionnaireResponse resources for a specific patient

curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header "X-Org-Public-Id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" "https://sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?patient=Patient/3d8afd18-0844-459a-b3c2-355d02e54c0a"

New API call for searching for QuestionnaireResponse resources for a specific patient

curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header “x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314” "FHIRWALL_URL/QuestionnaireResponse?patient=Patient/3d8afd18-0844-459a-b3c2-355d02e54c0a"

Summary of the differences

  • X-Org-Public-ID is no longer required as a header. This has been replaced by x-team-id

...