Purview

$purview Operation

https://www.hl7.org/fhir/operations.html

https://www.hl7.org/fhir/operationdefinition.html

Overview

The grantee of a Consent record is always of one of the following types:
  • Team. A Patient can grant a Privacy Label to an entire Team.
  • Individual Professional. A Patient can grant a Privacy Label to an Individual Professional who does not belong to a Team.
  • Carer. A Patient can grant a Privacy Label to another Patient who is caring for them.
The Purview of an authenticated User is the grantee to which Consent records which will influence their level of access have been assigned.

A Consent record will apply to an authenticated User if and only if the Consent record's grantee matches the User's Purview.

Difference between a User and their Purview

A patient never grants a Privacy Label to a Team Professional, but instead they grant them to the Team itself. Conversely, Privacy Labels can be granted directly to an Individual Professional or a Patient (acting as a carer).

For example, let's imagine there are two Professionals.
  • Doctor Jones is a Team Professional, working for Team One.
  • Doctor Smith is an Individual Professional.
They would each like to know which Privacy Labels Patient 1 has granted them.

Doctor Jones cannot search for Consent records assign to himself, because Patient 1 cannot assign a Consent record to a Team Professional. Instead, Patient 1 has granted Privacy Labels to Team One, knowing that these will apply to Doctor Jones. So the Consent record query filter which Doctor Jones needs to use is: grantee = Team One

Doctor Smith, however, does not have a Team. Instead, as an Individual Professional, Patient 1 will have granted Privacy Labels directly to him. The Consent record query filter he needs to use is: grantee = Doctor Smith

To prevent authenticated callers of the FHIR® API needing to be aware of this logic, they can determine their Purview by calling the $purview operation. This will perform the necessary logic for them and return a single reference to a grantee, which will be of one of the 3 types outlined above.

The caller can then use this reference to determine whether any given Consent record will apply to them. A Consent record will apply to them if and only if the response from $purview matches Consent.actor

How a User's Purview determined

The purview of a caller is calculated based on their user type, as indicated in the table below.

User TypePurviewReturned Reference
PatientThe currently authenticated Patient.

This is true even if the Patient is intending to check which Consent records they have for another Patient's record (i.e. even if they are acting as a carer.)
The Patient resource.
Professional
(Team)
The Team to which the currently authenticated Professional belongs.The Organization resource for the Team.
Professional
(Individual)
 The Practitioner which represents the Professional directly, since they do not belong to a Team. The Practitioner resource representing the individual Professional.

Endpoints

Protection CategoryInteractionHTTPURLSupported Search ParamsPermitted User TypesDescriptionExamples (more)
MinimaloperationGET/Consent/$purviewNone
  • Patient
  • Professional
Retrieve the Purview of the currently authenticated caller.

Mappings

FHIRPKBNotes
OperationDefinition.url"http://fhir.patientsknowbest.com/operation/purview" 
OperationDefinition.name"purview" 
OperationDefinition.status"active" 
OperationDefinition.kind"operation" 
Operation.idempotenttrue 
OperationDefinition.code"purview" 
OperationDefinition.resource
  • "Consent"
 
OperationDefinition.systemfalse 
OperationDefinition.typetrue 
OperationDefinition.instancefalse 
OperationDefinition.parameterThere is exactly one parameter.
  • Parameter.name = "purview"
  • Parameter.use = "out"
  • Parameter.min = 1
  • Parameter.max = "1"
  • Parameter.type = "Reference"
 

Subpages (1): Examples
Comments