diff --git a/pages/appointments/appointments_serviceid_configuration.md b/pages/appointments/appointments_serviceid_configuration.md index 2fbaa0678..8757437f9 100644 --- a/pages/appointments/appointments_serviceid_configuration.md +++ b/pages/appointments/appointments_serviceid_configuration.md @@ -1,35 +1,35 @@ --- -title: Provider system configuration for service ID filtering +title: Provider system configuration for service filtering keywords: appointments design tags: [design,appointments] sidebar: appointments_sidebar permalink: appointments_serviceid_configuration.html -summary: "Configuration to support the rollout of the service ID filtering feature" +summary: "Configuration to support the rollout of the service filtering feature" ---
-Service ID filtering in a provider system **SHALL** be controlled by two levels of configuration: +Service filtering in a provider system **SHALL** be controlled by two levels of configuration: 1. a supplier-controlled configuration enablement switch ("supplier switch") 2. organisation-controlled configuration ("organisation configuration"), incorporating an organisation enablement switch ("organisation switch") -The supplier switch allows the service ID filtering configuration to be made visible to selected (or all) organisations using the supplier's provider system. +The supplier switch allows the service filtering configuration to be made visible to selected (or all) organisations using the supplier's provider system. -Once the service ID configuration screens are made available to an organisation, a user at the organisation can configure service ID filtering, and once configuration is completed, switch service ID filtering on so that the configuration takes effect upon the API, for their organisation. +Once the service configuration screens are made available to an organisation, a user at the organisation can configure service filtering, and once configuration is completed, switch service filtering on so that the configuration takes effect upon the API, for their organisation. ## Supplier switch ## -The visibility of the service ID filtering configuration in a provider system **SHALL** be controlled by a global supplier system switch, with three states: +The visibility of the service filtering configuration in a provider system **SHALL** be controlled by a global supplier system switch, with three states: 1. OFF 2. ON AT SELECTED ORGANISATIONS - this state requires an associated selected organisation list 3. ON -{% include note.html content="The supplier switch allows service ID filtering configuration to be made available to provider organisations in a controlled manner, and not before Directory of Services changes have been made to support them." %} +{% include note.html content="The supplier switch allows service filtering configuration to be made available to provider organisations in a controlled manner, and not before Directory of Services changes have been made to support them." %} The supplier switch, and associated selected organisation list **SHALL**: -- control service ID filtering functionality as described in the sub-sections below +- control service filtering functionality as described in the sub-sections below - only be controlled by appropriate staff at the supplier - be changed and applied quickly to the supplier's system without requiring a code change or software release - be initially defaulted to OFF, and empty @@ -39,43 +39,43 @@ The supplier switch, and associated selected organisation list **SHALL**: - current and previous state of the switch - changes to the selected organisation list (if any) -{% include important.html content="The configuration visibility switch does not affect service ID filtering changes in an appointments consumer in the same supplier system, such as displaying service name when searching for free slots." %} +{% include important.html content="The configuration visibility switch does not affect service filtering changes in an appointments consumer in the same supplier system, such as displaying service name when searching for free slots." %} ### Supplier switch set to OFF ### -When the service ID supplier switch is set to OFF: +When the service filtering supplier switch is set to OFF: - For ALL organisations in the supplier's system: - - the organisation-controlled service ID configuration **SHALL NOT** be visible to users, and **SHALL NOT** take effect upon the API (regardless of the value of the organisation switch) + - the organisation-controlled service configuration **SHALL NOT** be visible to users, and **SHALL NOT** take effect upon the API (regardless of the value of the organisation switch) ### Supplier switch set to ON AT SELECTED ORGANISATIONS ### -When the service ID supplier switch is set to ON AT SELECTED ORGANISATIONS: +When the service filtering supplier switch is set to ON AT SELECTED ORGANISATIONS: - For organisations in the selected organisation list that are eligible to use GP Connect: - the organisation configuration **SHALL** be visible - - the effect of service ID filtering upon the API **SHALL** be dependent on the organisation configuration + - the effect of service filtering upon the API **SHALL** be dependent on the organisation configuration - For organisations NOT held in the selected organisation list: - the organisation configuration **SHALL NOT** be visible, and **SHALL NOT** take effect upon the API (regardless of the value of the organisation switch) ### Supplier switch set to ON ### -When the service ID supplier switch is set to ON: +When the service filtering supplier switch is set to ON: - For ALL organisations in the supplier's system that are eligible to use GP Connect: - the organisation configuration **SHALL** be visible - - the effect of service ID filtering upon the API **SHALL** be dependent on the organisation configuration + - the effect of service filtering upon the API **SHALL** be dependent on the organisation configuration -{% include note.html content="This state has been included so that when service ID filtering configuration can be made available to all organisations using the supplier's system, there is no need to continue to maintain the selected organisation list." %} +{% include note.html content="This state has been included so that when service filtering configuration can be made available to all organisations using the supplier's system, there is no need to continue to maintain the selected organisation list." %} ## Organisation configuration ## -The organisation configuration for service ID filtering **SHALL** be used by staff within a provider organisation to: +The organisation configuration for service filtering **SHALL** be used by staff within a provider organisation to: - set up a list of services for their organisation (taken from the service(s) in DOS provided by the organisation) - assign services to schedules (or schedule "templates") -- enable or disable service ID filtering for their organisation +- enable or disable service filtering for their organisation {% include important.html content="See [supplier switch](#supplier-switch) above for conditions when the organisation configuration is visible to a provider organisation." %} @@ -119,7 +119,7 @@ The *Service by ODS Code* endpoint in the DOS API **MUST NOT** be used as this w ### Linking services to schedules ### -The organisation configuration **SHALL** include the ability for a user to link services to schedules, so that service ID filtering can return free slots for a service. +The organisation configuration **SHALL** include the ability for a user to link services to schedules, so that service filtering can return free slots for a service. {% include important.html content="The term schedule (in line with FHIR nomenclature) is used to indicate a grouping of slots, however in provider systems these are typically called sessions or rotas, and in fact the linking may occur to session or rota templates, rather than to instances of sessions/rotas." %} @@ -156,11 +156,11 @@ If a schedule is amended to become 'GP Connect bookable' and the [organisation s ### Organisation switch ### -The organisation configuration **SHALL** include a service ID filtering enablement switch that allows a user at a provider organisation to enable or disable service ID filtering for their organisation. +The organisation configuration **SHALL** include a service filtering enablement switch that allows a user at a provider organisation to enable or disable service filtering for their organisation. The organisation switch **SHALL**: -- control service ID filtering enablement for the current organisation +- control service filtering enablement for the current organisation - only be controlled by appropriate staff logged on at the provider organisation - allow two states (ON and OFF), and be initially defaulted to OFF - take effect immediately @@ -169,8 +169,8 @@ The organisation switch **SHALL**: - user responsible for the change - current and previous state of the switch -{% include note.html content="The purpose of the organisation switch is so that organisations can set up their list of service IDs and link them to sessions/rotas, before they enable service ID filtering. If the feature was deployed in the enabled state without the list of service IDs set up, no slots would be returned to consumers that requested free slots for a specific service. -
In addition, some organisations may not wish to or need to use service ID filtering, such as those with a single DOS service. " %} +{% include note.html content="The purpose of the organisation switch is so that organisations can set up their list of service IDs and link them to sessions/rotas, before they enable service filtering. If the feature was deployed in the enabled state without the list of service IDs set up, no slots would be returned to consumers that requested free slots for a specific service. +
In addition, some organisations may not wish to or need to use service filtering, such as those with a single DOS service. " %} {% include important.html content="Please note if the [supplier switch](#supplier-switch) is set to OFF, or set to ON AT SELECTED ORGANISATIONS and the current organisation is not in the selected organisation list, the organisation configuration including the organisation switch **SHALL NOT** be visible, and **SHALL NOT** take effect upon the API, regardless of the value of the organisation switch." %} @@ -178,7 +178,7 @@ The organisation switch **SHALL**: When the organisation switch is set to OFF: -- service ID filtering in the API **SHALL NOT** take effect +- service filtering in the API **SHALL NOT** take effect - `schedule.actor:healthcareservice` parameter on [Search for free slots](appointments_use_case_search_for_free_slots.html#search-parameters) **SHALL** be ignored - ... @@ -188,7 +188,7 @@ When the organisation switch is set to OFF: When the organisation switch is set to ON: -- service ID filtering in the API **SHALL** take effect +- service filtering in the API **SHALL** take effect - ... {% include todo.html content="List areas to enable" %} diff --git a/pages/appointments/appointments_serviceid_filtering.md b/pages/appointments/appointments_serviceid_filtering.md index aef1a261b..8dfef8607 100644 --- a/pages/appointments/appointments_serviceid_filtering.md +++ b/pages/appointments/appointments_serviceid_filtering.md @@ -1,5 +1,5 @@ --- -title: Appointment Management service ID filtering +title: Appointment Management service filtering keywords: appointments design tags: [design,appointments] sidebar: appointments_sidebar diff --git a/pages/appointments/appointments_use_case_amend_an_appointment.md b/pages/appointments/appointments_use_case_amend_an_appointment.md index 11d5f4fbc..d58851143 100644 --- a/pages/appointments/appointments_use_case_amend_an_appointment.md +++ b/pages/appointments/appointments_use_case_amend_an_appointment.md @@ -119,8 +119,8 @@ Provider systems: - SHALL populate `serviceType.text` with the practice defined slot type description, and where available `serviceCategory.text` with a practice defined schedule type description (may be called session name or rota type). - SHALL populate a reference to a `HealthcareService` in the `Appointment.participant.actor` element where: - - the Appointment is [linked to a service](appointments_serviceid_configuration.html#linking-services-to-schedules) set up for service ID filtering - - and the service ID filtering [organisation switch](appointments_serviceid_configuration.html#organisation-switch) is set to ON + - the Appointment is [linked to a service](appointments_serviceid_configuration.html#linking-services-to-schedules) set up for service filtering + - and the service filtering [organisation switch](appointments_serviceid_configuration.html#organisation-switch) is set to ON - SHALL meet [General FHIR resource population requirements](development_fhir_resource_guidance.html#general-fhir-resource-population-requirements) populating all fields where data is available, excluding those listed below diff --git a/pages/appointments/appointments_use_case_book_an_appointment.md b/pages/appointments/appointments_use_case_book_an_appointment.md index c31f0deaf..6ae5482f8 100644 --- a/pages/appointments/appointments_use_case_book_an_appointment.md +++ b/pages/appointments/appointments_use_case_book_an_appointment.md @@ -43,7 +43,7 @@ Consumer systems SHALL display the following fields upon a successful booking in - End date and time, or duration - Delivery channel (in-person, telephone, video) - Slot type and schedule type (see `Appointment.serviceType` and `Appointment.serviceCategory`) -- Service name (where present, see [service ID filtering](appointments_serviceid_filtering.html) for more information) +- Service name (where present, see [service filtering](appointments_serviceid_filtering.html) for more information) - Location name and address - Practitioner role (e.g. General Medical Practitioner, Nurse) - Practitioner name and gender @@ -164,8 +164,8 @@ Provider systems: - SHALL populate `Appointment.serviceType.text` with the practice defined slot type description, and where available `Appointment.serviceCategory.text` with a practice defined schedule type description (may be called session name or rota type). - SHALL populate a reference to a `HealthcareService` in the `Appointment.participant.actor` element where: - - the Appointment is [linked to a service](appointments_serviceid_configuration.html#linking-services-to-schedules) set up for service ID filtering - - and the service ID filtering [organisation switch](appointments_serviceid_configuration.html#organisation-switch) is set to ON + - the Appointment is [linked to a service](appointments_serviceid_configuration.html#linking-services-to-schedules) set up for service filtering + - and the service filtering [organisation switch](appointments_serviceid_configuration.html#organisation-switch) is set to ON - SHALL meet [General FHIR resource population requirements](development_fhir_resource_guidance.html#general-fhir-resource-population-requirements) populating all fields where data is available, excluding those listed below diff --git a/pages/appointments/appointments_use_case_cancel_an_appointment.md b/pages/appointments/appointments_use_case_cancel_an_appointment.md index 5d224e677..381d3b09f 100644 --- a/pages/appointments/appointments_use_case_cancel_an_appointment.md +++ b/pages/appointments/appointments_use_case_cancel_an_appointment.md @@ -104,8 +104,8 @@ Provider systems: - SHALL populate `serviceType.text` with the practice defined slot type description, and where available `serviceCategory.text` with a practice defined schedule type description (may be called session name or rota type). - SHALL populate a reference to a `HealthcareService` in the `Appointment.participant.actor` element where: - - the Appointment is [linked to a service](appointments_serviceid_configuration.html#linking-services-to-schedules) set up for service ID filtering - - and the service ID filtering [organisation switch](appointments_serviceid_configuration.html#organisation-switch) is set to ON + - the Appointment is [linked to a service](appointments_serviceid_configuration.html#linking-services-to-schedules) set up for service filtering + - and the service filtering [organisation switch](appointments_serviceid_configuration.html#organisation-switch) is set to ON - SHALL meet [General FHIR resource population requirements](development_fhir_resource_guidance.html#general-fhir-resource-population-requirements) populating all fields where data is available, excluding those listed below diff --git a/pages/appointments/appointments_use_case_read_an_appointment.md b/pages/appointments/appointments_use_case_read_an_appointment.md index ed4885d2e..e36fdf230 100644 --- a/pages/appointments/appointments_use_case_read_an_appointment.md +++ b/pages/appointments/appointments_use_case_read_an_appointment.md @@ -85,8 +85,8 @@ Provider systems: - SHALL populate `Appointment.serviceType.text` with the practice defined slot type description, and where available `Appointment.serviceCategory.text` with a practice defined schedule type description (may be called session name or rota type). - SHALL populate a reference to a `HealthcareService` in the `Appointment.participant.actor` element where: - - the Appointment is [linked to a service](appointments_serviceid_configuration.html#linking-services-to-schedules) set up for service ID filtering - - and the service ID filtering [organisation switch](appointments_serviceid_configuration.html#organisation-switch) is set to ON + - the Appointment is [linked to a service](appointments_serviceid_configuration.html#linking-services-to-schedules) set up for service filtering + - and the service filtering [organisation switch](appointments_serviceid_configuration.html#organisation-switch) is set to ON - SHALL meet [General FHIR resource population requirements](development_fhir_resource_guidance.html#general-fhir-resource-population-requirements) populating all fields where data is available, excluding those listed below diff --git a/pages/appointments/appointments_use_case_retrieve_a_patients_appointments.md b/pages/appointments/appointments_use_case_retrieve_a_patients_appointments.md index 92fadc0f3..53dcbcd6c 100644 --- a/pages/appointments/appointments_use_case_retrieve_a_patients_appointments.md +++ b/pages/appointments/appointments_use_case_retrieve_a_patients_appointments.md @@ -38,7 +38,7 @@ Consumer systems SHALL support the following fields in order to provide the full - End date and time, or duration - Delivery channel (in-person, telephone, video) - Slot type and schedule type (see `Appointment.serviceType` and `Appointment.serviceCategory`) -- Service name (where present, see [service ID filtering](appointments_serviceid_filtering.html) for more information) +- Service name (where present, see [service filtering](appointments_serviceid_filtering.html) for more information) - Location name and address - Practitioner role (e.g. General Medical Practitioner, Nurse) - Practitioner name and gender @@ -126,8 +126,8 @@ Provider systems: - SHALL populate `Appointment.serviceType.text` with the practice defined slot type description, and where available `Appointment.serviceCategory.text` with a practice defined schedule type description (may be called session name or rota type). - SHALL populate a reference to a `HealthcareService` in the `Appointment.participant.actor` element where: - - the Appointment is [linked to a service](appointments_serviceid_configuration.html#linking-services-to-schedules) set up for service ID filtering - - and the service ID filtering [organisation switch](appointments_serviceid_configuration.html#organisation-switch) is set to ON + - the Appointment is [linked to a service](appointments_serviceid_configuration.html#linking-services-to-schedules) set up for service filtering + - and the service filtering [organisation switch](appointments_serviceid_configuration.html#organisation-switch) is set to ON - SHALL meet [General FHIR resource population requirements](development_fhir_resource_guidance.html#general-fhir-resource-population-requirements) populating all fields where data is available, excluding those listed below diff --git a/pages/appointments/appointments_use_case_search_for_free_slots.md b/pages/appointments/appointments_use_case_search_for_free_slots.md index f83ead600..a08fe36a4 100644 --- a/pages/appointments/appointments_use_case_search_for_free_slots.md +++ b/pages/appointments/appointments_use_case_search_for_free_slots.md @@ -61,7 +61,7 @@ Consumer systems SHALL send the following parameters in the request: Where a Consumer system has used [Directory of Services (DOS) to locate a service to book at](appointments_service_discovery.html#directory-of-services-dos---currently-for-uec-consumers-only), the consumer system SHALL send the following parameter in the request: -- The `service.identifier` parameter with the service ID of the chosen DOS service, e.g. `service.identifier=https://fhir.nhs.uk/Id/uec-dos-service-id|1000123` (see [Service ID filtering](appointments_serviceid_filtering.html) for more information) +- The `service.identifier` parameter with the service ID of the chosen DOS service, e.g. `service.identifier=https://fhir.nhs.uk/Id/uec-dos-service-id|1000123` (see [Service filtering](appointments_serviceid_filtering.html) for more information) Consumer systems SHOULD send the following parameters in the request: @@ -103,7 +103,7 @@ In order to prevent incorrect or unsuitable bookings, and to allow a patient to - End date and time, or duration - Delivery channel (in-person, telephone, video) - Slot type and schedule type (see `Slot.serviceType` and `Schedule.serviceCategory`) -- Service name (where present, see [service ID filtering](appointments_serviceid_filtering.html) for more information) +- Service name (where present, see [service filtering](appointments_serviceid_filtering.html) for more information) - Location name and address - Practitioner role (e.g. General Medical Practitioner, Nurse) - Practitioner name and gender @@ -204,10 +204,10 @@ Provider systems: - **and** which match the search filter parameters of booking organisation (ODS code) and/or organisation type, or are not restricted for booking by ODS code and/or organisation type - **and** reference a `Schedule` with a `actor` of type `HealthcareService`, **where**: - the consumer has sent a `service.identifier` search parameter in the request - - **and** the service ID filtering [organisation switch is ON](appointments_serviceid_configuration.html#organisation-switch-set-to-on) + - **and** the service filtering [organisation switch is ON](appointments_serviceid_configuration.html#organisation-switch-set-to-on) - **and** a `HealthcareService.identifier` element matches the token passed in the `service` parameter - {% include important.html content="The `service.identifier` and the HealthcareService `_include` parameters do not take effect (i.e. are ignored) if the provider organisation has the service ID filtering [organisation switch set to OFF](appointments_serviceid_configuration.html#organisation-switch-set-to-off)" %} + {% include important.html content="The `service.identifier` and the HealthcareService `_include` parameters do not take effect (i.e. are ignored) if the provider organisation has the service filtering [organisation switch set to OFF](appointments_serviceid_configuration.html#organisation-switch-set-to-off)" %} - `Schedule` resources associated with the returned `Slot` resources @@ -221,9 +221,9 @@ Provider systems: - SHALL populate the `Location` resource according to population requirements for [Read a location](foundations_use_case_read_a_location.html#payload-response-body) - - `HealthcareService` resources associated with the returned `Schedule` resources where requested by the consumer using the `_include:recurse=Schedule:actor:HealthcareService` parameter and where the service ID filtering [organisation switch is ON](appointments_serviceid_configuration.html#organisation-switch-set-to-on) + - `HealthcareService` resources associated with the returned `Schedule` resources where requested by the consumer using the `_include:recurse=Schedule:actor:HealthcareService` parameter and where the service filtering [organisation switch is ON](appointments_serviceid_configuration.html#organisation-switch-set-to-on) - - `HealthcareService` resources and their reference in `Schedule.actor` SHALL NOT be populated when the service ID filtering [organisation switch is OFF](appointments_serviceid_configuration.html#organisation-switch-set-to-off) regardless of the parameters sent by the consumer + - `HealthcareService` resources and their reference in `Schedule.actor` SHALL NOT be populated when the service filtering [organisation switch is OFF](appointments_serviceid_configuration.html#organisation-switch-set-to-off) regardless of the parameters sent by the consumer - SHALL populate the `HealthcareService` resource according to population requirements for [Read a healthcare service](foundations_use_case_read_a_healthcareservice.html#payload-response-body) @@ -248,7 +248,7 @@ Provider systems: - SHALL NOT populate the `specialty` field on `Schedule` or `Slot` -- SHALL indicate the service ID filtering status of the search: +- SHALL indicate the service filtering status of the search: - only when the consumer sends the `service.identifier` parameter in the request - by using the `Bundle.meta.tag` element populating the system and code elements with [GPConnect-ServiceFilteringStatus]((https://fhir.nhs.uk/STU3/CodeSystem/GPConnect-ServiceFilteringStatus-1)) @@ -265,7 +265,7 @@ The provider system: - SHALL return a [RECORD_NOT_FOUND](development_fhir_error_handling_guidance.html#example-resource-not-found) error with the diagnostics element providing detail of the issue when: - the consumer system has populated the `service.identifier` parameter in the request - - *AND* the provider organisation has the [service ID filtering switch set to ON](appointments_serviceid_configuration.html#organisation-switch-set-to-on) + - *AND* the provider organisation has the [service filtering switch set to ON](appointments_serviceid_configuration.html#organisation-switch-set-to-on) - *AND* the DOS service ID in the `service.identifier` parameter value is not contained in the provider organisation's [service list](appointments_serviceid_configuration.html#service-list) Refer to [Error handling guidance](development_fhir_error_handling_guidance.html) for details of error codes. @@ -296,7 +296,7 @@ The example response includes two Slot resources matching the search criteria, a Because the consumer has not sent the service.identifier parameter, the response has not been filtered by service - schedules linked to any service, or not linked to a service at all, could be returned. -In this example the schedule matching the search criteria has been linked to a service by the provider organisation (and they have switched on the service ID filtering feature) so the service has been returned in the Bundle as a HealthcareService resource. Please see the examples further down this page for a response where a HealthcareService resource is not returned. +In this example the schedule matching the search criteria has been linked to a service by the provider organisation (and they have switched on the service filtering feature) so the service has been returned in the Bundle as a HealthcareService resource. Please see the examples further down this page for a response where a HealthcareService resource is not returned. ```json {% include appointments/search-for-free-slots-response-payload-1.json %} @@ -322,7 +322,7 @@ The example below shows a typical search for free slots request from a consumer The example response includes two Slot resources matching the search criteria, and associated Schedule, Location, Practitioner and Organization resources. -The consumer has searched with a service ID from DOS, however in this example the provider organisation has not enabled [service ID filtering](appointments_serviceid_filtering.html) and has therefore ignored the service.identifier parameter sent in the request. Because the consumer sent the service.identifier parameter in the request, the `Bundle.meta.tag` element is populated to indicate whether the parameter was applied when filtering the returned slots. +The consumer has searched with a service ID from DOS, however in this example the provider organisation has not enabled [service filtering](appointments_serviceid_filtering.html) and has therefore ignored the service.identifier parameter sent in the request. Because the consumer sent the service.identifier parameter in the request, the `Bundle.meta.tag` element is populated to indicate whether the parameter was applied when filtering the returned slots. ```json {% include appointments/search-for-free-slots-response-payload-2.json %} @@ -348,7 +348,7 @@ The example below shows a typical search for free slots request: The example response includes two Slot resources matching the search criteria, and associated Schedule and Organization resources. -In this example the provider organisation has not enabled [service ID filtering](appointments_serviceid_filtering.html). This can be seen in the example response below as the Schedule resource is not linked to a HealthcareService resource, and there are no HealthcareService resources in the response Bundle. Please see the example above for a response where a HealthcareService resource is returned. +In this example the provider organisation has not enabled [service filtering](appointments_serviceid_filtering.html). This can be seen in the example response below as the Schedule resource is not linked to a HealthcareService resource, and there are no HealthcareService resources in the response Bundle. Please see the example above for a response where a HealthcareService resource is returned. This example also shows the absence of a Practitioner resource. This may happen where a provider organisation has not yet assigned a named practitioner to an appointment schedule.