From b70c1c432a35da7ec209658778fbfaea7c2f1b71 Mon Sep 17 00:00:00 2001 From: ORybak5 <12736698+ORybak5@users.noreply.github.com> Date: Mon, 13 Apr 2026 14:23:45 +0100 Subject: [PATCH] documentation update --- .github/pull_request_template.md | 18 ++++++------ README.md | 47 ++++++++++++++++---------------- release/DOCKERHUB.md | 45 ++++++++++++++++-------------- 3 files changed, 57 insertions(+), 53 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b750437f..f00eef69 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,25 +1,25 @@ ## What -Please include a summary of the changes and the related issue +Please include a summary of the changes and any related issue(s). ## Why -Please include details of the reasoning for these changes +Please include details of the reasoning for these changes. -## Type of change +## Type of Change -Please delete options that are not relevant. +Please check the option(s) that apply. -- [ ] Bug fix (non-breaking change which fixes an issue) -- [ ] New feature (non-breaking change which adds functionality) -- [ ] Internal change (non-breaking change with no effect on the functionality affecting end users) +- [ ] Bug fix (non-breaking change that fixes an issue) +- [ ] New feature (non-breaking change that adds functionality) +- [ ] Internal change (non-breaking change with no effect on functionality affecting end users) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) -## Checklist: +## Checklist - [ ] I have performed a self-review of my code - [ ] I have made corresponding changes to the documentation - [ ] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [ ] New and existing unit tests pass locally with my changes -- [ ] I have updated the [Changelog](../CHANGELOG.MD) with details of my change in the UNRELEASED section if this change will affect end users \ No newline at end of file +- [ ] I have updated the [Changelog](../CHANGELOG.MD) with details of my change in the UNRELEASED section, if this change will affect end users diff --git a/README.md b/README.md index 925970f6..003c83e9 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ The GP Connect Consumer Adaptor allows a GP Connect Consumer to connect to a GP Connect Producer over Spine. The adaptor proxies GP Connect API requests to the correct GP Connect producer. It performs the - [Spine integration required to consume GP Connect capabilities](https://nhsconnect.github.io/FHIR-SpineCore/integration_example_gpconnect.html#spine-integration-required-to-consume-gp-connect-capabilities). +[Spine integration required to consume GP Connect capabilities](https://nhsconnect.github.io/FHIR-SpineCore/integration_example_gpconnect.html#spine-integration-required-to-consume-gp-connect-capabilities). ## Adaptor API @@ -19,7 +19,7 @@ We only support the two endpoints required for the GP2GP use case: ### Service Root URL -We follow the [Service Root URL](https://gpc-structured-1-5-0.netlify.app/development_general_api_guidance.html#service-root-url-versioning) scheme defined by GP Connect. +We follow the [Service Root URL](https://gpc-structured-1-6-0.netlify.app/development_general_api_guidance.html#service-root-url-versioning) scheme defined by GP Connect. Example (Retrieve a patient's structured record, ODS Code GP0001): `POST https://gpcadaptor.com/GP0001/STU3/1/gpconnect/fhir/Patient/$gpc.migratestructuredrecord` @@ -35,7 +35,7 @@ The adaptor does not perform a PDS lookup/trace. You must perform the PDS lookup ## Configuration The adaptor reads its configuration from environment variables. The following sections describe the environment variables - used to configure the adaptor. +used to configure the adaptor. Variables without a default value and not marked optional, *MUST* be defined for the adaptor to run. @@ -46,14 +46,14 @@ Variables without a default value and not marked optional, *MUST* be defined for | GPC_CONSUMER_SERVER_PORT | 8090 | The port on which the GPC Consumer Adaptor will run. | GPC_CONSUMER_ROOT_LOGGING_LEVEL | WARN | The logging level applied to the entire application (including third-party dependencies). | GPC_CONSUMER_LOGGING_LEVEL | INFO | The logging level applied to GPC Consumer Adaptor components. -| GPC_CONSUMER_LOGGING_FORMAT | (*) | Defines how to format log events on stdout +| GPC_CONSUMER_LOGGING_FORMAT | (*) | Defines how to format log events on stdout. Logging level is one of: DEBUG, INFO, WARN, ERROR The level DEBUG **MUST NOT** be used when handling live patient data. -(*) GP2GP API uses logback (http://logback.qos.ch/). The built-in [logback.xml](service/src/main/resources/logback.xml) -defines the default log format. This value can be overridden using the `GP2GP_LOGGING_FORMAT` environment variable. +(*) GPC Consumer uses logback (http://logback.qos.ch/). The built-in [logback.xml](service/src/main/resources/logback.xml) +defines the default log format. This value can be overridden using the `GPC_CONSUMER_LOGGING_FORMAT` environment variable. You can provide an external `logback.xml` file using the `-Dlogback.configurationFile` JVM parameter. ### GP Connect API Configuration Options @@ -71,7 +71,7 @@ The adaptor uses the GP Connect API to fetch patient records and documents. ### SDS API Configuration Options You need an [API-M API Key](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-api-key-authentication) - for the [SDS FHIR API](https://digital.nhs.uk/developer/api-catalogue/spine-directory-service-fhir) +for the [SDS FHIR API](https://digital.nhs.uk/developer/api-catalogue/spine-directory-service-fhir) to use the adaptor in the integration and production environments. | Environment Variable | Default | Description @@ -96,7 +96,7 @@ Service URL scheme. | GPC_CONSUMER_SEARCH_DOCUMENTS_PATH | /*/STU3/1/gpconnect/documents/fhir/Patient/** | Search for a Patient's Document path. | GPC_CONSUMER_GPC_MIGRATE_STRUCTURED_PATH | /*/STU3/1/gpconnect/fhir/Patient/$gpc.migratestructuredrecord | Migrate structured record path. -## How to run service: +## How to Run the Service The following steps use Docker to provide mocks of adaptor dependencies and infrastructure for local testing and development. These containers are not suitable for use in a deployed environment. You are responsible for providing @@ -117,29 +117,29 @@ For local environment to run against mocks: ./start-local-environment-mocks.sh ``` -For local environment to run against gp demonstrator 1.6.0 +For local environment to run against GP Demonstrator 1.6.0: ```bash ./start-local-environment-public.sh ``` You can also run the docker-compose commands directly. -## How to run tests +## How to Run Tests **Warning**: Gradle uses a [Build Cache](https://docs.gradle.org/current/userguide/build_cache.html) to re-use compile and test outputs for faster builds. To re-run passing tests without making any code changes you must first run `./gradlew clean` to clear the build cache. Otherwise, gradle uses the cached outputs from a previous test execution to pass the build. -You must run all gradle commands from the `service/` directory. +You must run all Gradle commands from the `service/` directory. -### How to run unit tests: +### How to Run Unit Tests ```shell script ./gradlew test ``` -### How to run integration tests: +### How to Run Integration Tests Without special configuration, you must build the gpcc-mocks container using docker-compose before running integration tests and after making any changes to the mocks project. The JUnit tests use @@ -150,17 +150,17 @@ cd docker/ docker-compose build gpcc-mocks ``` -Then run the integration tests from within the IDE or using gradle +Then run the integration tests from within the IDE or using Gradle: ```shell script ./gradlew integrationTest ``` -It is also possible to run the integration tests without Testcontainers; Setting the `GPC_CONSUMER_SDS_URL` disables +It is also possible to run the integration tests without Testcontainers. Setting the `GPC_CONSUMER_SDS_URL` disables Testcontainers. You must configure the other environment variables also to use the correct services. The integration tests use the same variables as the application. -### How to run all checks: +### How to Run All Checks ```shell script ./gradlew check @@ -188,14 +188,14 @@ YYYY-MM-DD HH:MM:SS.mmm Level={DEBUG/INFO/WARNING/ERROR} Logger={LoggerName} Req ``` - **LoggerName** name of the Java class which emitted the log -- **RequestId** randomly generated identified for each request +- **RequestId** randomly generated identifier for each request - **Ssp-TraceID** value of the Ssp-TraceID header, for distributed tracing - **ThreadName** name of the thread handling the request - **LogMessage** content of the log message The properties RequestId and Ssp-TraceID may only be populated if the log is emitted by application code. These are blank for logs emitted by framework or -third party code. +third-party code. ## Mapping External (adaptor) URLs to internal (NHSD) URLs @@ -213,7 +213,7 @@ https://gpcconsumer.prod.mydomain.com/A12345/STU3/1/gpconnect/structured/fhir/Pa The adaptor then performs an SDS lookup and constructs a new path using the Spine Secure Proxy and the practice's GP Connect Provider's internal URL. -https://proxy.opentest.hscic.gov.uk/https://gpconnect.gpsytemsupplier.internal.nhs.uk/A12345/STU3/1/gpconnect/structured/fhir/Patient/$gpc.getstructuredrecord +https://proxy.opentest.hscic.gov.uk/https://gpconnect.gpsystemsupplier.internal.nhs.uk/A12345/STU3/1/gpconnect/structured/fhir/Patient/$gpc.getstructuredrecord | $GPC_CONSUMER_SSP_URL | [ From SDS Lookup ] | [ Path from original request ] | ``` @@ -250,7 +250,7 @@ the adaptor replaces the GP Connect Provider Hosts (`https://orange.testlab.nhs. ... ``` -with the dns name / port used in the original request. +with the DNS name / port used in the original request. ``` ... @@ -273,11 +273,11 @@ with the dns name / port used in the original request. ## Example Deployment -We release adaptor image on Dockerhub as [nhsdev/nia-gpc-consumer-adaptor][docker-hub-image], +We release the adaptor image on Docker Hub as [nhsdev/nia-gpc-consumer-adaptor][docker-hub-image], with the latest changes documented within the [CHANGELOG.MD](/CHANGELOG.MD). -When performing assurance against a simulated workload involving the transfer of 100MB documents, we -have identified a minimum of 2GB of RAM and 2 vCPUs to the container is required. +When performing assurance against a simulated workload involving the transfer of 100 MB documents, we +have identified that a minimum of 2 GB of RAM and 2 vCPUs allocated to the container is required. We provide [Terraform scripts][exemplar-deployment] to perform an exemplar deployment of the GP2GP adaptor and GP Connect Consumer adaptor into AWS. @@ -286,6 +286,7 @@ and GP Connect Consumer adaptor into AWS. [docker-hub-image]: https://hub.docker.com/r/nhsdev/nia-gpc-consumer-adaptor ## Licensing + This code is dual licensed under the MIT license and the OGL (Open Government License). Any new work added to this repository must conform to the conditions of these licenses. In particular this means that this project may not depend on GPL-licensed or AGPL-licensed libraries, as these would violate the terms of those libraries' licenses. The contents of this repository are protected by Crown Copyright (C). diff --git a/release/DOCKERHUB.md b/release/DOCKERHUB.md index 2e6dc9e9..d28b9727 100644 --- a/release/DOCKERHUB.md +++ b/release/DOCKERHUB.md @@ -1,24 +1,26 @@ -# Quick reference -- Maintained by: NHS Digital -- Where to get help: https://github.com/nhsconnect/integration-adaptor-gpc-consumer -- Where to file issues: https://github.com/nhsconnect/integration-adaptor-gpc-consumer/issues +# Quick Reference -# What is the GPC Consumer? -The GPC Consumer adaptor proxies requests to GP Connect provider endpoints. The adaptor simplifies your GP Connect integration by performing service discovery via Spine Directory Service and routing over Spine Security Proxy. We only support the interactions required for GP2GP over GP Connect and the [GP2GP Adaptor](https://github.com/nhsconnect/integration-adaptor-gp2gp). +- **Maintained by:** NHS Digital +- **Where to get help:** https://github.com/nhsconnect/integration-adaptor-gpc-consumer +- **Where to file issues:** https://github.com/nhsconnect/integration-adaptor-gpc-consumer/issues -# How to use this image +# What is the GPC Consumer Adaptor? -To help you begin using the GPC Consumer we provide shell scripts and Docker Compose configurations. +The GPC Consumer Adaptor proxies requests to GP Connect provider endpoints. The adaptor simplifies your GP Connect integration by performing service discovery via the Spine Directory Service and routing over the Spine Secure Proxy. We only support the interactions required for GP2GP over GP Connect and the [GP2GP Adaptor](https://github.com/nhsconnect/integration-adaptor-gp2gp). -## Clone the repository +# How to Use This Image + +To help you begin using the GPC Consumer Adaptor, we provide shell scripts and Docker Compose configurations. + +## Clone the Repository ```bash git clone https://github.com/nhsconnect/integration-adaptor-gpc-consumer.git ``` -## Pull the latest changes and checkout the release tag +## Pull the Latest Changes and Checkout the Release Tag -Every tagged container on Docker hub has a corresponding tag in the git repository. Checkout the tag of the release +Every tagged container on Docker Hub has a corresponding tag in the git repository. Checkout the tag of the release you are testing to ensure compatibility with configurations and scripts. ```bash @@ -26,39 +28,39 @@ git pull git checkout 0.3.3 ``` -## Find the docker directory +## Find the Docker Directory ```bash cd integration-adaptor-gpc-consumer/docker ``` -## Configure the application +## Configure the Application -[Copy a configuration example](https://github.com/nhsconnect/integration-adaptor-gpc-consumer/blob/0.0.5/README.md#copy-a-configuration-example) - to `docker/vars.sh` and make any required changes to the `vars.sh` file. +[Copy a configuration example](https://github.com/nhsconnect/integration-adaptor-gpc-consumer#copy-a-configuration-example) +to `docker/vars.sh` and make any required changes to the `vars.sh` file. -## Find the release directory +## Find the Release Directory ```bash cd ../release ``` -## Start the adaptor +## Start the Adaptor -The script pulls the released GPC Consumer adaptor container image from Docker Hub. It builds containers for its dependencies +The script pulls the released GPC Consumer Adaptor container image from Docker Hub. It builds containers for its dependencies from the Dockerfiles in the repository. ```bash ./run.sh ``` -## Monitor the logs +## Monitor the Logs ```bash ./logs.sh ``` -## Run the tests +## Run the Tests We provide a shell script to help you determine if the adaptor is running. @@ -78,7 +80,8 @@ Modify the values for the environment "Public GP Connect Reference Implementatio * providerURL_1_5_x_structured: `http://localhost:8090/B82617/STU3/1/gpconnect/structured/fhir` * providerURL_1_5_x_documents: `http://localhost:8090/B82617/STU3/1/gpconnect/documents/fhir` -## Stopping the adaptor +## Stopping the Adaptor + ```bash cd ../docker docker-compose down