diff --git a/common/README.md b/common/README.md index a96e0e05b..fe578afe9 100644 --- a/common/README.md +++ b/common/README.md @@ -1,25 +1,25 @@ # Common -This is a common module used by GP2GP Translator, GPC Api Facade and DB Connector modules. +This is a common module used by GP2GP Translator, GPC API Facade and DB Connector modules. It holds any common util classes used by more than one module. -## Util classes description +## Utility classes description ### DateUtils -Class for date-related methods. -- `getCurrentOffsetDateTime()` method returns current UTC OffsetDateTime. +Utility class for date-related methods. +- `getCurrentOffsetDateTime()` method returns the current UTC `OffsetDateTime`. ### FhirParser This class offers methods for parsing and encoding FHIR resources. -- `parseResource(String body, Class fhirClass)` method parses String to given FHIR resource. -- `encodeToJson(IBaseResource resource)` method parses FHIR resource to String. +- `parseResource(String body, Class fhirClass)` method parses a `String` to a given FHIR resource. +- `encodeToJson(IBaseResource resource)` method encodes a FHIR resource to a `String`. ### ParametersUtils -Here you can find method related to `Parameters` FHIR resource. -- `getNhsNumberFromParameters(Parameters parameters)` method retrieves patient's NHS number value - from Parameters resource. +This class provides a method related to the `Parameters` FHIR resource. +- `getNhsNumberFromParameters(Parameters parameters)` method retrieves the patient's NHS number value + from a `Parameters` resource. ### CreateParametersUtil -This class keeps convenient methods for creating `Parameters` FHIR resource objects. +This class provides convenient methods for creating `Parameters` FHIR resource objects. Meant to be used inside test classes. - `createValidParametersResource(String nhsNumberValue)` method returns a `Parameters` resource - with given patient NHS number set. + with a given patient NHS number set. diff --git a/db-connector/README.md b/db-connector/README.md index 8ffa9eec3..d3c18e471 100644 --- a/db-connector/README.md +++ b/db-connector/README.md @@ -1,30 +1,30 @@ # DB connector -This is a common module, used by GP2GP Translator and GPC Api Facade. +This is a common module, used by GP2GP Translator and GPC API Facade. It holds services needed for communication with the database. ## Migrations -Migrations are implemented using Liquibase and need to be run manually before starting applications. +Migrations are implemented using Liquibase and need to be run manually before starting the applications. To run the migrations, you need to specify the database URL and credentials of the database user that will be used to run the migrations. **This user needs to have permissions to create a database.** The first migration will try to connect to the default postgres database, to be able to create -the patient_switching database used by the adapter. Then, the next set of the migrations -will be executed on the patient_switching database. +the `patient_switching` database used by the adaptor. Then, the next set of migrations +will be executed on the `patient_switching` database. -Set the following env variables: -- PS_DB_OWNER_NAME -- POSTGRES_PASSWORD -- PS_DB_URL +Set the following environment variables: +- `PS_DB_OWNER_NAME` +- `POSTGRES_PASSWORD` +- `PS_DB_URL` To run the migrations use the following command: ```shell script ./gradlew update ``` -Changelog can be found under /changelog path. +The changelog can be found under the `/changelog` path. ### How to add migrations -To add a new migration, create a new xml file inside `/changelog/migration` directory. +To add a new migration, create a new XML file inside the `/changelog/migration` directory. All files from this directory are included in the `db.changelog-master.xml` file. ## How to run tests @@ -43,8 +43,8 @@ All files from this directory are included in the `db.changelog-master.xml` file ## Troubleshooting -### gradle-wrapper.jar doesn't exist +### `gradle-wrapper.jar` doesn't exist -If gradle-wrapper.jar doesn't exist run in terminal: -* Install Gradle (MacOS) `brew install gradle` -* Update gradle `gradle wrapper` +If `gradle-wrapper.jar` doesn't exist, run in terminal: +* Install Gradle (macOS): `brew install gradle` +* Update Gradle: `gradle wrapper` diff --git a/gp2gp-translator/README.md b/gp2gp-translator/README.md index 5f70fd491..4d3cd33bd 100644 --- a/gp2gp-translator/README.md +++ b/gp2gp-translator/README.md @@ -1,6 +1,6 @@ # GP2GP Translator -GP2GP Translator - new system that is the heart of the PSS Adaptor. +GP2GP Translator - a new system that is the heart of the PSS Adaptor. It is responsible for GPC ↔︎ GP2GP translations, assembly of binary document data, communication with the incumbent system via MHS Adaptor and data cleanup. @@ -20,26 +20,26 @@ communication with the incumbent system via MHS Adaptor and data cleanup. ### How to run integration tests: -Integration tests require running database and queue. -Make sure GP2GP Translator application is off, because if it's not, it will steal the message from the `inbound` queue -before the application started by tests have a chance to grab it. +Integration tests require a running database and queue. +Make sure the GP2GP Translator application is off, because if it's not, it will steal the message from the `inbound` queue +before the application started by the tests has a chance to grab it. -Running tests form the terminal: +Running tests from the terminal: ```shell script ./gradlew integrationTest ``` You can also run tests from IntelliJ, just remember to set the database password -inside the `gp2gp-translator/src/integrationTest/resources/application.yml` file (or set GP2GP_TRANSLATOR_USER_DB_PASSWORD variable). +inside the `gp2gp-translator/src/integrationTest/resources/application.yml` file (or set the `GP2GP_TRANSLATOR_USER_DB_PASSWORD` variable). -If your get lots of integration tests failures within the fixtures you can set the `BaseEhrHandler.OVERWRITE_EXPECTED_JSON` +If you get lots of integration test failures within the fixtures, you can set the `BaseEhrHandler.OVERWRITE_EXPECTED_JSON` to `true` to regenerate them. Once regenerated, review the changes made using `git diff` or similar. ## Troubleshooting -### gradle-wrapper.jar doesn't exist +### `gradle-wrapper.jar` doesn't exist -If gradle-wrapper.jar doesn't exist run in terminal: -* Install Gradle (MacOS) `brew install gradle` -* Update gradle `gradle wrapper` +If `gradle-wrapper.jar` doesn't exist, run in terminal: +* Install Gradle (macOS): `brew install gradle` +* Update Gradle: `gradle wrapper` diff --git a/gpc-api-facade/README.md b/gpc-api-facade/README.md index 912ede702..185faefdd 100644 --- a/gpc-api-facade/README.md +++ b/gpc-api-facade/README.md @@ -5,16 +5,16 @@ It enables NME to request and fetch patient data in the FHIR format. This facade only serves light tasks, delegating all the work to the async GP2GP Translator component. ## Enabling TLS -To turn on the TLS MA, set SSL_ENABLED env variable to true. Also, you'll need to create a keystore and a truststore +To turn on TLS Mutual Authentication (MA), set the `SSL_ENABLED` environment variable to `true`. You will also need to create a keystore and a truststore and set paths to them along with required passwords in those variables: -- KEY_STORE: path to the keystore -- KEY_STORE_PASSWORD: keystore password -- KEY_PASSWORD: server private key password -- TRUST_STORE: path to the truststore -- TRUST_STORE_PASSWORD: truststore password - -To allow docker to fetch the keystore and truststore, you need to bind a directory containing them. -You can achieve this by adding these lines to gpc_facade service in docker-compose.yml, below the `networks` part: +- `KEY_STORE`: path to the keystore +- `KEY_STORE_PASSWORD`: keystore password +- `KEY_PASSWORD`: server private key password +- `TRUST_STORE`: path to the truststore +- `TRUST_STORE_PASSWORD`: truststore password + +To allow Docker to fetch the keystore and truststore, you need to bind a directory containing them. +You can achieve this by adding these lines to the `gpc_facade` service in `docker-compose.yml`, below the `networks` part: ```yml volumes: - type: bind @@ -22,44 +22,66 @@ volumes: target: /certs #path on the docker volume ``` -You also need to import server's private key to the keystore, and import trusted client's public certificates -(or root CA cert) to the truststore. Below you can find the instruction on how to create the server and client certificates +You also need to import the server's private key to the keystore, and import the trusted client's public certificates +(or root CA certificate) to the truststore. Below you can find the instructions on how to create the server and client certificates and how to import them. ### Creation of certificates 1. Create the Root CA: -> openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer +``` +openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer +``` 2. Create the Server Private Key -> openssl genrsa -out server_private.key 4096 +``` +openssl genrsa -out server_private.key 4096 +``` 3. Create the CSR with private key for Root CA -> openssl req -new -key server_private.key -out server.csr -sha256 +``` +openssl req -new -key server_private.key -out server.csr -sha256 +``` 4. Create the Server Public Certificate -> openssl x509 -req -in server.csr -CA ca.cer -CAkey ca.key -set_serial 100 -extensions server -days 1460 -outform PEM -out server_public.cer -sha256 +``` +openssl x509 -req -in server.csr -CA ca.cer -CAkey ca.key -set_serial 100 -extensions server -days 1460 -outform PEM -out server_public.cer -sha256 +``` -5. Create a PKCS12 cert for server (it's needed to import the private key to the keystore) -> openssl pkcs12 -export -inkey server_private.key -in server_public.cer -out server_pkcs.p12 +5. Create a PKCS12 cert for the server (it's needed to import the private key to the keystore) +``` +openssl pkcs12 -export -inkey server_private.key -in server_public.cer -out server_pkcs.p12 +``` 6. Create the client private key -> openssl genrsa -out client_private.key 4096 +``` +openssl genrsa -out client_private.key 4096 +``` 7. Create the CSR with client private key -> openssl req -new -key client_private.key -out client.csr +``` +openssl req -new -key client_private.key -out client.csr +``` 8. Create the client public certificate -> openssl x509 -req -in client.csr -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client_public.cer +``` +openssl x509 -req -in client.csr -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client_public.cer +``` -8. Create a PKCS12 cert for client -> openssl pkcs12 -export -inkey client_private.key -in client_public.cer -out client_pkcs.p12 +9. Create a PKCS12 cert for the client +``` +openssl pkcs12 -export -inkey client_private.key -in client_public.cer -out client_pkcs.p12 +``` -9. Import the server private key (using pkcs) to the keystore (keystore will be created if it doesn't exist) -> keytool -importkeystore -srckeystore server_pkcs.p12 -srcstoretype PKCS12 -destkeystore keystore.jks -deststoretype JKS +10. Import the server private key (using PKCS) to the keystore (keystore will be created if it doesn't exist) +``` +keytool -importkeystore -srckeystore server_pkcs.p12 -srcstoretype PKCS12 -destkeystore keystore.jks -deststoretype JKS +``` -10. Import the public client certificate to the truststore (truststore will be created if it doesn't exist) -> keytool -keystore truststore.jks -importcert -file client_public.cer -alias client +11. Import the public client certificate to the truststore (truststore will be created if it doesn't exist) +``` +keytool -keystore truststore.jks -importcert -file client_public.cer -alias client +``` ## How to run tests @@ -76,18 +98,18 @@ and how to import them. ``` ### How to run integration tests: -*Integration tests require running database and queue.* -Running tests form the terminal: +*Integration tests require a running database and queue.* +Running tests from the terminal: ```shell script ./gradlew integrationTest ``` You can also run tests from IntelliJ, just remember to set the database password -inside the `gpc-api-facade/src/integrationTest/resources/application.yml` file (or set GPC_FACADE_USER_DB_PASSWORD variable). +inside the `gpc-api-facade/src/integrationTest/resources/application.yml` file (or set the `GPC_FACADE_USER_DB_PASSWORD` variable). ## Troubleshooting -### gradle-wrapper.jar doesn't exist +### `gradle-wrapper.jar` doesn't exist -If gradle-wrapper.jar doesn't exist run in terminal: -* Install Gradle (MacOS) `brew install gradle` -* Update gradle `gradle wrapper` +If `gradle-wrapper.jar` doesn't exist, run in terminal: +* Install Gradle (macOS): `brew install gradle` +* Update Gradle: `gradle wrapper` diff --git a/schema/README.md b/schema/README.md index 24647059e..c430f248a 100644 --- a/schema/README.md +++ b/schema/README.md @@ -1,11 +1,11 @@ # Schema module -This module holds xsd schemas and java classes generated based on those schemas. -Schema files can be found inside src/resources directory. +This module holds XSD schemas and Java classes generated based on those schemas. +Schema files can be found inside the `src/resources` directory. -## Generating java classes +## Generating Java classes -#### NOTE: Please use the newest version of the plugin: [gradle-xjc-plugin](https://github.com/unbroken-dome/gradle-xjc-plugin) +### NOTE: Please use the newest version of the plugin: [gradle-xjc-plugin](https://github.com/unbroken-dome/gradle-xjc-plugin) 1. Add `org.unbroken-dome.xjc` plugin in build.gradle: @@ -21,23 +21,23 @@ Schema files can be found inside src/resources directory. srcDirName = 'resources/schema' } ``` -3. After reloading gradle, `xjcGenerate` gradle task should be present under - 'code generation' category. Execute this task, it will generate java classes +3. After reloading Gradle, the `xjcGenerate` Gradle task should be present under + the `code generation` category. Execute this task, it will generate Java classes based on schemas pointed in srcDirName property in build.gradle. -4. Generated classes should be under `build/generated/sourced/xjc/java/main` path. - Copy them to `src/main/java` directory. Modify generated classes as needed. - Execute gradle `clean` task and remove changes added to build.gradle file. +4. Generated classes should be under `build/generated/sources/xjc/java/main` path. + Copy them to `src/main/java` directory. Modify the generated classes as needed. + Execute the Gradle `clean` task and remove the changes added to the `build.gradle` file. ## Generating individual JAXB elements for testing -When writing unit tests, you may be required to unmarshall code elements that haven't been pre-generated. The error you will see if this is the case will follow the general pattern of: +When writing unit tests, you may be required to unmarshal XML elements that haven't been pre-generated. The error you will see if this is the case will follow the general pattern of: ``` unexpected element (uri:"", local:"YOUR_ELEMENT"). Expected elements are <{urn:hl7-org:v3}PARENT_ELEMENT> ``` -This will require you add these elements directly to the `ObjectFactory.java` class independently. +This will require you to add these elements directly to the `ObjectFactory.java` class independently. 1. In `ObjectFactory.java`, register your element's QNAME in the custom made QNAME area. ``` @@ -55,7 +55,7 @@ This will require you add these elements directly to the `ObjectFactory.java` cl ## Manually modified classes -Please make sure you don't override the following classes with the generated ones. They had to be manually changed to allow correct unmarshalling xml files to java objects: +Please make sure you don't overwrite the following classes with the generated ones. They had to be manually changed to allow correct unmarshalling of XML files to Java objects: - EN.java - RCMRMT030101UK04Place.java - IVLTS.java @@ -99,16 +99,13 @@ Please make sure you don't override the following classes with the generated one - RCMRMT030101UK04Prescribe.java - RCMRMT030101UK04SupplyAnnotation.java - RCMRMT030101UK04Predecessor.java -- TS.java -- RCMRMT030101UK04NarrativeStatement.java - RCMRMT030101UK04InterpretationRange.java - RCCTMT120101UK01Device.java -- RCMRMT030101UK04InterpretationRange.java - RCMRMT030101UK04SpecimenMaterial.java Removed files: - ST.java New file: -- ValueAdapter.java - this is custom adapter helping with unmarshalling value element, - which can be of few different types +- ValueAdapter.java - this is a custom adapter helping with unmarshalling the value element, + which can be of a few different types diff --git a/smoke-tests/README.md b/smoke-tests/README.md index d367dd21d..c140b4d9c 100644 --- a/smoke-tests/README.md +++ b/smoke-tests/README.md @@ -1,25 +1,25 @@ # Smoke Tests -## Running the smoke test +## Running the smoke tests 1. Make sure the environment is set up -2. Ensure you are in the `smoketests` directory -3. Run `.\run-smoke-tests.sh `, where the parameter is the location of your configuration shell script. +2. Ensure you are in the `smoke-tests` directory +3. Run `./run-smoke-tests.sh `, where the parameter is the location of your configuration shell script. -#### Troubleshooting on M1 mac +### Troubleshooting on M1 Mac Issue: `zsh: permission denied: ./run-smoke-tests.sh` -Resolution: to give smoke tests script the permission to run - in your terminal run `chmod +x run-smoke-tests.sh` +Resolution: To give the smoke tests script the permission to run, in your terminal run `chmod +x run-smoke-tests.sh` ---- Issue: `zsh: permission denied: ./gradlew` -Resolution: to give gradlew the permission to run - in your terminal run `chmod +x gradlew` +Resolution: To give `gradlew` the permission to run, in your terminal run `chmod +x gradlew` ---- Issue: `Error: Could not find or load main class org.gradle.wrapper.GradleWrapperMain` -Resolution: ensure gradle is installed and the right version within the smoketest directory - run `brew install gradle` +Resolution: Ensure Gradle is installed and the correct version is present within the `smoke-tests` directory. Run `brew install gradle` diff --git a/snomed-database-loader/README.md b/snomed-database-loader/README.md index 251d94ad8..0e34b0a44 100644 --- a/snomed-database-loader/README.md +++ b/snomed-database-loader/README.md @@ -16,19 +16,19 @@ These immunization codes are constructed from using the following methods: ### Immunization root codes -The SNOMED CT schema is build in a hierarchical structure with a relationship reference set which defines whether a -particular is a child of another code (identified using the type code of `116680003` (`IsA`)). These root codes refer -to a certain set of codes under which most other immunization codes exists. +The SNOMED CT schema is built in a hierarchical structure with a relationship reference set which defines whether a +particular code is a child of another code (identified using the type code of `116680003` (`IsA`)). These root codes refer +to a certain set of codes under which most other immunization codes exist. These root codes are as follows: -| SNOMED Code | Description | -|----------------|---------------------------------------------------------------------------| -| 787859002 | Vaccine Product (medicinal product) | -| 127785005 | Administration to produce immunity, either active or passive (procedure) | -| 304250009 | Immunization status (finding) | -| 90351000119108 | Vaccination not done (situation) | -| 713404003 | Vaccination given (situation) | +| SNOMED Code | Description | +|----------------|--------------------------------------------------------------------------| +| 787859002 | Vaccine Product (medicinal product) | +| 127785005 | Administration to produce immunity, either active or passive (procedure) | +| 304250009 | Immunization status (finding) | +| 90351000119108 | Vaccination not done (situation) | +| 713404003 | Vaccination given (situation) | ### Immunization root code descendants @@ -42,7 +42,7 @@ This hierarchy can be illustrated using the [SNOMED CT Browser](https://termbrow ### Immunizations outside of root code hierarchy There also exist a number of codes which do not sit within the hierarchy of the root codes listed above. These are -usually codes for which an immunization is not provided anymore but may be present on the history of a patients. +usually codes for which an immunization is not provided anymore but may be present on the history of a patient. An example of one of these codes in the [SNOMED CT Browser](https://termbrowser.nhs.uk/) is below: ![immunization_not_in_hierarchy_example.png](immunization_not_in_hierarchy_example.png) @@ -50,11 +50,8 @@ An example of one of these codes in the [SNOMED CT Browser](https://termbrowser. However, the reference set used to build the immunization codes still includes inactive relationships, so these will be included when building the descendants of immunization root codes. -If the immunization codes have not been loaded successfully into the SNOMED DB then a RuntimeException with twill be thrown during -initialization of the GP2GP Translator Service and the service will then terminate. - -If the immunization codes have not been loaded successfully into the SNOMED DB, The GP2GP Translator Service will now -exit and throw a RuntimeException with the following message: +If the immunization codes have not been loaded successfully into the SNOMED DB, the GP2GP Translator Service will +exit and throw a RuntimeException during initialization with the following message: ``` FATAL: Expected Immunization codes not found in snomedct.immunization_codes view. SNOMED CT Database not set up correctly. @@ -66,7 +63,7 @@ Please update / reload the SNOMED DB. ## How to run (Mac & Unix) -### Prerequsistes +### Prerequisites 1. Download SNOMED CT Release 2. Set the following env vars: - PS_DB_OWNER_NAME (database user, needs permissions to create/drop schemas), e.g. `export PS_DB_OWNER_NAME='postgres'` diff --git a/test-suite/README.md b/test-suite/README.md index cc7f55c6e..6f18f3b7e 100644 --- a/test-suite/README.md +++ b/test-suite/README.md @@ -1,25 +1,25 @@ # Getting started with Postman tests -## Pre-reqs before running Postman tests -1. Ensure you have built the docker containers by following the build process from the root [README](../README.md) -2. Postman installed -3. Import the scripts into Postman `nia-patient-switching-standard-adaptor\test-suite\postman\Medicus Test Collection PSS Adaptor.postman_collection.json` -4. Certificates have been added to postman +## Prerequisites before running Postman tests +1. Ensure you have built the Docker containers by following the build process from the root [README](../README.md) +2. Ensure Postman is installed +3. Import the scripts into Postman `nia-patient-switching-standard-adaptor\test-suite\postman\Test Collection PSS Adaptor.postman_collection.json` +4. Certificates have been added to Postman 1. Open Postman / Settings (cog symbol) 2. Go to Certificates tab inside Settings menu 3. Turn on CA Certificates and add the `rootCA.pem` file from `nia-patient-switching-standard-adaptor\test-suite\postman\localhost-certificates` 4. Click on Add certificate next to Client Certificates 5. Add the `spineClient` file - 6. Add the `spintClient.key` + 6. Add the `spineClient.key` 7. Change the Host location to `localhost` : `443` 8. Click on Add 9. Close Settings menu ## Setting up test-suite adaptors to run Postman tests -1. Use the terminal and CD into folder `\nia-patient-switching-standard-adaptor\test-suite` +1. Use the terminal and navigate into folder `\nia-patient-switching-standard-adaptor\test-suite` 2. Run the start script `./start-test-environment.sh` 3. Allow the system to build adaptors -4. After building your docker suite should look something like this (containers can appear in any order): +4. After building, your Docker suite should look something like this (containers can appear in any order):
``` @@ -41,9 +41,9 @@ This is especially useful for the SNOMED data which takes a long time to import. If you want to start from a fresh DB, delete the volume with `docker volume rm test-suite_pgdata` and then run `./start-test-environment.sh`. ## Running the translator and facade in your IDE for debugging -1. Ensure test-suite environment is setup from steps above -2. Turn off both the `ps_gp2gp_transaltor-1` and `gpc_facade-1` in docker desktop -3. Open the project:`nia-patient-switching-standard-adaptor` +1. Ensure test-suite environment is set up from steps above +2. Turn off both the `ps_gp2gp_translator-1` and `gpc_facade-1` in Docker Desktop +3. Open the project: `nia-patient-switching-standard-adaptor` 4. Navigate to `nia-patient-switching-standard-adaptor\gp2gp-translator\src\main\java\uk\nhs\adaptors\pss\translator\Gp2gpTranslatorApplication.java` 5. Run `Gp2gpTranslatorApplication.java` with the environment variables below: @@ -75,7 +75,7 @@ If you want to start from a fresh DB, delete the volume with `docker volume rm t SDS_API_KEY: "change_if_needed" # used for calculating migration timeouts - #changepathforsnomedFilepath + # Change path for SNOMED filepath SNOMED_CT_TERMINOLOGY_FILE: "/snomed/file/location/uk_sct2mo_41.0.0_20250924000001Z.zip" PS_LOGGING_LEVEL: "DEBUG" @@ -98,9 +98,9 @@ GPC_FACADE_USER_DB_PASSWORD: "123456" ### Troubleshooting: -- Check that both `Gp2gpTranslatorApplication.java` + `GpcFacadeApplication.java` are running locally +- Check that both `Gp2gpTranslatorApplication.java` and `GpcFacadeApplication.java` are running locally - Check the environment variables -- Check that both the `ps_gp2gp_translator-1` + `gpc_facade-1` have stopped running -- Check the certificates in postman +- Check that both the `ps_gp2gp_translator-1` and `gpc_facade-1` have stopped running +- Check the certificates in Postman - If the start script doesn't run, check the file permissions to ensure the script is executable or run with elevated privileges i.e. `sudo ./start-test-environment.sh`