From 0fa53373fcb1c5aec34aee3c425082ff33eb88d5 Mon Sep 17 00:00:00 2001 From: Marcus Fearnett Date: Wed, 12 Jun 2024 18:08:56 +0100 Subject: [PATCH] fgm use cases --- .../add-pf-record-sequence.plantuml | 14 +- .../add-pf-record-usecase.plantuml | 6 +- .../remove-pf-record-sequence.plantuml | 14 +- .../remove-pf-record-usecase.plantuml | 6 +- .../retrieve-pf-record-sequence.plantuml | 8 - .../retrieve-pf-record-usecase.plantuml | 4 +- input/pagecontent/add-fgm-flag-record.md | 117 ++++++++++++++ input/pagecontent/remove-fgm-flag-record.md | 63 ++++++++ input/pagecontent/retrieve-fgm-flag-record.md | 151 ++++++++++++++++++ sushi-config.yaml | 3 + 10 files changed, 345 insertions(+), 41 deletions(-) create mode 100644 input/pagecontent/add-fgm-flag-record.md create mode 100644 input/pagecontent/remove-fgm-flag-record.md create mode 100644 input/pagecontent/retrieve-fgm-flag-record.md diff --git a/input/images-source/add-pf-record-sequence.plantuml b/input/images-source/add-pf-record-sequence.plantuml index 1a3cea4..229e7dd 100644 --- a/input/images-source/add-pf-record-sequence.plantuml +++ b/input/images-source/add-pf-record-sequence.plantuml @@ -6,26 +6,16 @@ actor "Patient" as pat actor "Practitioner" as pra boundary "FHIR API" as api entity "Patient Flag" as flg -entity "Additional Detail" as add pra -> pat : Consult patient -pra -> api : Record adjustment record (transaction Bundle) - -api -> flg : Create/update resource +pra -> api : Record FGM Flag record +api -> flg : Create resource flg -> flg : Validate api <-- flg : return alt Validation failed api -> api : rollback end -loop for each Additional Detail resource - api -> add : Create/update resource (any) - add -> add : Validate - api <-- add : return - alt Validation failed - api -> api : rollback - end -end pra <-- api : OperationOutcome @enduml \ No newline at end of file diff --git a/input/images-source/add-pf-record-usecase.plantuml b/input/images-source/add-pf-record-usecase.plantuml index 0ee6426..548bfaf 100644 --- a/input/images-source/add-pf-record-usecase.plantuml +++ b/input/images-source/add-pf-record-usecase.plantuml @@ -5,14 +5,14 @@ left to right direction rectangle "Patient Flag"{ actor Practitioner as pra -usecase "Record" as record <> -usecase "Add Patient Flag record" as add <> +usecase "Record" as record +usecase "Add FGM Flag record" as add } actor Patient as pat -usecase "Consult" as consult <> +usecase "Consult" as consult pat -- consult pra -- consult diff --git a/input/images-source/remove-pf-record-sequence.plantuml b/input/images-source/remove-pf-record-sequence.plantuml index d9411b5..638b7d2 100644 --- a/input/images-source/remove-pf-record-sequence.plantuml +++ b/input/images-source/remove-pf-record-sequence.plantuml @@ -6,22 +6,10 @@ actor "Patient" as pat actor "Practitioner" as pra participant "FHIR API" as api entity "Patient Flag" as pfg -entity "Additional Detail" as add pat -> pra : Remove pra -> api : Remove api -> pfg : Remove resourc - - -loop for each Additional Detail resource - api -> add : Remove resource (any) - add -> add : Validate - api <-- add : return - alt Validation failed - api -> api : rollback - end -end - -pra <-- api : OperationOutcome + pra <-- api : OperationOutcome @enduml diff --git a/input/images-source/remove-pf-record-usecase.plantuml b/input/images-source/remove-pf-record-usecase.plantuml index fe8255b..99005bb 100644 --- a/input/images-source/remove-pf-record-usecase.plantuml +++ b/input/images-source/remove-pf-record-usecase.plantuml @@ -5,14 +5,14 @@ left to right direction rectangle "Patient Flag"{ actor Practitioner as pra -usecase "Record" as record <> -usecase "Remove Patient Flag record" as rem <> +usecase "Record" as record +usecase "Remove FGM Flag record" as rem } actor Patient as pat -usecase "Consult" as consult <> +usecase "Consult" as consult pat -- consult pra -- consult diff --git a/input/images-source/retrieve-pf-record-sequence.plantuml b/input/images-source/retrieve-pf-record-sequence.plantuml index 2c7f9c7..da4cb4e 100644 --- a/input/images-source/retrieve-pf-record-sequence.plantuml +++ b/input/images-source/retrieve-pf-record-sequence.plantuml @@ -5,18 +5,10 @@ skinparam actorStyle hollow actor "Practitioner" as pra boundary "FHIR API" as api entity "Patient Flag" as pfg -entity "Additional Detail" as add pra -> api : Query for records api -> pfg : Query for records api <-- pfg : SearchSet Bundle -opt - loop for each Additional Detail resource type - api -> add : Query for records - api <-- add : SearchSet Bundle - end -end pra <-- api : SearchSet Bundle -pra <-- api : OperationOutcome @enduml diff --git a/input/images-source/retrieve-pf-record-usecase.plantuml b/input/images-source/retrieve-pf-record-usecase.plantuml index 61a4a4b..f2a0156 100644 --- a/input/images-source/retrieve-pf-record-usecase.plantuml +++ b/input/images-source/retrieve-pf-record-usecase.plantuml @@ -5,8 +5,8 @@ left to right direction rectangle "Patient Flag"{ actor Practitioner as pra -usecase "Research" as res <> -usecase "Retrieve Patient Flag record" as ret <> +usecase "Research" as res +usecase "Retrieve FGM Flag record" as ret } pra -- res diff --git a/input/pagecontent/add-fgm-flag-record.md b/input/pagecontent/add-fgm-flag-record.md new file mode 100644 index 0000000..8ea7303 --- /dev/null +++ b/input/pagecontent/add-fgm-flag-record.md @@ -0,0 +1,117 @@ +### Overview + +For high level requirements, see [Key purposes of the FGM Flag](index.html#fgm-key-purposes) + +### Usecase + +
+ + {%include add-fgm-record-usecase.svg%} + +
+ +#### Scenarios + +```gherkin +Given a practitioner has received consent from a patient +And the consent is for reasonable adjustments +When a practioner adds an adjustment flag +Then an additional flag designated as a patient flag will be created + +Given a practitioner has received consent from a patient +And the consent is for reasonable adjustments +When a practioner adds an patient flag +Then the details of who created the patient flag will be recorded +And the flag will be linked to the patient + +Given a practitioner has received consent from a patient +And the consent is for reasonable adjustments +When a practioner adds an patient flag +Then the category of the flag will indicate that it is reasonable adjustments + +Given a practitioner has received consent from a patient +And the consent is for reasonable adjustments +When a practioner adds an patient flag +Then the code of the flag will indicate that it is reasonable adjustments + +Given a practitioner has received consent from a patient +And the consent is for reasonable adjustments +When a practioner adds an adjustment flag +Then the details of who created the adjustment flag will be recorded +And the flag will be linked to the patient + +Given a practitioner has received consent from a patient +And the consent is for reasonable adjustments +When a practioner adds an adjustment flag +Then the category of the flag will contain a code that indicates it is reasonable adjustments +And the cateogry of the flag will contain a code that indicates which adjustment category the flag is + +Given a practitioner has received consent from a patient +And the consent is for reasonable adjustments +When a practioner adds an adjustment flag +Then the code of the flag will be a SNOMED-CT concept that provide details of the adjustment + +Given a practitioner has received consent from a patient +And the consent is for reasonable adjustments +When a practioner adds an adjustment flag +Then a condition resource may also be created +And the details of who created the condition will be recorded +And the condition will be linked to the patient + +Given a practitioner has received consent from a patient +And the consent is for reasonable adjustments +When a practioner adds an condition +Then the category of the condition will indicate which catgory the condition is + +Given a practitioner has received consent from a patient +And the consent is for reasonable adjustments +When a practioner adds an condition +Then the code of the condition will be a SNOMED-CT concept representing an impairment/condition + +Given a practitioner has received consent from a patient +And the consent is for reasonable adjustments +When a practioner adds an adjustment flag +Then a freetext note may be added to the flag +``` + +### Workflow + +A practitioner performs an examination and determines that a condition and/or an adjustment should be recorded. If the patient does not consent, no details are recorded. If the patient consents, then the adjustment is recorded, and optionally the condition as well. + +
+ Add Patient Flag record workflow BPMN diagram. +
+ +### System Interactions + +The practioner decides to record a condition with the patients consent. This could be done with individual calls to the required endpoints, or can be done in a single transaction Bundle. A transaction Bundle can help with data integrity requirements and also help to reduce required http calls. + +
+ {%include add-fgm-record-sequence.svg%} +
+ +### Examples + +* [Patient example](Patient-PatientExample1.html) + +The following set of examples constitute the individual associated resources with the intial addition of a flag for Reasonable Adjustment. This includes the Consent resource where the patient has agreed to share information. Also a patient Flag resource, the adjustment Flag resource and the associated Condition resource. All resources have contained provenances. + +A transaction Bundle is also given that allows these resources (plus the patient) to be entered in an atomic traction. It uses PUTs, where in the case of an intial update, it may be done as a [conditional update](https://www.hl7.org/fhir/http.html#cond-update) + +* [Consent](Consent-RAConsentExample1.html) +* [Patient flag](Flag-RAPatientFlagExample1.html) +* [Reasonable Adjustment flag 1](Flag-RAFlagExample1.html) +* [Condition 1](Condition-RAConditionExample1.html) +* [Transaction Bundle 1](Bundle-AddRARecordTransactionExample1.html) + +The following set of examples are for the same patient, and constitute an addition flag and condition. The transaction Bundle here illustates an idempotent update by simply adding the new resources to the first transaction Bundle. + +* [Reasonable Adjustment flag 2](Flag-RAFlagExample2.html) +* [Condition 2](Condition-RAConditionExample2.html) +* [Transaction Bundle 2](Bundle-AddRARecordTransactionExample2.html) + +### Relevant Documentation + +* [Bundle](https://hl7.org/fhir/r4/bundle.html) +* [Transaction](https://hl7.org/fhir/r4/http.html#transaction) +* [Upsert](https://hl7.org/fhir/r4/http.html#upsert) \ No newline at end of file diff --git a/input/pagecontent/remove-fgm-flag-record.md b/input/pagecontent/remove-fgm-flag-record.md new file mode 100644 index 0000000..4c47c47 --- /dev/null +++ b/input/pagecontent/remove-fgm-flag-record.md @@ -0,0 +1,63 @@ +### Overview + +For high level requirements, see [Key purposes of the FGM Flag](index.html#fgm-key-purposes) + + +#### UseCase + +
+ + {%include remove-fgm-record-usecase.svg%} + +
+ +#### Scenarios + +```gherkin +Given a patient or their advocate revokes consent +And the consent is for reasonable adjustments +When a practioner records the consent +Then consent will be marked as inactive +And all flags will be deleted +And all conditions will be deleted +``` + +#### Workflow +

+ +A patient may revoke consent to share information about Reasonable Adjustment records and if they do, all records must be removed. + +

+ +
+ Remove Patient Flag record workflow BPMN diagram. +
+ +### System Interactions + +In the following sequence diagram, a patient revokes consent. The Consent resource is updated to reflect the patient dissent, and all adjustment records are deleted. + +
+ + {%include remove-fgm-record-sequence.svg%} + +
+ +The following resource types will be deleted from the record if consent is not granted i.e. + +* [Patient Flag](StructureDefinition-PatientFlag.html) +* [Programme Flag](StructureDefinition-ProgrammeFlag.html) +* [Condition Flag](StructureDefinition-FlagCondition.html) + +#### Example + +Multiple resources can be deleted using a transaction bundle. This [example delete transaction Bundle](Bundle-RemoveRARecordExample.html) demonstates deleting the following resources + +* [Patient Flag](Flag-RAPatientFlagExample1.html) example. +* [Programme Flag](Flag-RAFlagExample1.html) example. +* [Condition Flag](Condition-RAConditionExample1.html) example. + +### Relevant Documentation + +* [Bundle](https://hl7.org/fhir/r4/bundle.html) +* [Transaction](https://hl7.org/fhir/r4/http.html#transaction) \ No newline at end of file diff --git a/input/pagecontent/retrieve-fgm-flag-record.md b/input/pagecontent/retrieve-fgm-flag-record.md new file mode 100644 index 0000000..bb0bef9 --- /dev/null +++ b/input/pagecontent/retrieve-fgm-flag-record.md @@ -0,0 +1,151 @@ +### Overview + +For high level requirements, see [Key purposes of the FGM Flag](index.html#fgm-key-purposes) + +### Usecase + +A Patient Flag Record may be retrieved if it exists. It will be possible to determine that a adjustment flags exist by searching for a [Patient Flag](StructureDefinition-PatientFlag.html) with: + +- [Programme Flags](StructureDefinition-ProgrammeFlag.html) +- [Programme Flags](StructureDefinition-ProgrammeFlag.html) with a category of [NRAF](CodeSystem-PatientFlagCategory.html#PatientFlagCategory-NRAF) +- or the code [NRAF](CodeSystem-PatientFlagCategory.html#PatientFlagCategory-NRAF), + +
+ + {%include retrieve-fgm-record-usecase.svg%} + +
+ +#### Scenarios + +```gherkin +Given a practitioner must access a patients reasonable adjustment records +And consent has been provided +When the practitioner retrieves the reasonable adjustment records +Then all resources associated with reasonable adjustment records will be returned + +Given a practitioner must access a patients reasonable adjustment records +And no consent has been provided +When the practitioner attempts to retrieve the reasonable adjustment records +Then no resources will be returned + +Given a practitioner must access a patients reasonable adjustment records +And consent is revoked +When the practitioner updates the Consent resource to revoked +Then all other resources associated with reasonable adjustment records will be removed +``` + +### Workflow + +A practitioner confirms that a patient consents to share information about Reasonable Adjustment records. A patient may revoke consent to share information about Reasonable Adjustment records and if they do, all records must be removed. + +
+ Retrieve Patient Flag record workflow BPMN diagram. +
+ +### System Interaction + +
+ + {%include retrieve-fgm-record-sequence.svg%} + +
+ +### Queries + +Using [FHIR search](https://www.hl7.org/fhir/search.html) capabilities, it is possible to retrieve the reasonable adjustment records in several ways. + +#### Patient endpoint search + +This section describes how to query from the [Patient](http://www.hl7.org/fhir/R4/patient.html#search) endpoint using [FHIR search](https://www.hl7.org/fhir/search.html) + +This will return all associated flag resources for Reasonable Adjustments. + +``` +GET /Patient?identifier=9912003888&_has:Flag:patient:code=NRAF&_has:Flag:patient:category=NRAF&_revinclude=Flag:patient&_has:Consent:patient:category=NRAF&_revinclude=Consent:patient&_has:Condition:patient:category=NRAF&_revinclude=Condition:patient +``` + +This limits the search to patients thant have the identifier `9912003888` + +``` +identifier=9912003888 +``` + +This limits the search to patients that have Flag resources linked via patient and have the code NRAF, and also includes the resource in the returned searchset Bundle. + +``` +&_has:Flag:patient:code=NRAF&_revinclude=Flag:patient +``` + +This limits the search to patients that have Flag resources linked via patient and have the category NRAF, and also includes the resource in the returned searchset Bundle. + +``` +&_has:Flag:patient:category=NRAF&_revinclude=Flag:patient +``` + +This limits the search to patients that have Consent resources linked via patient and have the category NRAF, and also includes the resource in the returned searchset Bundle. + +``` +&_has:Consent:patient:category=NRAF&_revinclude=Consent:patient +``` + +This limits the search to patients that have Condition resources linked via patient and have the category NRAF, and also includes the resource in the returned searchset Bundle. + +``` +&_has:Condition:patient:category=NRAF&_revinclude=Condition:patient +``` + +The following queries will return all or some of the resources constituing a Reasonable Adjustments record, i.e. + +* [Flag Consent](StructureDefinition-FlagConsent.html) resource +* [Patient Flag](StructureDefinition-PatientFlag.html) resources +* [Programme Flag](StructureDefinition-ProgrammeFlag.html) resources +* [Flag Condition](StructureDefinition-FlagCondition.html) resources + +This query relies on the [FlagCategory](SearchParameter-FlagCategory.html) and [FlagCode](SearchParameter-FlagCode.html) SearchParameters. + +#### Flag endpoint search + +This section describes how to query from the [Flag](http://www.hl7.org/fhir/R4/flag.html#search) endpoint using [FHIR search](https://www.hl7.org/fhir/search.html) + +**NOTE:** For every additional record/resource added, the flag-detail element in the Patient Flag resource will need updated. See **TODO -- link to add interaction diagram**. + + + +If the [flag-detail extension](http://hl7.org/fhir/StructureDefinition/flag-detail) is used, then references to all Reasonable Adjustment resources can be included the [Patient Flag](StructureDefinition-PatientFlag.html) resource. + +This will return all associated flag resources for Reasonable Adjustments. + +``` +http://localhost:8080/fhir/Flag?patient.identifier=9912003888&_include=Flag:detail&_include=Flag:patient +``` + +This limits the search to patients thant have the identifier `9912003888` + +``` +patient.identifier=9912003888=9912003888 +``` + +This includes all references in the flag detail extension that have been defined in the [FlagDetail](SearchParameter-FlagDetail.html) SearchParameter. + +``` +&_include=Flag:detail +``` + +This includes the associated patient resource. + +``` +&_include=Flag:patient +``` + +This query relies on the [FlagCategory](SearchParameter-FlagCategory.html), [FlagCode](SearchParameter-FlagCode.html) and [FlagDetail](SearchParameter-FlagDetail.html) SearchParameters. + + +### Relevant Documentation + +* FHIR [Search](http://www.hl7.org/fhir/R4/search.html) +* [SearchParameters](https://www.hl7.org/fhir/R4/searchparameter.html) \ No newline at end of file diff --git a/sushi-config.yaml b/sushi-config.yaml index 95a7076..7f0c2ab 100644 --- a/sushi-config.yaml +++ b/sushi-config.yaml @@ -85,6 +85,9 @@ menu: Add Reasonable Adjustment Record: add-reasonable-adjustment-record.html Retrieve Reasonable Adjustment Record: retrieve-reasonable-adjustment-record.html Remove Reasonable Adjustment Record: remove-reasonable-adjustment-record.html + Add FGM Flag Record: add-fgm-flag-record.html + Retrieve FGM Flag Record: retrieve-fgm-flag-record.html + Remove FGM Flag Record: remove-fgm-flag-record.html Additional Examples: CPIS/FGM demo: additional-examples.html Basic Query Examples: basic-query-examples.html