Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

A023: Retrieve Advice and Guidance Requests Worklist

Status: Live

Description

This API aims to make available e-RS functionality which will allow the retrieval of the “Advice and Guidance Requests” worklist by a Service Provider. The behaviour for this retrieval is very similar to retrieval of worklists for Appointment Requests (e.g. the “Referrals for Review” worklist) but references FHIR ‘CommunicationRequest’ resources which are used to model e-RS Advice and Guidance Requests.

Request Operation: URL

Method URL Authentication
POST {Base URL}/STU3/v1/CommunicationRequest/$ers.fetchworklist Session Token (Details)
  • {Base URL} (Dev1) = https://api.dev1.ers.ncrs.nhs.uk/ers-api

Operation Definition

Prerequisite Conditions

  • The user is authenticated with an effective business function of Service Provider Clinician or Service Provider Admin. For a login business function of Service Provider Clinician Admin, the effective business function is Service Provider Clinician since the login is “on behalf of”

INPUT

Request Operation: Header

Field Name Value
XAPI_ASID The “Accredited System ID” issued to the third party
HTTP_X_SESSION_KEY The session key generated by the Authentication and Authorisation APIs
Content-Type */*, application/fhir+json

Request Operation: Body

Name Cardinality Type Description
listType 1..1 CodeableConcept Indicates the type of list requested, this is currently fixed to ‘ADVICE_AND_GUIDANCE_REQUESTS
service 0..1 Identifier The service identifier
specialtyAssignedIndicator 0..1 CodeableConcept Indicates whether a Specialty is assigned to the Referral Request. If ‘Assigned’ the ‘Specialty’ parameter must be present. If ‘Not Assigned’ the ‘specialtyAssignedIndicator’ and ‘Specialty’ parameter must be absent.
specialty 0..1 CodeableConcept The Specialty for the service. If present, the ‘specialtyAssignedIndicator’ parameter must be set to ‘Assigned’. The specialty list must be retrieved dynamically from the e-RS valueset.
location 0..1 Identifier The service location identifier.
clinicianAssignedIndicator 0..1 CodeableConcept Indicates whether a clinician is assigned to the Referral Request. If ‘Assigned’ the ‘Clinician’ parameter must be present. If ‘Not Assigned’ the ‘Clinician’ parameter must be absent.
clinician 0..1 Identifier The clinician assigned to the Referral Request. If present, the ‘ClinicianAssignedIndicator’ parameter must be set to ‘Assigned’

Example URI

https://api.dev1.ers.ncrs.nhs.uk/ers-api/STU3/v1/CommunicationRequest/$ers.fetchworklist

Example Request Header

"XAPI_ASID" : "999000000045",
"HTTP_X_SESSION_KEY" : "pro-api-session:06bdd8aa-da2c-45dc-bc73-bee80b70fe2d",
"Content-Type" : "application/fhir+json"

OUTPUT

Response: Success

If successful, all entries from the ‘Advice and Guidance Requests’ worklist matching the input criteria are returned and the response code 200 (OK) is returned.

The Response Body is in the structure of a eRS-FetchWorklist-List-1 and each entry within the List includes Extension-eRS-AdviceAndGuidanceRequests-WorkListItem-1.

The fields within this extension are specific to the Advice and Guidance Requests worklist as follows:

Field Description
priority Priority of the Advice and Guidance Request from the CodeableConcept eRS-Priority-1
category The status of the Advice and Guidance Request. A Codeable Concept from eRS-AdviceAndGuidanceStatus-1
adviceLastUpdated DateTime when the Advice and Guidance Request was last updated
adviceFirstRequested DateTime when the Advice and Guidance Request was first requested
referrer The Referrer of the Advice and Guidance Request. Reference to a Practitioner by UID in SDS
service Reference to an e-RS Service by Service Id
specialty Specialty of the Service from CodeableConcept SPECIALTY
clinicType Specialty of the Service from CodeableConcept CLINIC-TYPE
namedClinician Reference to a Practitioner used within the Service Search by UID in SDS. Only present if service search included ‘Named Clinician’.
patient Reference to the Patient associated with the Advice and Guidance Request by NHS Number.

The ‘item.reference’ field within each entry in the FHIR List returned is a reference to a FHIR ‘CommunicationRequest’ resource. This reference can be used to retrieve the full Advice and Guidance Request as a FHIR ‘CommunicationRequest’ resource.

CodeableConcept https://baseURL/STU3/CodeSystem/eRS-CommunicationListSelector-1 is new for this worklist. It has, for now, only a single value as follows:

Value Meaning
ADVICE_AND_GUIDANCE_REQUESTS Select the ‘Advice and Guidance Requests’ worklist

Example Response Header

"X_ERS_TRANSACTION_ID" : "bfa90094-981a-4d2a-ad56-a17429865241-1",
"Content-Type" : "application/fhir+json"

Example Response Body

The following example contains a single entry on the worklist:

Response: Failure

If an error occurs, the relating HTTP status code will be returned in the header.

Where status code 422 (Unprocessable Entity) is returned then an eRS-OperationOutcome-1 will be included in the body, as detailed below:

OutcomeKey Description Suggested Diagnostic
NO_RELATIONSHIP The SPC user (or if SPCA, SPC user they are “on behalf of”) is not a workgroup member for the worklist. The professional user must be associated to the following by current workgroup membership at the same e-RS organisation that the “owner” professional user is logged-in under:
- Service
- Location (if provided)
- Specialty (if provided)
MISSING_VALUE Either one or both of the following fields have not been provided:
- Specialty
- Clinician
The field is reported as the location of the error.
When attempting to filter the worklist by specialty and/or clinician, the value for specialty assigned or clinician assigned is ‘assigned’. A specialty or clinician must be provided in this scenario.
UNEXPECTED_FIELD A value for specialty and/or clinician has been provided when not required.  The field is reported as the location of the error. When attempting to filter the worklist by specialty and/or clinician, the value for specialty assigned or clinician assigned is not ‘assigned’, a specialty or clinician is not required.
NO_SUCH_SERVICE The service provided does not exist in e-RS. When attempting to filter the worklist by service, the service ID must match an existing service in the eRS application. Check the service is still active and published in the DOS (directory of services).
NO_SUCH_LOCATION The location does not match a service location in e-RS. When attempting to filter the worklist by location, the location ID must match an existing location in the eRS application. Check the organisation is still active and not closed.
NO_SUCH_SPECIALTY The specialty provided is not part of e-RS reference data. When attempting to filter the worklist by specialty, the provided specialty is not recognised.  Check against existing reference data.
NO_SUCH_CLINICIAN The clinician provided is not a recognised professional user in e-RS. When attempting to filter the worklist by clinician, the provided clinician is not recognised.  Check against existing reference data.
INVALID_VALUE The specialty assigned value is ‘Not Assigned’. This value may be allowed in future worklists.

All content is available under the Open Government Licence v3.0, except where otherwise stated