{"id":23421096,"url":"https://github.com/nhsdigital/integration-adaptor-gpc-consumer","last_synced_at":"2025-04-09T09:34:38.114Z","repository":{"id":40486428,"uuid":"343388044","full_name":"NHSDigital/integration-adaptor-gpc-consumer","owner":"NHSDigital","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-31T08:19:52.000Z","size":517,"stargazers_count":2,"open_issues_count":2,"forks_count":2,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-03-31T09:26:10.263Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Mustache","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NHSDigital.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.MD","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-01T11:13:08.000Z","updated_at":"2025-03-31T08:19:55.000Z","dependencies_parsed_at":"2023-12-21T16:11:10.372Z","dependency_job_id":"df4860c2-2623-43b9-a95b-9f1d148310b4","html_url":"https://github.com/NHSDigital/integration-adaptor-gpc-consumer","commit_stats":null,"previous_names":["nhsdigital/integration-adaptor-gpc-consumer"],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fintegration-adaptor-gpc-consumer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fintegration-adaptor-gpc-consumer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fintegration-adaptor-gpc-consumer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fintegration-adaptor-gpc-consumer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NHSDigital","download_url":"https://codeload.github.com/NHSDigital/integration-adaptor-gpc-consumer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248013006,"owners_count":21033285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-23T02:14:01.739Z","updated_at":"2025-04-09T09:34:38.086Z","avatar_url":"https://github.com/NHSDigital.png","language":"Mustache","funding_links":[],"categories":[],"sub_categories":[],"readme":"# National Integration Adaptor - GP Connect Consumer\n\n## Introduction\n\nThe GP Connect Consumer Adaptor allows a GP Connect Consumer to connect to a GP Connect Producer over Spine.\nThe adaptor proxies GP Connect API requests to the correct GP Connect producer. It performs the\n [Spine integration required to consume GP Connect capabilities](https://developer.nhs.uk/apis/gpconnect-1-6-0/integration_illustrated.html#spine-integration-required-to-consume-gp-connect-capabilities).\n\n## Adaptor API\n\nThe GP Connect Consumer Adaptor adheres to the GP Connect API specifications.\n\nWe only support the two endpoints required for the GP2GP use case:\n\n* Capability: [Migrate Structured Record](https://gpc-structured-1-5-0.netlify.app/accessrecord_structured.html) \n  * Endpoint: [Migrate a patient's structured record](https://developer.nhs.uk/apis/gpconnect-1-6-0/accessrecord_structured_development_migrate_patient_record.html)\n* Capability: [Access Document](https://gpc-structured-1-5-0.netlify.app/access_documents.html)\n  * Endpoint: [Retrieve a document](https://gpc-structured-1-5-0.netlify.app/access_documents_development_retrieve_patient_documents.html)\n\n### Service Root URL\n\nWe 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.\n\nExample (Retrieve a patient's structured record, ODS Code GP0001): `POST https://gpcadaptor.com/GP0001/STU3/1/gpconnect/fhir/Patient/$gpc.migratestructuredrecord`\n\n### Known Limitations\n\nThe adaptor does not perform a PDS lookup/trace. You must perform the PDS lookup before making a request to the adaptor.\n\n## Requirements\n\n* JDK 21\n* Docker\n\n## Configuration\n\nThe adaptor reads its configuration from environment variables. The following sections describe the environment variables\n used to configure the adaptor.\n\nVariables without a default value and not marked optional, *MUST* be defined for the adaptor to run.\n\n### General Configuration Options\n\n| Environment Variable                        | Default                   | Description\n| --------------------------------------------|---------------------------|-------------\n| GPC_CONSUMER_SERVER_PORT                    | 8090                      | The port on which the GPC Consumer Adaptor will run.\n| GPC_CONSUMER_ROOT_LOGGING_LEVEL             | WARN                      | The logging level applied to the entire application (including third-party dependencies).\n| GPC_CONSUMER_LOGGING_LEVEL                  | INFO                      | The logging level applied to GPC Consumer Adaptor components.\n| GPC_CONSUMER_LOGGING_FORMAT                 | (*)                       | Defines how to format log events on stdout\n\nLogging level is one of: DEBUG, INFO, WARN, ERROR\n\nThe level DEBUG **MUST NOT** be used when handling live patient data.\n\n(*) GP2GP API uses logback (http://logback.qos.ch/). The built-in [logback.xml](service/src/main/resources/logback.xml) \ndefines the default log format. This value can be overridden using the `GP2GP_LOGGING_FORMAT` environment variable.\nYou can provide an external `logback.xml` file using the `-Dlogback.configurationFile` JVM parameter.\n\n### GP Connect API Configuration Options\n\nThe adaptor uses the GP Connect API to fetch patient records and documents.\n\n| Environment Variable                        | Default | Description\n| --------------------------------------------|---------|-------------\n| GPC_CONSUMER_SPINE_CLIENT_CERT              |         | The content of the PEM-formatted client endpoint certificate\n| GPC_CONSUMER_SPINE_CLIENT_KEY               |         | The content of the PEM-formatted client private key\n| GPC_CONSUMER_SPINE_ROOT_CA_CERT             |         | The content of the PEM-formatted certificate of the issuing Root CA.\n| GPC_CONSUMER_SPINE_SUB_CA_CERT              |         | The content of the PEM-formatted certificate of the issuing Sub CA.\n| GPC_CONSUMER_SSP_URL                        |         | The URL of Spine Secure Proxy including a trailing slash e.g. https://proxy.opentest.hscic.gov.uk/\n\n### SDS API Configuration Options\n\nYou need an [API-M API Key](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-api-key-authentication)\n for the [SDS FHIR API](https://digital.nhs.uk/developer/api-catalogue/spine-directory-service-fhir) \nto use the adaptor in the integration and production environments.\n\n| Environment Variable    | Default | Description\n| ------------------------|---------|-------------\n| GPC_CONSUMER_SDS_URL    |         | [URL of the SDS FHIR API]\n| GPC_CONSUMER_SDS_APIKEY |         | Secret key used to authenticate with the API\n| GPC_SUPPLIER_ODS_CODE   |         | Supplier ODS code [see GP Connect Docs](https://developer.nhs.uk/apis/gpconnect-1-6-0/integration_spine_directory_service.html#looking-up-a-consumers-own-asid)\n\n[URL of the SDS FHIR API]: https://digital.nhs.uk/developer/api-catalogue/spine-directory-service-fhir#overview--environments-and-testing\n\n### API Configuration Options\n\n**Warning**: We don't recommend overriding these default values. The values are paths of \n[Spring Cloud Gateway](https://spring.io/projects/spring-cloud-gateway) routes. The defaults conform to the GP Connect \nService URL scheme.\n\n| Environment Variable                        | Default                                                              | Description\n| --------------------------------------------|----------------------------------------------------------------------|-------------\n| GPC_CONSUMER_GPC_STRUCTURED_PATH            | /*/STU3/1/gpconnect/structured/fhir/Patient/$gpc.getstructuredrecord | Structured record path.\n| GPC_CONSUMER_GPC_GET_DOCUMENT_PATH          | /*/STU3/1/gpconnect/documents/fhir/Binary/**                         | Get Document record path.\n| GPC_CONSUMER_GPC_GET_PATIENT_PATH\t          | /*/STU3/1/gpconnect/documents/fhir/Patient                           | Patient record path.\n| GPC_CONSUMER_SEARCH_DOCUMENTS_PATH          | /*/STU3/1/gpconnect/documents/fhir/Patient/**                        | Search for a Patient's Document path.\n| GPC_CONSUMER_GPC_MIGRATE_STRUCTURED_PATH    | /*/STU3/1/gpconnect/fhir/Patient/$gpc.migratestructuredrecord        | Migrate structured record path.\n\n## How to run service:\n\nThe following steps use Docker to provide mocks of adaptor dependencies and infrastructure for local testing and \ndevelopment. These containers are not suitable for use in a deployed environment. You are responsible for providing \nadequate infrastructure and connections to external APIs. \n\n### Copy a configuration example\n\nWe provide several example configurations:\n\n* `vars.public.sh` runs the adaptor with the [GP Connect public demonstrator](Docker image - https://developer.nhs.uk/apis/gpconnect-1-6-0/overview_release_notes_1_6_0.html) and the [SDS FHIR API sandbox](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing)\n\n```bash\ncd docker/\ncp vars.opentest.sh vars.sh\n```\n\nEdit `vars.sh` to add any missing values e.g. Spine certificates.\n\n### Using the helper script for Docker Compose\n\nFor local environment to run against mocks:\n```bash\n./start-local-environment-mocks.sh\n```\n\nFor local environment to run against gp demonstrator 1.6.0\n```bash\n./start-local-environment-public.sh\n```\n\nYou can also run the docker-compose commands directly.\n\n## How to run tests\n\n**Warning**: Gradle uses a [Build Cache](https://docs.gradle.org/current/userguide/build_cache.html) to re-use compile and\ntest outputs for faster builds. To re-run passing tests without making any code changes you must first run \n`./gradlew clean` to clear the build cache. Otherwise, gradle uses the cached outputs from a previous test execution to \npass the build.\n\nYou must run all gradle commands from the `service/` directory.\n\n### How to run unit tests:\n\n```shell script\n./gradlew test\n```\n\n### How to run integration tests:\n\nWithout special configuration, you must build the gpcc-mocks container using docker-compose before running integration \ntests and after making any changes to the mocks project. The JUnit tests use \n[Testcontainers](https://www.testcontainers.org/) to run the mock service.\n\n```shell script\ncd docker/\ndocker-compose build gpcc-mocks\n```\n\nThen run the integration tests from within the IDE or using gradle\n\n```shell script\n./gradlew integrationTest\n```\n\nIt is also possible to run the integration tests without Testcontainers; Setting the `GPC_CONSUMER_SDS_URL` disables\nTestcontainers. You must configure the other environment variables also to use the correct services. The integration\ntests use the same variables as the application.\n\n### How to run all checks:\n\n```shell script\n./gradlew check\n```\n\n## Operating the Adaptor\n\n### Dependencies\n\nThe stateless GP Connect Consumer Adaptor does not use a database or a message queue.\n\nThe adaptor requires an [HSCN](https://digital.nhs.uk/services/health-and-social-care-network) network connection to use the [Spine Secure Proxy](https://developer.nhs.uk/apis/spine-core-1-0/ssp_overview.html).\n\nThe adaptor can access the [SDS FHIR API](https://digital.nhs.uk/developer/api-catalogue/spine-directory-service-fhir) over either the HSCN network or the public internet.\n\n### Logging\n\nThe adaptor logs to stdout within its container. You must aggregate all logs to store, monitor,\nand search them. You must choose a strategy and tooling appropriate for your infrastructure.\n\nThe adaptor uses the following log format by default:\n\n```\nYYYY-MM-DD HH:MM:SS.mmm Level={DEBUG/INFO/WARNING/ERROR} Logger={LoggerName} RequestId={RequestId} Ssp-TraceID={Ssp-TraceID} Thread=\"{ThreadName}\" Message=\"{LogMessage}\"\n```\n\n- **LoggerName** name of the Java class which emitted the log\n- **RequestId** randomly generated identified for each request\n- **Ssp-TraceID** value of the Ssp-TraceID header, for distributed tracing\n- **ThreadName** name of the thread handling the request\n- **LogMessage** content of the log message\n\nThe properties RequestId and Ssp-TraceID may only be populated if the log \nis emitted by application code. These are blank for logs emitted by framework or \nthird party code.\n\n## Mapping External (adaptor) URLs to internal (NHSD) URLs\n\nThe adaptor proxies its requests to internal NHSD URLs via the Spine Secure Proxy.\n\n```\nExample: Get structured record for a patient at practice with ODS code A12345\n\nThe request URL made to the adaptor includes the ODS code of the patient's practice. The two \nvariables (with * as wildcard) must have values matching the full request URL.\n\nhttps://gpcconsumer.prod.mydomain.com/A12345/STU3/1/gpconnect/structured/fhir/Patient/$gpc.getstructuredrecord\n|            Adaptor's Host          |          $GPC_CONSUMER_GPC_STRUCTURED_PATH                             |\n\nThe adaptor then performs an SDS lookup and constructs a new path using the Spine\nSecure Proxy and the practice's GP Connect Provider's internal URL.\n\nhttps://proxy.opentest.hscic.gov.uk/https://gpconnect.gpsytemsupplier.internal.nhs.uk/A12345/STU3/1/gpconnect/structured/fhir/Patient/$gpc.getstructuredrecord\n|       $GPC_CONSUMER_SSP_URL     |     [ From SDS Lookup ]                         |     [ Path from original request ]                                      |\n```\n\n### Additional Functionality\n\nThe adaptor re-writes URLs in response bodies to refer to adaptor URLs instead of GP Connect Provider URLs.\n\nFor example (Search for a patient's documents):\n\nWhen making a \"Search for a patient's documents\" request\n\n```\nGET https://orange.testlab.nhs.uk/B82617/STU3/1/gpconnect/fhir/Patient/2/DocumentReference?...\n```\n\nthe adaptor replaces the GP Connect Provider Hosts (`https://orange.testlab.nhs.uk/`) in the original response\n\n```\n...\n        {\n            \"fullUrl\": \"https://orange.testlab.nhs.uk/B82617/STU3/1/gpconnect/documents/fhir/DocumentReference/27863182736\",\n            \"resource\": {\n                \"resourceType\": \"DocumentReference\",\n                ...\n                \"content\": [\n                    {\n                        \"attachment\": {\n                            \"contentType\": \"application/msword\",\n                            \"url\": \"https://orange.testlab.nhs.uk/B82617/STU3/1/gpconnect/documents/fhir/Binary/07a6483f-732b-461e-86b6-edb665c45510\",\n                            \"size\": 3654\n                        }\n                    }\n                ],\n...\n```\n\nwith the dns name / port used in the original request.\n\n```\n...\n        {\n            \"fullUrl\": \"http://localhost:8090/B82617/STU3/1/gpconnect/documents/fhir/DocumentReference/27863182736\",\n            \"resource\": {\n                \"resourceType\": \"DocumentReference\",\n                ...\n                \"content\": [\n                    {\n                        \"attachment\": {\n                            \"contentType\": \"application/msword\",\n                            \"url\": \"http://localhost:8090/B82617/STU3/1/gpconnect/documents/fhir/Binary/07a6483f-732b-461e-86b6-edb665c45510\",\n                            \"size\": 3654\n                        }\n                    }\n                ],\n...\n```\n\n## Example Deployment\n\nWe release adaptor image on Dockerhub as [nhsdev/nia-gpc-consumer-adaptor][docker-hub-image],\nwith the latest changes documented within the [CHANGELOG.MD](/CHANGELOG.MD).\n\nWhen performing assurance against a simulated workload involving the transfer of 100MB documents, we\nhave identified a minimum of 2GB of RAM and 2 vCPUs to the container is required.\n\nWe provide [Terraform scripts][exemplar-deployment] to perform an exemplar deployment of the GP2GP adaptor\nand GP Connect Consumer adaptor into AWS.\n\n[exemplar-deployment]: https://github.com/nhsconnect/integration-adaptors/tree/develop/terraform/aws/components/gp2gp\n[docker-hub-image]: https://hub.docker.com/r/nhsdev/nia-gpc-consumer-adaptor\n\n## Licensing\nThis 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.\n\nThe contents of this repository are protected by Crown Copyright (C).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhsdigital%2Fintegration-adaptor-gpc-consumer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnhsdigital%2Fintegration-adaptor-gpc-consumer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhsdigital%2Fintegration-adaptor-gpc-consumer/lists"}