diff --git a/paths/qoc_checkupList_set_status.yaml b/paths/qoc_checkupList_set_status.yaml index 958b33e..f945e49 100644 --- a/paths/qoc_checkupList_set_status.yaml +++ b/paths/qoc_checkupList_set_status.yaml @@ -1,7 +1,7 @@ post: tags: - Quality of Care - operationId: setPatientCallUpStatus + operationId: setPatientCallupStatus summary: Call-up status description: Set call-up status for patients in a care program. parameters: @@ -24,12 +24,23 @@ post: properties: careprogram: description: |- - The kind of chronic care that this care program caters to. Can be omitted in cases where this care program doesn't cover a generally accepted protocollized chronic care condition (Often, new research). + The kind of chronic care you want to set the call up status for. $ref: '../schemas/CareProgram-enum.yaml' callUpStatus: - $ref: '../schemas/callUpStatus-enum.yaml' + type: string + enum: + - byPolicy + - callUp + - dontCallUp + - scheduled + example: callUp employee: - $ref: ../schemas/employee-string.yaml + $ref: ../schemas/employee-alias.yaml + quarter: + $ref: ../schemas/date.yaml + description: |- + Callup plans are specific to a single quarter and are returned only when asking for callup lists with this quarter + as the `refDate`. Defaults to 'next quarter' (i.e. on April 5th, would default to July 1st). bsns: type: array items: diff --git a/paths/qoc_checkupList_{setKey}.yaml b/paths/qoc_checkupList_{setKey}.yaml index 8705108..92e4f4c 100644 --- a/paths/qoc_checkupList_{setKey}.yaml +++ b/paths/qoc_checkupList_{setKey}.yaml @@ -1,10 +1,35 @@ get: - operationId: checkUpListSet + operationId: callupList tags: - Quality of Care summary: Call-up status description: |- - Load call-up status for patients in a care program. Returns each patient in a care program along with the progress on required or suggested measurements indicated for this care program. + Load call-up status for patients in a care program. + + Returns each patient in a care program along with the progress on required or suggested measurements indicated for this care program. + Also includes any custom callup policies as part of the response, and the callup plan for this quarter. + + Every quarter, each patient is assigned a callup plan for just that quarter (it resets for every quarter). A callup plan + is either 'call them up' or 'do not call them up'. Most patients start off in an 'open' state where no decision on whether + to call them up has been made yet. + + Callup policies are different: They aren't per quarter; instead they represent medical decisions that impact their chronic + care. For example, 'this patient is not available for checkups until next year', or 'this patient is an amputee; do not + consider a missing analysis of the feet as relevant'. They can have an explicitly chosen end date. + + Call up plans have a default. Usually it is 'open' (no decision yet made on whether to call them up this quarter or not), + but explicitly set policies as well as implicit policies chosen by the care group can affect this. For example, if a + policy is set that the patient is not available for a few quarters, the plan defaults to 'do not call up' instead. + + To enable making clear to the user via the UI exactly what choices have been made, the API services differentiates between + what the default behaviour of a plan is; this is called the `byPolicy` plan - versus what the user explicitly chose. + + In other words, a patient that defaults to 'do not call up' can be differentiated from a patient where an explicit choice + was made to set their callup plan for the quarter to 'do not call up'. A patient that has defaulted to 'do not call up' can + have that value change when the policies change; a patient that was explicitly set to 'do not call up' will not change the + plan even if underlying policies change. + + Policies are set vie the `/qoc/callupPolicy` endpoint. parameters: - name: setKey in: path @@ -89,6 +114,7 @@ get: format: int32 minimum: 1 maximum: 99999999 + example: 1099999 required: - name indicators: @@ -128,24 +154,64 @@ get: format: int32 description: |- An index (0-based) into the `doctors` entry: This is the GP responsible for this patient. + chosenStatus: + type: string + description: |- + The callup plan explicitly chosen via an earlier call to the `/qoc/callupList/setStatus` endpoint. + + The chosen status always defaults to `byPolicy` which indicates that the actual status will be derived + by analysing explicit and implicit policies. This 'by policy' status is provided via `byPolicyStatus`. + enum: + - byPolicy + - callUp + - dontCallUp + - scheduled + example: byPolicy + byPolicyStatus: + type: string + description: |- + The callup plan that applies if no explicit choice is made (i.e. the default choice - `byPolicy`). + + This status is derived by analysing the care group's policies as well as any explicit policies set + via the `/qoc/callupPolicy` endpoint. + + `open` means: Whether to call this patient up this quarter hasn't been decided yet, and the policies + do not suggest either choice as a default. + enum: + - open + - callUp + - dontCallUp status: - $ref: '../schemas/callUpStatus-enum.yaml' + type: string + description: |- + Provided by convenience: It's the value of `chosenStatus`, unless that is `byPolicy`, in which case + it is the value of `byPolicyStatus`. In other words, the status that applies to this patient. + enum: + - open + - callUp + - dontCallUp + - scheduled + example: open address1: type: string description: |- The first line of this patient's postal address (Street name and number, generally). + example: Dorpsstraat 1 city: type: string description: Patient lives in this city or township. + example: Nowhereville postcode: type: string description: Postcode of the patient. + example: 1234AA bsn: type: integer minimum: 1 maximum: 999999999 format: int32 description: The BSN (dutch social security number) of the patient. + example: 123456789 dob: $ref: ../schemas/date.yaml description: Date of birth of the patient. @@ -153,6 +219,7 @@ get: type: string format: email description: Email address of the patient. + example: foo@bar.fake state: type: string description: |- @@ -167,9 +234,69 @@ get: * `2`-`8` – `2` is like `1`, except the measurement lasts for 2 quarters up to 8 quarters. * `+` – The measurement lasts for 9 or more quarters (for example, the measurement only needs to be done once ever and it has been done). * `x` – unknown situation (should not occur). + example: 0017-R-0 + policies: + type: array + description: |- + Lists all explicitly chosen policies (set via `qoc/callupPolicy`) that apply to this + patient. + items: + type: object + properties: + 'type': + type: string + enum: + - PatientIndicator + - PatientSnoozed + description: |- + The kind of policy this is. + + `PatientSnoozed` indicates the patient is not available for a limited period of time and thus isn't a candidate for calling up. + + `PatientIndicator` indicates an alternate frequency has been chosen for a specific indicator for this specific patient. + example: PatientIndicator + indicatorKey: + type: string + description: |- + Only set for `PatientIndicator`. Which indicator has a custom frequency. + example: ZEL-dm2-bp-result + expires: + type: string + $ref: ../schemas/date.yaml + description: Date in ISO8601 format; if omitted does not expire. It is considered expired _on_ the stated date. + frequency: + type: string + description: |- + For type `PatientIndicator` only (otherwise, not sent). Indicates that this indicator should be measured + with a different frequency than what this care program by default suggests. The letter for this indicator in the `state` string + takes this alternate frequency into account (or, is rendered as a `-`, indicating 'not relevant', if `never` is the custom frequency). + enum: + - quarter + - sixMonths + - year + - twoYear + - threeYear + - fiveYear + - never + example: sixMonths + reason: + type: string + description: |- + A reason for a policy can be provided when it is set, and is returned here. Omitted if not provided. + example: Jannie zit tot eind december op een boorplatform. + employee: + $ref: ../schemas/employee-string.yaml + timestamp: + type: string + description: The policy was created (set) at this time. + $ref: ../schemas/dateTimeZ.yaml + required: + - type required: - patUnid - doctor + - byPolicyStatus + - chosenStatus - status - dob - state diff --git a/paths/qoc_checkupPolicy.yaml b/paths/qoc_checkupPolicy.yaml index 3e0f8ae..4a3db5c 100644 --- a/paths/qoc_checkupPolicy.yaml +++ b/paths/qoc_checkupPolicy.yaml @@ -3,29 +3,37 @@ get: - Quality of Care operationId: getCallupPolicy summary: Call-up policy - description: Gets all call-up policies of a patient for all indicators in which the patient participates, or for a specific indicator. + description: Gets all call-up policies of a patient for all indicators in which the patient participates, or for a specific indicator. Parameters are optional and simply filter the response; in other words, without parameters all policies are returned. parameters: - name: policyType in: query schema: - $ref: ../schemas/CallupPolicyType-enum.yaml + $ref: ../schemas/CallupPolicyType-enum-short.yaml - name: patUnid in: query - schema: + schema: $ref: ../schemas/pat-patUnid.yaml + description: Show only policies for patients that match this unid. Not allowed if asking for `UserIndicator`. - name: bsn in: query schema: $ref: ../schemas/pat-BSN.yaml + description: Show only policies for patients that match this bsn. Not allowed if asking for `UserIndicator`. - name: indicatorKey in: query - description: The version suffix of the indicator is ignored. - schema: + description: The version suffix of the indicator is ignored. Only for type `UserIndicator` and `PatientIndicator`. + schema: type: string example: ZOO-dm2-hb-1 + - name: refDate + in: query + description: Return only policies that haven't expired at this date. Defaults to 'next quarter'). + schema: + type: string + $ref: ../schemas/date.yaml responses: '200': - description: A set of policies for the supplied patient or for the combination of a patient and an indicator. For the latter the set contains 0 or 1 policies. + description: All policies that match the supplied filter conditions. content: 'application/json': schema: @@ -34,7 +42,7 @@ get: type: object properties: policyType: - $ref: ../schemas/CallupPolicyType-enum.yaml + $ref: ../schemas/CallupPolicyType-enum-short.yaml patUnid: $ref: ../schemas/pat-patUnid.yaml indicatorKey: @@ -42,14 +50,18 @@ get: example: ZOO-dm2-hb userId: type: integer - doNotCallupUntil: + example: 123456 + expires: $ref: ../schemas/date.yaml + example: "2026-04-01" frequency: $ref: ../schemas/CallupPolicyFrequency.yaml + example: never reason: type: string + example: Zit op een boorplatform. employee: - type: string + $ref: ../schemas/employee-string.yaml timestamp: $ref: ../schemas/dateTime.yaml '401': @@ -62,54 +74,42 @@ post: operationId: postCallupPolicy summary: Call-up policy description: |- - Set a call-up policy for a combination of a patient and/ or an indicator. A call-up policy for filters the patient from the call-up list with a certain frequency or until a specific end date has passed. The calculation of the (call-up) indicator is not affected by this setting. It is solely meant as a tool for the general practitioner. A patient is specified using a `patUnid` or a bsn. Both are checked in the GPIS import database for existance. - requestBody: + Set a call-up policy. Policies last until a specific expiry (or forever). See the descriptions of policy types to get an idea of what policies do and what they represent. + requestBody: content: 'application/json': schema: type: object properties: policyType: - $ref: ../schemas/CallupPolicyType-enum.yaml + $ref: ../schemas/CallupPolicyType-enum-full.yaml patUnid: $ref: ../schemas/pat-patUnid.yaml + example: 123456 bsn: $ref: ../schemas/pat-BSN.yaml indicatorKey: description: |- - The key of the indicator as listed in the indicator set. The version of the indicator is ignored. That means that any suffix in the form: dash followed by a integer is ignored. The policy is therefore set for a indicator, and not for a specific version of the indicator. E.g. for ZOO-dm2-hb and not for ZOO-dm2-hb-3. + The key of the indicator as listed in the indicator set. The version of the indicator is ignored (if the string ends in a dash and a number, those are stripped). Only relevant for `IndicatorUser` and `UserIndicator`. example: ZOO-dm2-hb-3 type: string - userId: - type: integer - doNotCallupUntil: + reason: + type: string + description: An optional human written reason for why the policy is being applied. + example: Zit op een boorplatform. + expires: description: |- - The first date the patient will be taken (again) in account in a call-up list. This date is always compared to a reference date, which is not necessary today. + If provided, this policy does not apply on and after this date. Mandatory for certain types of policy. $ref: ../schemas/date.yaml frequency: $ref: ../schemas/CallupPolicyFrequency.yaml - reason: - description: The reason for which the patient is temporary excluded from the call-up plan. - type: string employee: $ref: ../schemas/employee-string.yaml required: - policyType - - indicatorKey - employee - oneOf: - - required: - - patUnid - not: - required: - - bsn - - required: - - bsn - not: - required: - - patUnid responses: - '200': + '204': description: If the policy has been processed without any errors. '401': $ref: '../zoo-api.yaml/#/components/responses/NoAuth' @@ -120,24 +120,24 @@ delete: - Quality of Care operationId: deleteCallupPolicy summary: Call-up policy - description: |- - Unset a call-up policy for a combination of a patient and an indicator. This withdraws all previous set policies. - parameters: + description: Unset a call-up policy. + parameters: - name: policyType in: query schema: - $ref: ../schemas/CallupPolicyType-enum.yaml + $ref: ../schemas/CallupPolicyType-enum-short.yaml - name: patUnid in: query schema: $ref: ../schemas/pat-patUnid.yaml + example: 123456 - name: bsn in: query schema: $ref: ../schemas/pat-BSN.yaml - name: indicatorKey in: query - description: The version suffix of the indicator is ignored (if any). + description: The version suffix of the indicator is ignored (if any). Only relevant for `IndicatorUser` and `UserIndicator`. schema: type: string example: ZOO-dm2-hb-1 diff --git a/paths/qoc_indicatorsets.yaml b/paths/qoc_indicatorsets.yaml index b7fe80a..2689188 100644 --- a/paths/qoc_indicatorsets.yaml +++ b/paths/qoc_indicatorsets.yaml @@ -42,7 +42,7 @@ get: properties: key: type: string - description: Key of the indicator set. + description: Key of the indicator set or casefinder. name: type: string description: |- @@ -50,7 +50,7 @@ get: subName: type: string description: |- - Something like `Oproepen` or `Rapportage 75+` – describes the purpose of this indicatorset; a number of sets all with the same name but with different subNames can exist, representing different views and protocol approaches to the same care program. + Something like `Oproepen` or `Rapportage 75+` – describes the purpose of this indicatorset; a number of sets all with the same name but with different subNames can exist, representing different views and protocol approaches to the same care program. Omitted if not relevant (in that case `name` describes this set/casefinder fully). description: type: string description: A longer description in dutch describing e.g. the chronic care condition covered by this set. @@ -65,8 +65,8 @@ get: example: X 'type': type: string - description: Always "indicatorset". - example: indicatorSet + description: Either "indicatorset" or "casefinding". + example: indicatorset careprogram: $ref: '../schemas/CareProgram-enum.yaml' description: The kind of chronic care that this care program caters to. Can be omitted in cases where this care program doesn't cover a generally accepted protocolized chronic care condition. That is often the case with new research projects. @@ -74,6 +74,10 @@ get: type: boolean description: |- If this 'flavour' (as per `subName`) is intended to be used to call up patients and look to the future (this will be `true`) or if this set's intent is reporting and introspection, looking to the past (this will be `false`). + url: + type: string + description: |- + Only provided for type "casefinder". Casefinders are not available via the API; redirect the user to this URL. '401': $ref: '../zoo-api.yaml/#/components/responses/NoAuth' '403': diff --git a/schemas/CallUpStatus-enum.yaml b/schemas/CallUpStatus-enum.yaml deleted file mode 100644 index 728934c..0000000 --- a/schemas/CallUpStatus-enum.yaml +++ /dev/null @@ -1,6 +0,0 @@ -type: string -enum: - - open - - callUp - - dontCallUp - - scheduled \ No newline at end of file diff --git a/schemas/CallupPolicyFrequency.yaml b/schemas/CallupPolicyFrequency.yaml index f24c27f..dde4c33 100644 --- a/schemas/CallupPolicyFrequency.yaml +++ b/schemas/CallupPolicyFrequency.yaml @@ -1,5 +1,5 @@ description: |- - The frequency in which the patient should be called up for the chosen indicator. If set to never, then the patient is removed from any call-up plan, until the policy is set or the end date has passed. + The stated patient should have the stated indicator checked with this frequency instead of the standard frequency as per the care protocol for this care program. The callup state is modified accordingly, except for the special value of `never` which means te callup state is reported as `-` ('not relevant for this patient'). type: string enum: - quarter @@ -8,4 +8,5 @@ enum: - twoYear - threeYear - fiveYear - - never \ No newline at end of file + - never +example: never \ No newline at end of file diff --git a/schemas/CallupPolicyType-enum-full.yaml b/schemas/CallupPolicyType-enum-full.yaml new file mode 100644 index 0000000..7bd4633 --- /dev/null +++ b/schemas/CallupPolicyType-enum-full.yaml @@ -0,0 +1,26 @@ +description: |- + Call-up policies type. Various types are supported: + +
+
PatientIndicator
+
A policy that applies to a specific patient for a specific indicator. For example, a policy might capture the notion "This patient is an amputee and therefore, the frequency of doing foot inspections for chronic diabetes care should be 'never', forever". Or "This patient is going to receive an eye operation next year, therefore funduscopy is not useful, and the specialist team managing their eye care is responsible for it until after the operation and its recovery. Frequency set to 'never', until 2026-08-01". Such policies always refer to a specific patient and a specific indicator, may or may not have an expiry date, and always have a custom frequency. + + The effect of this policy is to modify the 'callup state' for that patient/indicator combination. For example, the amputee would receive a `-` state for 'foot inspection' (indicating: Foot inspection is not relevant for this patient) instead of a `0` (indicating: Foot inspection must be done this quarter). Naturally, any policy that expires _before_ the `refDate` of a callup list you're asking for doesn't apply.
+ +
PatientSnoozed
+
A policy that applies to a specific patient for a certain care program type (e.g. `COPD`), and indicates that providing chronic care at the GP level is not possible for a limited time. For longer 'snoozing' the advice is generally to set the GPIS based registration of chronic care participation (i.e. the value 'COKZ' (COPD chronic care participation) to 'No'), but when the situation is temporary and a medical operator knows when the situation ends, this policy can be used instead, which has the advantage of restoring the patient to chronic care reporting automatically when the policy is expires. `expiry` is mandatory for this type of policy. + + The effect of this policy is to default the patient's call up plan (the `chosenStatus` is `byPolicy`) to `doNotCallup` until the policy expires.
+ +
UserIndicator
+
WARNING: Not current available (not implemented yet). + + This policy applies to a specific indicator, for all patients. Can be used to represent "our ECG machine is broken until 2025-10-01" for example, or "providing flu injections is done by a different team than DM chronic care therefore this indicator does not apply to me". + + The effect of this policy is to mark it as 'not relevant' for all patients. It is not possible to configure an alternate frequency; that would be a modification of the protocol itself which can be implemented by contacting Zorg op Orde to discuss a customised protocol. +type: string +enum: + - PatientIndicator + - PatientOnly + - IndicatorUser +example: PatientIndicator \ No newline at end of file diff --git a/schemas/CallupPolicyType-enum-short.yaml b/schemas/CallupPolicyType-enum-short.yaml new file mode 100644 index 0000000..94e669e --- /dev/null +++ b/schemas/CallupPolicyType-enum-short.yaml @@ -0,0 +1,6 @@ +type: string +enum: + - PatientIndicator + - PatientOnly + - IndicatorUser +example: PatientIndicator \ No newline at end of file diff --git a/schemas/CareProgram-enum.yaml b/schemas/CareProgram-enum.yaml index 127e303..3b87055 100644 --- a/schemas/CareProgram-enum.yaml +++ b/schemas/CareProgram-enum.yaml @@ -17,6 +17,7 @@ description: |-
Dermatoscopie
Dermatoscopy / (risk of) skin cancer
FractuurPreventie
Fracture prevention - often part of elderly care.
GecMonitoring
An assortment of indicators useful for monitoring a GEC (Geïntegreerd Eerstelijns Centrum / integrated primary care).
+
Nierschade
(risk of) kidney failure
type: string example: COPD \ No newline at end of file diff --git a/schemas/employee-string.yaml b/schemas/employee-string.yaml index 6473fa2..9a14a86 100644 --- a/schemas/employee-string.yaml +++ b/schemas/employee-string.yaml @@ -1,2 +1,3 @@ type: string -description: The employee that is setting the call-up status. Any string is accepted, but it is recommended to use a employee code derived from this API. \ No newline at end of file +description: A string that identifies the employee who is setting this policy. +example: Mien Dobbelsteen \ No newline at end of file diff --git a/schemas/pat-DOB.yaml b/schemas/pat-DOB.yaml index de4d86b..5fdd529 100644 --- a/schemas/pat-DOB.yaml +++ b/schemas/pat-DOB.yaml @@ -2,6 +2,7 @@ description: |- Patient's date of birth. Note that by convention, patients whose birthdate is unknown (rare, but can happen in certain asylum seeker cases) - pick a date and tend to pick either `xxxx-01-01` or `xxxx-07-01`. Can, in rare cases, be unavailable - if birth date is not known. + pick a date and tend to pick either `xxxx-01-01` or `xxxx-07-01`. + Can, in rare cases, be unavailable - if birth date is not known; in that case, `null` is sent. $ref: ./date.yaml diff --git a/zoo-api.yaml b/zoo-api.yaml index 1f5668f..dbefa91 100644 --- a/zoo-api.yaml +++ b/zoo-api.yaml @@ -249,5 +249,3 @@ components: expExpires atOPTIONAL If included, the request must not be received after this time. May be up to 10 minutes in the future. The difference between the exp claim and the iat must be 20 minutes or less and iat < exp. nbfNot beforeOPTIONAL If included, the request must not be received before this time. Should not be set in the future. - -