{"id":23421140,"url":"https://github.com/nhsdigital/integration-adaptor-111","last_synced_at":"2025-08-11T21:16:13.951Z","repository":{"id":37738251,"uuid":"264176431","full_name":"NHSDigital/integration-adaptor-111","owner":"NHSDigital","description":"National Integration Adaptors - Adaptor for NHS 111 Post Event Message","archived":false,"fork":false,"pushed_at":"2025-08-05T12:14:31.000Z","size":14414,"stargazers_count":3,"open_issues_count":5,"forks_count":9,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-08-05T14:22:16.343Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","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,"zenodo":null}},"created_at":"2020-05-15T11:29:48.000Z","updated_at":"2025-07-28T08:25:27.000Z","dependencies_parsed_at":"2024-03-06T17:24:48.179Z","dependency_job_id":"7ce46407-1c87-41fd-8e34-b084e2ebb5b2","html_url":"https://github.com/NHSDigital/integration-adaptor-111","commit_stats":null,"previous_names":["nhsdigital/integration-adaptor-111"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/NHSDigital/integration-adaptor-111","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fintegration-adaptor-111","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fintegration-adaptor-111/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fintegration-adaptor-111/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fintegration-adaptor-111/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NHSDigital","download_url":"https://codeload.github.com/NHSDigital/integration-adaptor-111/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NHSDigital%2Fintegration-adaptor-111/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269958397,"owners_count":24503552,"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","status":"online","status_checked_at":"2025-08-11T02:00:10.019Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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:08.142Z","updated_at":"2025-08-11T21:16:13.944Z","avatar_url":"https://github.com/NHSDigital.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# integration-adaptor-111\n\nThe 111 adaptor enables GP Practices to receive [NHS 111 Report messages](https://digital.nhs.uk/developer/api-catalogue/nhs-111) from NHS 111, for example into a GP system, following a patient's call to the free NHS 111 service. \n\nYou can receive and route a “post event message” to their GP when NHS 111 requests:\n\n* an ambulance call out\n* a referral to a local emergency department\n* a referral to an Out Of Hours service\n* a referral to their GP\n\nThe NHS 111 Report adaptor can receive messages from the NHS 111 service and post them to the mailbox of the relevant GP practice.\n\n## Adaptor Scope\nThe main objective of the 111 Adaptor is to hide complex legacy standards and instead present a simple and consistent interface aligned to current NHS England national standards.\nThe adaptor receives ITK 2.2 wrapped Clinical Document Architecture (CDA) XML documents over web services, and converts them into structured FHIR messages before posting them onto the GP system's inbound event queue.\n\nThe 111 adaptor consists of two docker images: [proxy](https://hub.docker.com/r/nhsdev/nia-111-nginx-adaptor) and [adaptor](https://hub.docker.com/r/nhsdev/nia-111-adaptor), you must deploy it within your own environment.\n\nThe following diagram illustrates the NHS 111 Report adaptor: \n![111 SysContext](/img/111SysContext.png)\n\n## Configuration\nThe adaptor reads its configuration from environment variables. The following sections describe the environment variables used to configure the adaptor.\n\n### Inbound Queue Configuration\nThe post event messages (PEM) handled by the adaptor are sent to the Active Message Queue within the GP supplier's own environment and are not stored within the NHS 111 adaptor itself.  \n\nYou need to configure the following environment variables to enable the version 1-0-0 protocol this:\n* PEM111_AMQP_BROKER\n* PEM111_AMQP_QUEUE_NAME\n* PEM111_AMQP_USERNAME\n* PEM111_AMQP_PASSWORD\n\nIf using RabbitMQ protocol 0-9-1 then the following variables need to be set:\n\n* PEM111_AMQP_BROKER - to prevent a breaking change, the full url should be given in the form of amqp://address:port. The address section will be extracted for configuration as long as your url conforms to containing :// and :. \n* PEM111_AMQP_PORT\n* PEM111_AMQP_PROTOCOL - needs to be set to \"0-9-1\"\n* PEM111_AMQP_QUEUE_NAME\n* PEM111_AMQP_USERNAME\n* PEM111_AMQP_PASSWORD\n* PEM111_AMQP_ROUTING_KEY\n* PEM111_AMQP_SSL_ENABLED - defaults to false\n\n### SOAP ITK\n\n* PEM111_SOAP_VALIDATION_ENABLED - Incoming SOAP ITK message can be validated. You can decide whether you want it enabled. Supported values are `true` and `false`\n* PEM111_SOAP_SEND_TO - if the validation is on then one of the checked fields is SOAP To - it's the URL of /report endpoint. You can set the expected value using this variable.\n\n### ITK HEADER\nODS code and DOS Service ID from ITK `addresslist.address` are validated against list of supported values.\nSupported ODS codes and DOS Service ID's should be separated with comma, for example `PEM111_ITK_ODS_CODE_LIST=RSHSO14A,20000729`\nValues should be set in the following env variables:\n* PEM111_ITK_ODS_CODE_LIST\n* PEM111_ITK_DOS_ID_LIST\n\nAlternatively you can configure the adaptor to fetch the ODS codes/DOS Ids from external server. Adaptor will read the configuration and reload it without any downtime. Following variables can be used to set up configuration service URL and the poll interval.\n* PEM111_ITK_EXTERNAL_CONFIGURATION_URL\n* PEM111_ITK_FETCH_INTERVAL_MIN\n\nConfiguration service has to expose a single GET endpoint returning application/json data in matching the following schema:\n```\n{\n  \"type\": \"object\",\n  \"required\": [\"odsCodes\", \"dosIds\"],\n  \"properties\": {\n    \"odsCodes\": {\n      \"type\": \"array\",\n      \"items\": {\n        \"type\": \"string\"\n      }\n    },\n    \"dosIds\": {\n      \"type\": \"array\",\n      \"items\": {\n        \"type\": \"string\"\n      }\n    }\n  }\n}\n```\n\nExample:\n```\n{\n   \"odsCodes\": [\n      \"EM396\",\n      \"5L399\"\n   ],\n   \"dosIds\": [\n      \"26428\",\n      \"96465\",\n      \"48583\"\n   ]\n}\n```\n\n#### ODS code/DOS ID validation rules\n- At least one property of `PEM111_ITK_ODS_CODE_LIST`, `PEM111_ITK_DOS_ID_LIST`, `PEM111_ITK_EXTERNAL_CONFIGURATION_URL` has to be set. Adaptor will fail to start if none is provided.\n- If you provide external service URL as well as ODS/DOS lists then external configuration overrides the defined lists.\n- Adaptor validates provided external service URL on startup. If the endpoint is unreachable, does not respond with HTTP 200 or responds with invalid data then adaptor will fail to start.\n- Incoming ITK message will be accepted when either ODS code or DOS Id is correct.\n\n\n### TLS Mutual Authentication\nNginx proxy is used to handle TLS MA. In order to configure it you need to set the following env variables:\n* NGINX_PUBLIC_CERT - Server public certificate\n* NGINX_PRIVATE_CERT - Server private certificate\n* NGINX_CLIENT_PUBLIC_CERT - Client public certificate\n* NGINX_CA_CERT - Root certificate\n* NGINX_CRL - Certificate revocation list\n* NGINX_CRL_URL - CRL URL - Nginx can download CRL on startup\n\n## Mapping documentation\nTo help understand what fields are populated by the adaptor we provide [ITK to FHIR field mappings](doc/ITK_FHIR_mapping.md).\n\nWe also provide [example JSON payloads](doc/json) of what the adaptor generates from an [incoming XML payload](doc/xml).  \n\n## ITK Testbench\nThe [ITK Testbench] provided by NHS England has an essential tool for ITK interface development and conformance.\nThis tool provides resources that will allow you to adequately test the 111 adaptor within your own environment.\n\n[ITK Testbench]: https://digital.nhs.uk/services/interoperability-toolkit/developer-resources/itk-test-centre/itk-testbench\n\n## Test Pack\nOur testing pack as well our test harness can be found inside the test-suite directory [Test-Suite](./test-suite)\n\n## NIA Support (NHS England) guidance\nIf you are looking to make changes to the adaptor you should first read the [guidance for developing the adaptor](nhs-england-developer-information.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhsdigital%2Fintegration-adaptor-111","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnhsdigital%2Fintegration-adaptor-111","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnhsdigital%2Fintegration-adaptor-111/lists"}