Merge pull request #2 from HealthengineAU/INIT-1530

INIT-1530 Snapshot syncing and handling incoming requests documentation improvements

README.md

@@ -11,6 +11,6 @@ Our [API definition](openapi.yaml) is formatted in OpenAPI v3 and can be viewed
 
 Following your initial review of our API definition, we strongly recommend referring to our [quick start guide](docs/quick-start-guide.md) . This guide outlines the necessary steps to establish a functional integration and the subsequent procedures for going live once the development phase is concluded.
 
-Additionally, the [suggested testing document](docs/suggested-testing.md) outlines common and edge use cases that your integration should be designed to accommodate throughout the development process.
+Additionally, the [suggested testing document](docs/suggested-testing.md) outlines common and edge use cases that your integration should be designed to accommodate throughout the development process. Failing to provide solutions to these tests could result in your integration not being approved for deployment.
 
 If have any questions related to this documentation, please reach out to [email protected]

docs/quick-start-guide.md

@@ -35,10 +35,10 @@ All interactions using the API key are conducted over HTTPS for security.
 To gain access to a practice's Healthengine profile and data, the practice administrator must grant consent.
 
 This can be accomplished by the practice administrator following these steps:
-1. Contacting the Healthengine support team via phone at 1300 377 639 or email at [email protected] to enable access to the PMS API  
-2. Visiting the Healthengine API Consumer Consent page within the [Healthengine Practice Admin](https://healthengine.com.au/appointment/admin) portal  
-3. Clicking the 'Grant new consent' button and selecting your API consumer as the integration vendor  
-4. Retrieving the supplied practice ID and practice key on consent grant success  
+1. Contacting the Healthengine support team via phone at 1300 377 639 or email at [email protected] to enable access to the PMS API
+2. Visiting the Healthengine API Consumer Consent page within the [Healthengine Practice Admin](https://healthengine.com.au/appointment/admin) portal
+3. Clicking the 'Grant new consent' button and selecting your API consumer as the integration vendor
+4. Retrieving the supplied practice ID and practice key on consent grant success
 
 ![Granting consent via the practice admin integration consent page](../assets/quick-start-guide/grant-consent.png)
 
@@ -50,7 +50,11 @@ Once consent is granted, you will need to provide a way for the practice to prov
 
 Once a practice has granted you consent and has provided you their practice ID and practice key, some initial configuration must be supplied before attempting to sync available appointments and bookings.
 
-This configuration data should be transmitted both when a new Healthengine practice ID is associated with a PMS account or location and whenever there are updates to the corresponding data within the PMS.
+This configuration data should be transmitted when:
+1. a Healthengine practice ID is associated with a PMS account or location
+2. the integration was disabled in your software via configuration and has now been enabled
+3. a user opts to resync their practice configuration via a dedicated action in your software
+3. whenever there are updates to the corresponding data within your software while the integration is enabled
 
 ### The liveness contract
 
@@ -178,7 +182,13 @@ Availability can be conveyed as time ranges, such as 9 am to 5 pm, until they ar
 
 If your software supports it, you have the ability to transmit availability that is exclusive to certain appointment types for a given practitioner using the 'pmsAppointmentTypeIds' field. This feature allows you to accommodate scenarios like Dr. Do Good only conducting patient visits on Tuesdays.
 
-It is imperative to update and send a new snapshot of this availability whenever there are changes, or when it is requested through the requests endpoint.
+It is important to send availability snapshots as often as possible to avoid availability in Healthengine becoming stale and causing booking failures.
+
+We strongly recommend you send availability in the following situations:
+1. when resource availability has been changed in your software
+2. when the integration is disabled via configuration in your software and is enabled again
+3. when requested by us via the availability snapshot request endpoint
+4. periodically **at least** once a day to avoid changes being missed in situations 1-3
 
 An example availability snapshot POST follows.
 
@@ -260,10 +270,13 @@ It is crucial to promptly address these types of requests. Failure to do so with
 
 We provide two notification methods for incoming requests that have been generated: webhook subscriptions and polling.
 
-### Webhook subscriptions
+### Webhook subscription method
 
 To help you determine when to call the request endpoints, you can set up webhook subscriptions to notify you about the occurring events.
 
+> :warning: **PLEASE NOTE**  
+While this method is useful in reducing the number of calls to maintain a healthy integration, you **must** also implement the polling method and poll the requests endpoint at least once an hour to respond to any missed requests due to transient network issues and the integration being disabled in your software.
+
 An example subscription POST follows.
 
 ```
@@ -385,9 +398,13 @@ This will give you a result like so:
 
 This feature enables you to identify instances where the webhook has encountered multiple failures. In this particular scenario, it attempted to execute the task three times, and the log provided pertains to the last failed attempt.
 
-### Polling
+### Polling method
+
+This method involves periodically polling our 'requests' endpoint that will then tell you which other request endpoints require resolving.
+
+If you are not also implementing the webhook subscription method, this endpoint should be called at least once every five seconds to ensure that requests are dealt with in a timely fashion.
 
-The alternative to primarily resolving requests via webhook payloads is to periodically poll our requests convenience endpoint that will then tell you which other request endpoints require resolving.
+If you are implementing the webhook subscription method, you should still poll this endpoint at least once an hour. This practice helps in identifying any missed requests caused by transient network issues or the integration being temporarily disabled within your software.
 
 An example requests GET follows.
 

docs/suggested-testing.md

@@ -6,6 +6,8 @@ After gaining access to our test environment, a user of the Healthengine PMS API
 
 To ensure the seamless functioning of this integration, we strongly advise conducting the following minimal set of tests prior to going live.
 
+Neglecting to satisfy these tests could potentially lead to your integration not being approved during the go-live process.
+
 ---
 
 ## Linking a PMS account to one or more Healthengine practices
@@ -18,7 +20,7 @@ Once a practice using Healthengine has granted consent for you to access their d
 **Then** an effort to transmit practice configuration to Healthengine must be initiated
 
 **Scenario: Practice provides Healthengine practice ID and practice key without consent or for a revoked consent**  
-**Given**  a PMS account in which a practice ID and practice key have been provided which do not belong to a non-revoked consent for your consumer
+**Given**  a PMS account in which a practice ID and practice key have been provided which do not belong to a non-revoked consent for your consumer  
 **When** a 403 Unauthorized response is received upon attempting to transmit practice configuration  
 **Then** the PMS user must be informed and guided to establish consent within Healthengine
 
@@ -34,7 +36,7 @@ Once a practice using Healthengine has granted consent for you to access their d
 
 ---
 
-## PMS account/location configuration synchronisation
+## Initial configuration synchronisation
 
 Upon the establishment of a PMS account, or a PMS location in a multi-location-per-account setup, the following configuration must be provided before initiating the synchronisation of resource availability and bookings:
 
@@ -64,17 +66,57 @@ It is important to note that for snapshot endpoints, the absence of an item in t
 **When** an existing PMS appointment type is altered, removed, or a new PMS appointment type is introduced  
 **Then** an updated PMS appointment type snapshot should be promptly communicated to Healthengine
 
+**Scenario: Manual configuration resync action by PMS user**  
+**Given** an integrated PMS account or location  
+**When** a PMS user opts to manually resync the PMS account or location configuration to Healthengine  
+**Then** there should be a solution available to them to do so
+
+**Scenario: Sending configuration after being temporarily disabled**  
+**Given** an integrated PMS account or location in a temporarily disabled state due to configuration in your software  
+**When** a PMS user re-enables this integration  
+**Then** configuration should be sent to Healthengine
+
 ---
 
-## Handling PMS resource edge cases
+## Initial configuration synchronisation edge cases
 
-Please consider these additional edge cases related to PMS resources when refining your integration logic.
+Please consider these additional edge cases related to initial configuration when designing your integration logic.
 
 **Scenario: Managing PMS practitioners with multiple specialties**  
 **Given** the potential for a single practitioner to possess multiple specialties within a PMS  
 **When** sending a PMS resource snapshot to Healthengine  
 **Then** distinct PMS resources should be sent for each practitioner/specialty combination
 
+**Scenario: Outstanding requests during initial configuration synchronisation**  
+**Given** the presence of a PMS account or location  
+**When** a new Healthengine practice ID and practice key are supplied  
+**Then** the 'requests' endpoint should be checked for any outstanding requests from a practice's previous integration (e.g. booking attempt)
+
+---
+
+## Syncing resource availability
+
+Availability snapshots are expected to be sent to us without an incoming request for each PMS resource multiplied by the number of days that you are syncing into the future.
+
+We will only request an availability snapshot from you if we have attempted to insert a booking and the request has been rejected, indicating that we might have stale availability for the resource and date. 
+
+Resource availability should be sent to us whenever the availability has been changed in your software for a resource and date. Some examples include:
+- Changing a resource's available hours
+- Creating a non-Healthengine booking for the resource
+- The integration being re-enabled after being disabled via configuration in your software
+
+There should also be a sync periodically to avoid any missed updates and a manual resync option available to PMS users.
+
+**Scenario: Manual availability resync action by PMS user**  
+**Given** an integrated PMS account or location  
+**When** a PMS user opts to manually resync availability to Healthengine  
+**Then** there should be a solution available to them to sync availability for all resources for the future sync period
+
+**Scenario: Sending availability after being temporarily disabled**  
+**Given** an integrated PMS account or location in a temporarily disabled state due to configuration in your software   
+**When** a PMS user re-enables this integration  
+**Then** availability for all resources should be sent to Healthengine
+
 ---
 
 ## Handling incoming requests
@@ -93,6 +135,11 @@ Certain types of requests hold a higher priority in terms of integration health.
 **When** an incoming booking, bookingUpdate or availability request is created  
 **Then** the integration should resolve this request within ten minutes
 
+**Scenario: Checking for outstanding requests after being temporarily disabled**  
+**Given** an integrated PMS account or location in a temporarily disabled state due to configuration in your software   
+**When** a PMS user re-enables this integration  
+**Then** the 'requests' endpoint should be checked for any outstanding requests
+
 ---
 
 ## Handling incoming requests via webhook subscriptions
@@ -114,7 +161,12 @@ We strongly advise that you continue to periodically check the requests endpoint
 **Scenario: Handling missed webhook payloads**  
 **Given** that a webhook subscription has been established for a specific request type  
 **When** a webhook payload is missed because the maximum number of unacknowledged requests is reached  
-**Then** regular polling of the requests endpoint should be employed to capture any missed requests
+**Then** polling the requests endpoint at least once an hour should be done to capture any missed requests
+
+**Scenario: Checking for outstanding requests after being temporarily disabled**  
+**Given** an integrated PMS account or location in a temporarily disabled state due to configuration in your software   
+**When** a PMS user re-enables this integration  
+**Then** the 'requests' endpoint should be checked for any outstanding requests
 
 ---