From 190cf0ba1bad5d077d662bc370d008a7efe0a230 Mon Sep 17 00:00:00 2001 From: BenHession Date: Mon, 23 Oct 2023 12:37:42 +0100 Subject: [PATCH 1/4] Add Timeout section to OPERATING.md. --- OPERATING.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/OPERATING.md b/OPERATING.md index fc9024ae4..1dd2aab32 100644 --- a/OPERATING.md +++ b/OPERATING.md @@ -20,6 +20,43 @@ yyyy-mm-dd HH:mm:ss.SSS Level=DEBUG Logger=u.n.a.p.t.s.BundleMapperService Conve ## Timeout functionality +The Adaptor conforms to the GP2GP large messaging specification (NPFIT-PC-BLOD-0170.03 v1.1) +by timing out in-progress transfers (section 2.3.6). This ensures transfers are ended gracefully +in the scenario a GP2GP message has not been received. + +The timeout +datetime is calculated using the following formula and the *Persist Duration* (the minium time a message is persisted by spine) of the expected GP2GP messages. + +```text + +Timeout [secs] = (A x persistDuration contract property of EHR Response +[secs]) + (B x Number of COPC Common Point to Point EHR messages x +persistDuration contract property of COPC Common Point to Point messages +[secs]) + +``` +The formula includes adjustable weightings (A and B) to offset potential transmission delays. + +From the documentation: + +> A & B are weighting factors associated with general message transmission delays and volume based +throughput times to allow adjustment if required .... + +The *Persist Duration* of each message is unique to the sending organisation and is obtained from the Spine Directory Service (SDS) FHIR API. Responses for an organisations message type are cached by default. + +The adaptor checks for transfers periodically, the default is every six hours. However, this is configurable via the environment variables. + +The following environment should be used to configure the timeout: + +| Environment variable | Required | Description | Default value | +|-------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| +| SDS_BASE_URL | | The SDS FHIR API Base URL (default is production) | `https://api.service.nhs.uk/spine-directory/FHIR/R4` | +| SDS_API_KEY | Yes | Your SDS FHIR API Key | | +| TIMEOUT_CRON_TIME | | The frequency of the timeout check specified as a Cron expression (default is every six hours). format = ` ` | `0 0 */6 * * * ` | +| TIMEOUT_SDS_POLL_FREQUENCY | | The frequency the persist duration cache is updated (default 3) i.e. 1 = send request to SDS everytime, 3 = send request to SDS on the third call | `3` | +| TIMEOUT_EHR_EXTRACT_WEIGHTING | | The weighting factor A (as described above) | `1` | +| TIMEOUT_COPC_WEIGHTING | | The weighting factor B (as described above) | `1` | + ## Database requirements * The adaptor requires a [PostgreSQL] database From e328ee81d10bb06e3abd9981728395e40abd190e Mon Sep 17 00:00:00 2001 From: BenHession Date: Mon, 23 Oct 2023 12:54:03 +0100 Subject: [PATCH 2/4] Change format of environment variables to match the current document. --- OPERATING.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/OPERATING.md b/OPERATING.md index 1dd2aab32..804cf07fa 100644 --- a/OPERATING.md +++ b/OPERATING.md @@ -44,18 +44,20 @@ throughput times to allow adjustment if required .... The *Persist Duration* of each message is unique to the sending organisation and is obtained from the Spine Directory Service (SDS) FHIR API. Responses for an organisations message type are cached by default. -The adaptor checks for transfers periodically, the default is every six hours. However, this is configurable via the environment variables. - -The following environment should be used to configure the timeout: - -| Environment variable | Required | Description | Default value | -|-------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------| -| SDS_BASE_URL | | The SDS FHIR API Base URL (default is production) | `https://api.service.nhs.uk/spine-directory/FHIR/R4` | -| SDS_API_KEY | Yes | Your SDS FHIR API Key | | -| TIMEOUT_CRON_TIME | | The frequency of the timeout check specified as a Cron expression (default is every six hours). format = ` ` | `0 0 */6 * * * ` | -| TIMEOUT_SDS_POLL_FREQUENCY | | The frequency the persist duration cache is updated (default 3) i.e. 1 = send request to SDS everytime, 3 = send request to SDS on the third call | `3` | -| TIMEOUT_EHR_EXTRACT_WEIGHTING | | The weighting factor A (as described above) | `1` | -| TIMEOUT_COPC_WEIGHTING | | The weighting factor B (as described above) | `1` | +The adaptor checks for transfers periodically, the default is every six hours. However, this is configurable via the environment variables. + +Required environment variables: + +- `SDS_API_KEY`: Your SDS FHIR API Key + +Optional environment variables: + +- `SDS_BASE_URL`: The SDS FHIR API Base URL (default is production) - default = `https://api.service.nhs.uk/spine-directory/FHIR/R4` +- `TIMEOUT_CRON_TIME`: The frequency of the timeout check specified as a Cron expression (default is every six hours). +format = ` ` - default = `0 0 */6 * * * ` +- `TIMEOUT_SDS_POLL_FREQUENCY`: The frequency the persist duration cache is updated (default 3) i.e. 1 = send request to SDS everytime, 3 = send request to SDS on the third call - default = `3` +- `TIMEOUT_EHR_EXTRACT_WEIGHTING`: The weighting factor A (as described above) - default = `1` +- `TIMEOUT_COPC_WEIGHTING`: The weighting factor B (as described above) - default = `1` ## Database requirements From 31b3f707b63bff374b57a1b7e67c56b43f4561eb Mon Sep 17 00:00:00 2001 From: Ben Hession <7346923+benhession@users.noreply.github.com> Date: Mon, 23 Oct 2023 16:57:44 +0100 Subject: [PATCH 3/4] refactor formula for readability Co-authored-by: Adrian Clay --- OPERATING.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/OPERATING.md b/OPERATING.md index 804cf07fa..6f68889dd 100644 --- a/OPERATING.md +++ b/OPERATING.md @@ -28,13 +28,9 @@ The timeout datetime is calculated using the following formula and the *Persist Duration* (the minium time a message is persisted by spine) of the expected GP2GP messages. ```text - -Timeout [secs] = (A x persistDuration contract property of EHR Response -[secs]) + (B x Number of COPC Common Point to Point EHR messages x -persistDuration contract property of COPC Common Point to Point messages -[secs]) - -``` +Timeout [secs] = (A x persistDuration contract property of EHR Response [secs]) + + (B x Number of COPC Common Point to Point EHR messages + x persistDuration contract property of COPC Common Point to Point messages [secs]) The formula includes adjustable weightings (A and B) to offset potential transmission delays. From the documentation: From 481dc69e63369edeb72e8d739150ba95a40dd179 Mon Sep 17 00:00:00 2001 From: BenHession Date: Mon, 23 Oct 2023 17:14:56 +0100 Subject: [PATCH 4/4] Update the timeout section of OPERATING.md. --- OPERATING.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/OPERATING.md b/OPERATING.md index 6f68889dd..a696a4401 100644 --- a/OPERATING.md +++ b/OPERATING.md @@ -20,17 +20,17 @@ yyyy-mm-dd HH:mm:ss.SSS Level=DEBUG Logger=u.n.a.p.t.s.BundleMapperService Conve ## Timeout functionality -The Adaptor conforms to the GP2GP large messaging specification (NPFIT-PC-BLOD-0170.03 v1.1) -by timing out in-progress transfers (section 2.3.6). This ensures transfers are ended gracefully -in the scenario a GP2GP message has not been received. +The Adaptor conforms to the GP2GP specification by timing out in-progress transfers. This ensures transfers are ended +gracefully in the scenario a GP2GP message has not been received. -The timeout -datetime is calculated using the following formula and the *Persist Duration* (the minium time a message is persisted by spine) of the expected GP2GP messages. +The timeout datetime is calculated using the following formula: ```text Timeout [secs] = (A x persistDuration contract property of EHR Response [secs]) + (B x Number of COPC Common Point to Point EHR messages x persistDuration contract property of COPC Common Point to Point messages [secs]) +``` + The formula includes adjustable weightings (A and B) to offset potential transmission delays. From the documentation: @@ -38,9 +38,10 @@ From the documentation: > A & B are weighting factors associated with general message transmission delays and volume based throughput times to allow adjustment if required .... -The *Persist Duration* of each message is unique to the sending organisation and is obtained from the Spine Directory Service (SDS) FHIR API. Responses for an organisations message type are cached by default. +The *Persist Duration* of each message is unique to the sending organisation and is obtained from the [Spine Directory Service (SDS) FHIR API](https://digital.nhs.uk/developer/api-catalogue/spine-directory-service-fhir). Responses for an organisation's message type are cached by default, the frequency the cache is +updated is configurable via the environment variable `TIMEOUT_SDS_POLL_FREQUENCY`. -The adaptor checks for transfers periodically, the default is every six hours. However, this is configurable via the environment variables. +The adaptor checks incomplete transfers periodically, at a default frequency of every six hours. However, this is configurable via the environment variable `TIMEOUT_CRON_TIME`. Required environment variables: