From fe520fa95a15a0b02fa3478aa0a71bfdeca7148d Mon Sep 17 00:00:00 2001
From: Alexandre P <apo@kereval.com>
Date: Tue, 6 Feb 2024 18:10:15 +0100
Subject: [PATCH] Add documentation for PIXm connector 3.0.0
---
Patient-Registry/installation.md | 329 +++++++++++----------
Patient-Registry/release-note.md | 20 +-
Patient-Registry/user.md | 474 ++++++++++---------------------
3 files changed, 336 insertions(+), 487 deletions(-)
diff --git a/Patient-Registry/installation.md b/Patient-Registry/installation.md
index 973edb1..5e86d1d 100755
--- a/Patient-Registry/installation.md
+++ b/Patient-Registry/installation.md
@@ -1,9 +1,9 @@
---
title: Installation Manual
subtitle: Patient Registry
-author: Franck Desaize
-releasedate: 12/07/2021
-toolversion: 2.0.x
+author: Franck Desaize, Alexandre POCINHO
+releasedate: 2024-02-02
+toolversion: 2.2.x
function: Developer
version: 0.01
status: Draft document
@@ -11,91 +11,90 @@ reference: KER1-MAN-IHE-PATIENT_REGISTRY_INSTALLATION-0_01
customer: IHE-EUROPE
---
-# Patient Registry
+# Patient Registry suite installation
-The Patient Registry project is dedicated to the management of patient demographics and identifiers test data.
+## Patient Registry (PATREG)
+
+The Patient Registry project is dedicated to the management of patient demographics and identifiers test data.
It will embed connectors such as FHIR PDQm, PIXm or PAM.
-## Sources & binaries
+### Sources & binaries
The sources are accessible here: [https://gitlab.inria.fr/gazelle/applications/test-execution/simulator/patient-registry](https://gitlab.inria.fr/gazelle/applications/test-execution/simulator/patient-registry)
-Bugs and issue tracking are accessible here : [https://gazelle.ihe.net/jira/projects/PATREG](https://gazelle.ihe.net/jira/projects/PATREG). The name
-of the latest release, can be obtained in the "Releases" section.
+Bugs and issue tracking are accessible here : [https://gazelle.ihe.net/jira/projects/PATREG](https://gazelle.ihe.net/jira/projects/PATREG). The name of the latest release, can be obtained in the "Releases" section.
To get official artifact (binaries), search for `patient-registry` in IHE Nexus : [https://gazelle.ihe.net/nexus](https://gazelle.ihe.net/nexus/#nexus-search;quick~patient-registry)
and select the **patient-registry.jar** artifact for download.
-## Installation
+### Installation
-### Patient Manager dependency
+#### Patient Manager dependency
-Patient Registry depends currently on the database of Patient Manager. Only patients created/managed in Patient Manager will be accessible in the
-Patient Registry Search API.
+Patient Registry depends currently on the database of Patient Manager. Only patients created/managed in Patient Manager will be accessible in the Patient Registry Search API.
Please follow [Patient Manager installation process](/gazelle-documentation/Patient-Manager/installation.html).
Patient Registry needs at least Patient Manager version 9.11.6.
-### Application server
+#### Application server
-Patient registry need to be deployed on Widlfly-18. Please read first the documentation on how to install and configure this server for Gazelle
-applications : [general considerations for WildFly 18](/gazelle-documentation/General/wildfly18.html)
+Patient registry need to be deployed on Widlfly-18.
+Please read first the documentation on how to install and configure this server for Gazelle
+applications : [general considerations for WildFly 18](https://gazelle.ihe.net/gazelle-documentation/General/wildfly18.html)
-### Database
+#### Database configuration
-Patient registry is using Patient Manager's database. It only needs a datasource connection declared in wildfly 18.
-See [Setup datasources for gazelle applications](/gazelle-documentation/General/wildfly18.html#setup-datasources-for-gazelle-applications)
+Patient registry is using Patient Manager's database. It only needs a datasource connection declared in wildfly 18.
+See [Setup datasources for gazelle applications](https://gazelle.ihe.net/gazelle-documentation/General/wildfly18.html#setup-datasources-for-gazelle-applications)
**Datasource name** : `patientRegistryDS`
-
+
**Database name** : `pam-simulator`
-### Deployment
+#### Deployment
-Copy the **jar** artifact app.patient-registry-service-X.X.X.jar in the deployment folder of the wildfly installation under the name
+Copy the **jar** artifact app.patient-registry-service-X.X.X.jar in the deployment folder of the wildfly installation under the name
**patient-registry.jar**. This is important for the path on which Patient Registry's web services will be exposed.
-```
+```bash
cp app.patient-registry-service-X.X.X.jar /usr/local/wildfly18/standalone/deployments/patient-registry.jar
-```
+```
Start wildfly. The API can be accessed at (depending on your configured host and port)
-For Patient processing Service :
- * GITB Processing Service : [GET http://localhost:8380/patient-registry/CrossReferenceService/xref-processing-service?wsdl ](http://localhost:8380/patient-registry/PatientProcessingService/patient-processing-service?wsdl )
+For Patient processing Service :
+
+* GITB Processing Service : GET <http://localhost:8380/patient-registry/PatientProcessingService/patient-processing-service?wsdl>
+
+For CrossReference Processing Service :
+
+* GITB Processing Service : GET <http://localhost:8380/patient-registry/CrossReferenceService/xref-processing-service?wsdl>
-For CrossReference Processing Service :
- - GITB Processing Service : [GET http://localhost:8380/patient-registry/CrossReferenceService/xref-processing-service?wsdl ](http://localhost:8380/patient-registry/CrossReferenceService/xref-processing-service?wsdl )
-# PDQm Connector
+## PDQm Connector
-PDQm Connector is a connector for Patient Registry. It is dedicated to interface FHIR requests defined in PDQm standard to and the
+PDQm Connector is a connector for Patient Registry. It is dedicated to interface FHIR requests defined in PDQm standard to and the
Patient Registry API for patient demographics and identifiers test data management.
-## Sources & binaries
+### Sources & binaries (PDQm)
The sources are accessible here: [https://gitlab.inria.fr/gazelle/applications/test-execution/simulator/pdqmsimulator](https://gitlab.inria.fr/gazelle/applications/test-execution/simulator/pdqmsimulator)
Bugs and issue tracking are accessible in the same project as the Patient Registry :
-[https://gazelle.ihe.net/jira/projects/PATREG](https://gazelle.ihe.net/jira/projects/PATREG).
+[https://gazelle.ihe.net/jira/projects/PATREG](https://gazelle.ihe.net/jira/projects/PATREG).
The name of the latest release, can be obtained in the "Releases" section.
To get official artifact (binaries), search for `pdqm-connector-service` in IHE Nexus : [https://gazelle.ihe.net/nexus](https://gazelle.ihe.net/nexus/#nexus-search;quick~pdqm-connector-service)
and select the **pdqm-connector.war** artifact for download.
-## Installation
-
-### Patient Manager dependency
+### Installation (PDQm)
-PDQm Connector, as Patient Registry, depends currently on the database of Patient Manager. It will use it to save transaction exchanged between SUTs and
-the simulator. Please follow [Patient Manager installation process](/gazelle-documentation/Patient-Manager/installation.html).
+#### Patient Manager dependency (PDQm)
-PDQm Connector needs at least Patient Manager version 9.11.6.
+Same as [Patient Manager Dependency for PATREG](#patient-manager-dependency)
-PDQm also needs Patient Registry to be installed.
-With connector version 1.0.x, you will need Patient Registry version 1.0.x.
+**AND** PDQm also needs Patient Registry to be installed with connector version >1.0.x, you will need Patient Registry version >1.0.x.
-
-### Operational Preferences
+#### Operational Preferences (PDQm)
PDQm connector defines mandatory Operational Preferences that you will have to define in your Application server.
To know how to do that, see [General considerations for WildFly 18](/gazelle-documentation/General/wildfly18.html)
@@ -106,125 +105,142 @@ This resource should refer to a deployment.properties file. This file shall cont
| Property Name | Description | Example value |
|--------------|-----------|------------|
-| patientregistry.url | URL of the Patient Registry Processing Service used to manage patients. | http://localhost:8580/patient-registry/patient-registry/PatientProcessingService/patient-processing-service?wsdl|
-
-### Application server
+| patientregistry.url | URL of the Patient Registry Processing Service used to manage patients. | <https://example.com/patient-registry/patient-registry/PatientProcessingService/patient-processing-service?wsdl>|
-Patient registry need to be deployed on Wildfly-18. Please read first the documentation on how to install and configure this server for Gazelle
-applications : [General considerations for WildFly 18](/gazelle-documentation/General/wildfly18.html)
+#### Application server (PDQm)
+PDQm need to be deployed on Wildfly-18. Please read first the documentation on how to install and configure this server for Gazelle applications : [General considerations for WildFly 18](/gazelle-documentation/General/wildfly18.html)
-#### Configure WildFly 18 for PDQm Connector
+##### Configure WildFly 18 f(PDQm)
Install factories module
-1. Stop wildfly and go to
-```bash
-sudo mkdir -p /usr/local/wildfly18/modules/system/layers/base/net/ihe/gazelle/factories/main
-cd /usr/local/wildfly18/modules/system/layers/base/net/ihe/gazelle/factories/main
-```
+1. Stop wildfly and go to:
-2. Download module `factories.jar`
-```bash
-sudo wget https://gazelle.ihe.net/wildfly18/factories.jar
-```
+ ```bash
+ sudo mkdir -p /usr/local/wildfly18/modules/system/layers/base/net/ihe/gazelle/factories/main
+ cd /usr/local/wildfly18/modules/system/layers/base/net/ihe/gazelle/factories/main
+ ```
-3. Create `module.xml` file
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<module xmlns="urn:jboss:module:1.1" name="net.ihe.gazelle.factories">
- <resources>
- <resource-root path="factories.jar"/>
- </resources>
- <dependencies>
- <module name="javax.api"/>
- <module name="javax.transaction.api"/>
- <module name="javax.servlet.api" optional="true"/>
- </dependencies>
-</module>
-```
+2. Download module `factories.jar`:
-4. Add `jboss:jboss-admin` rights
-```bash
-sudo chown jboss:jboss-admin *
-sudo chmod 775 *
-```
+ ```bash
+ sudo wget https://gazelle.ihe.net/wildfly18/factories.jar
+ ```
+
+3. Create `module.xml` file:
+
+ ```xml
+ <?xml version="1.0" encoding="UTF-8"?>
+ <module xmlns="urn:jboss:module:1.1" name="net.ihe.gazelle.factories">
+ <resources>
+ <resource-root path="factories.jar"/>
+ </resources>
+ <dependencies>
+ <module name="javax.api"/>
+ <module name="javax.transaction.api"/>
+ <module name="javax.servlet.api" optional="true"/>
+ </dependencies>
+ </module>
+ ```
+
+4. Add `jboss:jboss-admin` rights:
+
+ ```bash
+ sudo chown -R jboss:jboss-admin .
+ sudo chmod -R 775 .
+ ```
5. Stop Wildfly and edit standalone.xml in `/usr/local/wildfly18/standalone/configuration` ; add the factories binding in the naming subsystem :
-Replace this property `${DEPLOYMENT_PROPERTIES}` with your own path to the deployment property, which is stored in the pdqm-connector project : ``pdqm-connector/pdqm-connector-service/src/main/resources/deployment.properties``
+Replace this property `${DEPLOYMENT_PROPERTIES}` with your own path to the deployment property, which is stored in the pdqm-connector project : `pdqm-connector/pdqm-connector-service/src/main/resources/deployment.properties`
```xml
-<subsystem xmlns="urn:jboss:domain:naming:2.0">
- <bindings>
- <object-factory name="java:/app/gazelle/pdqm-connector/operational-preferences" module="net.ihe.gazelle.factories" class="net.ihe.gazelle.factories.PropertiesFactory">
- <environment>
- <property name="path" value="${DEPLOYMENT_PROPERTIES}"/>
- </environment>
- </object-factory>
- </bindings>
- <remote-naming/>
-</subsystem>
+ <subsystem xmlns="urn:jboss:domain:naming:2.0">
+ <bindings>
+ <object-factory name="java:/app/gazelle/pdqm-connector/operational-preferences" module="net.ihe.gazelle.factories" class="net.ihe.gazelle.factories.PropertiesFactory">
+ <environment>
+ <property name="path" value="${DEPLOYMENT_PROPERTIES}"/>
+ </environment>
+ </object-factory>
+ </bindings>
+ <remote-naming/>
+ </subsystem>
```
-### Database
+#### Database configuration (PDQm)
-PDQm is using Patient Manager's database. It only needs a datasource connection declared in wildfly 18.
-See [Setup datasources for gazelle applications](/gazelle-documentation/General/wildfly18.html#setup-datasources-for-gazelle-applications)
+Same as [Database for PATREG](#database-configuration) **EXCEPT FOR** :
-
-**Datasource name** : `pdqmConnectorDS`
-
+**Datasource name** : `pdqmConnectorDS`
**Database name** : `pam-simulator`
-### Deployment
+#### Deployment (PDQm)
-Copy the **war** artifact pdqm-connector-X.X.X.war in the deployment folder of the wildfly installation under the name
-**pdqm-connector.war**. This is important for the path on which connector's web services will be exposed.
+Copy the **war** artifact `pdqm-connector-X.X.X.war` in the deployment folder of the wildfly installation under the name `pdqm-connector.war`
+This is important for the path on which connector's web services will be exposed.
-```
+```bash
cp pdqm-connector-X.X.X.war /usr/local/wildfly18/standalone/deployments/pdqm-connector.war
-```
+```
Start wildfly. The API can be accessed at (depending on your configured host and port)
- * Retrieve : [GET http://localhost:8480/pdqm-connector/Patient/{id}](http://localhost:8480/pdqm-connector/Patient/{id})
- * Search : [POST http://localhost:8480/pdqm-connector/Patient](http://localhost:8480/pdqm-connector/Patient)
-# PIXm Connector
+* Retrieve : GET <https://www.example.com/pdqm-connector/Patient/{id}>
+* Search : POST <https://www.example.com/pdqm-connector/Patient>
+
+## PIXm Connector
PIXm Connector is a connector for Patient Registry. It is dedicated to interface FHIR requests defined in PIXm standard to and the
Patient Registry API for patient demographics and identifiers test data management.
-## Sources & binaries
+### Sources & binaries (PIXm)
-The sources are accessible here: [https://gitlab.inria.fr/gazelle/applications/test-execution/simulator/pixm-connector](https://gitlab.inria.fr/gazelle/applications/test-execution/simulator/pixm-connector.)
+The sources are accessible here: <https://gitlab.inria.fr/gazelle/applications/test-execution/simulator/pixm-connector>.
Bugs and issue tracking are accessible in the same project as the Patient Registry :
-[https://gazelle.ihe.net/jira/projects/PATREG](https://gazelle.ihe.net/jira/projects/PATREG).
+<https://gazelle.ihe.net/jira/projects/PATREG>.
The name of the latest release, can be obtained in the "Releases" section.
-To get official artifact (binaries), search for `pixm-connector` in IHE Nexus : [https://gazelle.ihe.net/nexus](https://gazelle.ihe.net/nexus/#nexus-search;quick~pixm-connector-service)
+To get official artifact (binaries), search for `pixm-connector-service` in IHE Nexus : [https://gazelle.ihe.net/nexus](https://gazelle.ihe.net/nexus/#nexus-search;quick~pixm-connector-service)
and select the **pixm-connector.war** artifact for download.
-## Installation
+### Installation (PIXm)
+
+#### Patient Manager dependency (PIXm)
-### Patient Manager dependency
+Same as [Patient Manager dependency for PATREG](#patient-manager-dependency)
-PIXm Connector, as Patient Registry, depends currently on the database of Patient Manager. It will use it to save transaction exchanged between SUTs and
-the simulator. Please follow [Patient Manager installation process](/gazelle-documentation/Patient-Manager/installation.html).
+PIXm also needs Patient Registry to be installed:
-PIXm Connector needs at least Patient Manager version 9.11.6.
+|PIXm version|PATREG version|
+|:---:|:---:|
+|`1.0.0`|`2.0.0`|
+|`2.0.0`|`2.1.0`|
+|`3.0.0`|`2.2.0`|
-PIXm also needs Patient Registry to be installed.
-With connector version 1.0.x, you will need Patient Registry version 2.0.x.
+#### Matchbox and Http-Validator dependencies (PIXm)
+Since `3.0.0` PIXm needs two deployed applications for validation:
-### Operational Preferences
+* HTTP-validator with the install documentation [here](https://gitlab.inria.fr/gazelle/public/validation/http-validator/-/blob/06997c194efc0f775d9af1c2aa7ae49e13d4d06d/documentation/installation.md).
+* Matchbox with the install documentation [here](https://github.com/ahdis/matchbox/blob/29da3b9dfec2334ceb031346ef12d0e08a626122/README.md)
+
+#### Operational Preferences
PIXm connector defines mandatory Operational Preferences that you will have to define in your Application server.
To know how to do that, see [General considerations for WildFly 18](/gazelle-documentation/General/wildfly18.html)
+/!\ Since `3.0.0` PIXm connector needs to be installed in Wildfly version that supports `JDK 17`. But the tutorial remains the same as Wildfly 18.
+
+|PIXm version|JDK version|Wildfly version|
+|:---:|:---:|:---:|
+|`1.0.0`|11|18.0.1.Final|
+|`2.0.0`|11|18.0.1.Final|
+|`3.0.0`|17|30.0.1.Final|
+
Define a resource in your server with name *java:/app/gazelle/pixm-connector/operational-preferences*.
+
```xml
<subsystem xmlns="urn:jboss:domain:naming:2.0">
<bindings>
@@ -238,74 +254,57 @@ Define a resource in your server with name *java:/app/gazelle/pixm-connector/ope
</subsystem>
```
-Replace this property `${DEPLOYMENT_PROPERTIES}` with your own path to the deployment property file.
+Replace this property `${DEPLOYMENT_PROPERTIES}` with the path to the `deployment.properties` file (like `/opt/pixm-connector/deployment.properties`)
-This resource should refer to a deployment.properties file. This file shall contain the following properties :
+This file shall contain the following properties :
-| Property Name |Â Description |Â Example valueÂ
-| patientregistry.url | URL of the Patient Registry Processing Service used to manage patients. | http://localhost:8580/patient-registry/PatientProcessingService/patient-processing-service?wsdl
-| xrefpatientregistry.url | URL of the CrossReference Processing Service used to XReference. | http://localhost:8580/patient-registry/CrossReferenceService/xref-processing-service?wsdl |
+|Property Name| Description | Example value |
+|:---:|:---:|:---:|
+| patientregistry.url | URL of the Patient Registry Processing Service used to manage patients.| <https://example.com/patient-registry/PatientProcessingService/patient-processing-service?wsdl>|
+| xrefpatientregistry.url | URL of the CrossReference Processing Service used to XReference. | <https://example.com/patient-registry/CrossReferenceService/xref-processing-service?wsdl> |
-### Application server
+Since version `3.0.0` PIXm needs:
-Patient registry need to be deployed on Wildfly-18. Please read first the documentation on how to install and configure this server for Gazelle
-applications : [General considerations for WildFly 18](/gazelle-documentation/General/wildfly18.html)
+* endpoints for matchbox and http-validator
+* profiles id (URL + headers validation with http-validator)
+* profile canonical url (body validation with Matchbox FHIR)
+|Property Name| Description | Example value |
+|:---:|:---:|:---:|
+|APP_HTTP_VALIDATOR_SERVER|Endpoint of HTTP-Validator|<https://www.example.com/http-validator>|
+|PROFILE_ID_CREATE_UPDATE_DELETE_ITI_104|Profile ID for ITI-104|IHE_ITI-104-PatientFeed_Query|
+|PROFILE_ID_POST_ITI_83|Profile ID for POST ITI-83|IHE_ITI-83_POST_PIXm_Query|
+|PROFILE_ID_GET_ITI_83|Profile ID for GET ITI-83|IHE_ITI-83_GET_PIXm_Query|
+|APP_IG_FHIR_SERVER|Endpoint for Matchbox|<https://www.example.com/matchboxv3/fhir>|
+|PIXM_PATIENT_PROFILE|Canonical URL for PIXm Patient Profile|<https://profiles.ihe.net/ITI/PIXm/StructureDefinition/IHE.PIXm.Patient>|
+|PIXM_PARAMETERS_PROFILE|Canonical URL for PIXm Paramaters Profile|<https://profiles.ihe.net/ITI/PIXm/StructureDefinition/IHE.PIXm.Query.Parameters.In>|
-#### Configure WildFly 18 for Pixm Connector
+#### Application server (PIXm)
-Install factories module
+Same as [Application Server (PDQm)](#application-server-pdqm) for both Wildfly 18 and Wildfly 30.
-1. Stop wildfly and go to
-```bash
-sudo mkdir -p /usr/local/wildfly18/modules/system/layers/base/net/ihe/gazelle/factories/main
-cd /usr/local/wildfly18/modules/system/layers/base/net/ihe/gazelle/factories/main
-```
+#### Deployment (PIXm)
-2. Download module `factories.jar`
-```bash
-sudo wget https://gazelle.ihe.net/wildfly18/factories.jar
-```
+Copy the **war** artifact `pixm-connector-X.X.X.war` (< 3.0.0) or `pixm-connector-service-X.X.X.war` (>= 3.0.0) in the deployment folder of the wildfly installation under the name
+`pixm-connector.war`.
+This is important for the path on which connector's web services will be exposed.
-3. Create `module.xml` file
-```xml
-<module xmlns="urn:jboss:module:1.1" name="net.ihe.gazelle.factories">
- <resources>
- <resource-root path="factories.jar"/>
- </resources>
- <dependencies>
- <module name="javax.api"/>
- </dependencies>
-</module>
-```
+Before `3.0.0`:
-4. Add `jboss:jboss-admin` rights
```bash
-sudo chown jboss:jboss-admin *
-sudo chmod 775 *
+cp pixm-connector-X.X.X.war /usr/local/wildfly18/standalone/deployments/pixm-connector.war
```
+Since `3.0.0`:
-### Database
-
-PIXm is using Patient Manager's database. It only needs a datasource connection declared in wildfly 18.
-See [Setup datasources for gazelle applications](/gazelle-documentation/General/wildfly18.html#setup-datasources-for-gazelle-applications)
-
-
-**Datasource name** : `pixmConnectorDS`
-
-**Database name** : `pam-simulator`
-
-### Deployment
-
-Copy the **war** artifact pixm-connector-X.X.X.war in the deployment folder of the wildfly installation under the name
-**pixm-connector.war**. This is important for the path on which connector's web services will be exposed.
-
+```bash
+cp pixm-connector-service-X.X.X.war /usr/local/wildfly30/standalone/deployments/pixm-connector.war
```
-cp pixm-connector-X.X.X.war /usr/local/wildfly18/standalone/deployments/pixm-connector.war
-```
-Start wildfly. The API can be accessed at (depending on your configured host and port)
-* ITI-83 : [GET http://localhost:8580/pixm-connector/fhir_ihe/Patient/$ihe-pix?sourceIdentifier={sourceIdentifier}(&targetSystem={targetsystem,...})(&_format=json)](http://localhost:8580/pixm-connector/fhir_ihe/Patient/$ihe-pix?sourceIdentifier={sourceIdentifier}(&targetSystem={targetsystem,...})(&_format=json))
+Start wildfly.
+
+The API can be accessed at (depending on your configured host and port):
-* ITI-93 : shall be reachable to perform a feed. Create and Delete method have been implemented.
+* ITI-104 : PUT/DELETE <https://example.com/pixm-connector/fhir/Patient?identifier=patient.system|patient.id>
+* ITI-83 : GET <https://example.com/pixm-connector/fhir/Patient/$ihe-pix?sourceIdentifier=patient.system|patient.id&targetSystem=targetSystem>
+* Capability statement : <https://example.com/pixm-connector/fhir/metadata>
diff --git a/Patient-Registry/release-note.md b/Patient-Registry/release-note.md
index 073874f..435f5bd 100755
--- a/Patient-Registry/release-note.md
+++ b/Patient-Registry/release-note.md
@@ -1,14 +1,28 @@
---
title: Release note
subtitle: PatientRegistry
-toolversion: 2.1.0
-releasedate: 2021-09-10
-author: Franck Desaize
+toolversion: 2.2.0
+releasedate: 2024-01-31
+author: Franck Desaize / Alexandre POCINHO
function: Software Engineer
customer: IHE Europe
reference: KER1-RNO-IHE-PATIENT_MANAGER
---
+# PIXm Connector 2.0.0
+_Release date: 2024-02-02_
+
+__New Feature__
+* \[[PATREG-220](https://gazelle.ihe.net/jira/browse/PATREG-220)\] Implementation of ITI-104
+* \[[PATREG-221](https://gazelle.ihe.net/jira/browse/PATREG-221)\] Validation Feature w/ Matchbox
+* \[[PATREG-222](https://gazelle.ihe.net/jira/browse/PATREG-222)\] Validation Feature w/ HTTP-Validator
+* \[[PATREG-223](https://gazelle.ihe.net/jira/browse/PATREG-223)\] Upgrade to Java 17 and Jakarta
+
+# Patient Registry 2.2.0
+_Release date: 2024-01-31_
+__Epic__
+* \[[PATREG-216](https://gazelle.ihe.net/jira/browse/PATREG-216)\] [CH] Adaptation of the new PIXm specifications
+
# PIXm Connector 2.0.0
_Release date: 2021-09-10_
diff --git a/Patient-Registry/user.md b/Patient-Registry/user.md
index 63c9801..9d41195 100755
--- a/Patient-Registry/user.md
+++ b/Patient-Registry/user.md
@@ -1,391 +1,227 @@
---
title: User Manual
subtitle: Patient Registry
-author: Franck Desaize
-releasedate: 2021-07-09
-toolversion: 2.1.x
+author: Alexandre POCINHO
+releasedate: 2024-02-02
+toolversion: 3.0.0
function: Engineer
version: 0.1
status: validated
---
-# Introduction
-The Patient Registry Tool
+# Patient Registry Tool suite
-# Pixm Connector
+Outline:
----
-### Prerequisites
-- Java 11 with maven.
-- WildFly 18.
----
-### Build project locally
+- [PIXm Connector Component](#pixm-connector-component)
-After cloning this repository to your local installation launch
+ - [Overview](#overview)
+ - [Validation Process](#validation-process)
+ - [ITI-83 Request cross reference identifiers](#request-a-patient-cross-reference-on-a-specific-target-identifier-iti-83)
+ - [ITI-104 Request on Patient Resources](#requests-on-patient-resources-iti-104)
+ - [Create/Update](#createupdate)
+ - [Merge duplicated patient](#merge-for-resolving-duplicated-patient)
+ - [Delete patient](#delete-one-or-more-patients)
+ - [Errors returned](#errors-returned)
-```bash
- > mvn clean install
-```
+## PIXm Connector Component
-from the project root directory.
+### Overview
+Here is a quick overview of the available functionality from PIXm connector
-The artifact pixm_fhir_server.war will be created in target/ directory.
+| Operation | HTTP Methods | URL to call | Entry parameter | Returned value |
+|--------------------------------|--------------|--------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------|------------------------------------------|
+| Create/Update Patient | PUT | ```https://example.com/pixm-connector/fhir/Patient?identifier={{patient.system}}\|{{patient.id}}``` | ITI-104 Patient identifier | ITI-104 FHIR Patient |
+| Delete Patient | DELETE | ```https://example.com/pixm-connector/fhir/Patient/?identifier={{patient.system}}\|{{patient.id}}``` | ITI-104 Patient identifier | / |
+| Merge Patient | PUT | ```https://example.com/pixm-connector/fhir/Patient/?identifier={{patient.system}}\|{{patient.id}}``` | ITI-104 Patient identifier w/ patient.link to Patient to keep | ITI-104 FHIR Patient |
+| Check Cross Referenced Patient | GET | ```https://example.com/pixm-connector/fhir/Patient/$ihe-pix?sourceIdentifier={{patient.system}}\|{{patient.id}}&targetSystem={{targetSystem}}``` | A Patient sourceIdentifier and a TargetDomain | ITI-83 FHIR Parameters with X-ref values |
+Capability statement of the application can be found with : <https://example.com/pixm-connector/fhir/metadata>
----
-### Deploy on WildFly server
+As described in [HAPI FHIR resources](https://hapifhir.io/hapi-fhir/docs/server_plain/rest_operations_operations.html), some strings are automatically escaped when the FHIR server parses URLs:
-After building the project through Maven, the artifact created just has to be added to your local WildFly installation in the folder
-```bash
- {$wildfly.home}/standalone/deployments
-```
+|Given String|Parsed as|
+| :---: | :---: |
+|\||%7C|
+|=>=|=%3E%3D|
+|=<=|=%3C%3D|
+|=>|=%3E|
+|=<|=%3C|
----
-### Request a Patient on a specific Target Identifier
+### Validation process
-Once the project deployed on your WildFly, you can now call it to request a cross Referenced Patient in the Patient Registry.
+Each operation implies a validation of requests for both `ITI-104` and `ITI-83` transactions.
+Validation is done by calling:
-Parameters allowed are :
+- [HTTP Validator](https://gitlab.inria.fr/gazelle/applications/test-execution/validator/http-validator) for URL and Headers.
+- [Matchbox](https://www.matchbox.health/) for Body with FHIR Resource.
-- The Patient Identifier and the Target System attributed to this identifier
-- The Target System you want the cross reference from.
-- The format returned.
+Both validators allow to perform validation and have high customization if specifications changed for both transactions without refactoring pixm-connector application.
+An error during validation process will result with an OperationOutcome with error `400 Bad Request` with issues describing where it failed.
-Cardinality for these parameters will be described in each profile since it's the main difference between each.
+### Request a Patient Cross Reference on a specific Target Identifier (ITI-83)
-### IHE Profile
+- [IHE Specifications](https://profiles.ihe.net/ITI/PIXm/ITI-83.html)
-The URL to call is
-```http
- {wildfly18.address}/pixm_fhir_server/fhir_ihe/Patient/$ihe-pix
-```
+Request a cross-referenced Patient is possible thanks to the `$ihe-pixm`.
+Parameters allowed are :
-|Parameter name|Cardinality|Parameter Type|Description|
-|--------------|-----------|--------------|-----------|
-|sourceIdentifier|1..1|Token|The Patient identifier search parameter that will be used by the Patient Identifier Cross-reference Manager to find cross matching identifiers associated with the Patient Resource
-|targetSystem|0..*|uri|The target Patient Identifier Assigning Authority from which the returned identifiers should be selected.|
-|_format|0..1|mime-type|The requested format of the response. Accepted values : JSON and XML|
+- The Patient Identifier and the Target System attributed to this identifier as `sourceIdentfier`
+- The Target System you want the cross-reference from as `targetSystem`.
+- The format returned as `_format`: **xml** or **json**.
-### CH Profile
+The URL to call is:
-The URL to call is
```http
- {wildfly18.address}/pixm_fhir_server/fhir_ch/Patient/$ihe-pix
+ GET https://example.com/pixm-connector/fhir/Patient/$ihe-pix
```
-
-|Parameter name|Cardinality|Parameter Type|Description|
-|--------------|-----------|--------------|-----------|
-|sourceIdentifier|1..1|Token|The Patient identifier search parameter that will be used by the Patient Identifier Cross-reference Manager to find cross matching identifiers associated with the Patient Resource
-|targetSystem|1..2|uri|The target Patient Identifier Assigning Authority from which the returned identifiers should be selected.|
-|_format|0..1|mime-type|The requested format of the response. Accepted values : JSON and XML|
-
For example :
-Given the Patient with the ID 69420 in the Target System 1.3.6.1.4.1.21367.13.20.3000
-And you want the cross referenced patient in the target system 1.3.6.1.4.1.21367.13.20.1000
+Given the Patient with the `id=69420` with the `system=urn:oid:1.3.6.1.4.1.21367.13.20.3000` as `sourceIdentifer=system|id`
+And you want the cross-referenced patient in the `targetSystem=1.3.6.1.4.1.21367.13.20.1000`
+And you want the returned response as a `json`.
The corresponding url will be :
-```http
- {wildfly18.address}/pixm_fhir_server/fhir_ihe/Patient/$ihe-pix?sourceIdentifier=urn:oid:1.3.6.1.4.1.21367.13.20.3000|69420&targetSystem=urn:oid:1.3.6.1.4.1.21367.13.20.1000
-```
-
----
-### Error returned
-Malformed requests can cause different types of error, here is a quick overview of how to troubleshoot them :
-
-- An error 400 Bad Request is returned when the source domain given within the source identifier parameter is not recognized by the Patient Registry as an asigning authority.
-In the case of our request above, the value "urn:oid:1.3.6.1.4.1.21367.13.20.3000" is not a valid source domain able to register Patients
-
-Common mistakes with the source domain include :
-- Forgetting the namespace in front of the adress (urn:oid:)
-- Malformed source domain.
-The source domain can have the form of an url
```http
-sourceIdentifier=https://your.domain|id
-```
-or of an adress, which must follows the pattern x.x.x.x.x.x.x.x.x.x
-```http
-sourceIdentifier=urn:oid:x.x.x.x.x.x.x.x.x.x|id
+ https://example.com/pixm-connector/fhir/Patient/$ihe-pix?sourceIdentifier=urn:oid:1.3.6.1.4.1.21367.13.20.3000|69420&targetSystem=urn:oid:1.3.6.1.4.1.21367.13.20.1000&_format=json
```
---
-- An error 403 Forbidden is returned when a target domain given in the target system parameter is not recognized by the Patient Registry.
-In the case of our request above, the value "urn:oid:1.3.6.1.4.1.21367.13.20.1000" is not recognized as a valid target domain containing Patients.
+### Requests on Patient resources (ITI-104)
-Common mistakes with the target system are the same as the aformentioned error 400 since the target system and the source domain have the same representation.
+- [IHE Specifications](https://profiles.ihe.net/ITI/PIXm/ITI-104.html)
---
-- An error 404 Not Found is returned when the patient identifier given within the source identifier parameter is not recognized by the Patient registry.
-In the case of our request above, the value "69420" is not a valid Identifier linked to an existing Patient.
+#### Create/Update
+Link: <https://profiles.ihe.net/ITI/PIXm/ITI-104.html#2310441-add-or-revise-patient>
-## PIXm Feed
+PIXm connector accepts the creation of a Patient in the Patient Manager.
+Although a Patient could be created without any information in the HL7 model, PIXm connector will only allow a Patient
+to be created with minimum and/or mandatory information to permits cross-reference thanks to validation with Matchbox.
-The simulator PIXm has been upgraded. It's now able to perform feed on Xreference Manager for CH profiles. Two methods are available for Swiss implementation.
-* **Create** : PIXm Simulator is able to handle create query. Using Bundle and Patient FHIR resources. (See documentation in the project for more information)
-* **Delete** : PIXm Simulatir is able to handle delete query. Using Bundle and Patient FHIR resources. (See documentation in the project for more information)
+The Resource could not be parsed or failed basic FHIR validation rules.
+In the case of an error `400 Bad Request` or `422 Unprocessable Entity` being returned,
+please check the following guidelines to verify your query.
-## CREATE METHOD :
-__________________________________________________________________
-Send the following REST Request
-#### Bundle Resource :
- POST : {serverAdress}/ch_fhir/Bundle/
+Create/Update request is done through a FHIR conditional update mechanism ([cond-update](http://hl7.org/fhir/http.html#cond-update)) where the patient identifier has to be given as following.
+```http
+ PUT https://example.com/pixm-connector/fhir/Patient/identifier=urn:oid:1.3.6.1.4.1.21367.13.20.1000|IHERED-m94
+```
-With a prefilled body as following for Bundle:
+With body :
+
+```json
-```json
{
- "resourceType" : "Bundle",
- "id" : "BundlePIXmFeed",
- "meta" : {
- "profile" : [
- "http://fhir.ch/ig/ch-epr-mhealth/StructureDefinition/ch-pixm-bundle"
- ]
- },
- "type" : "message",
- "entry" : [
- {
- "fullUrl" : "http://example.com/fhir/MessageHeader/1",
- "resource" : {
- "resourceType" : "MessageHeader",
- "id" : "1",
- "text" : {
- "status" : "generated",
- "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative</b></p><p><b>event</b>: <code>urn:ihe:iti:pmir:2019:patient-feed</code></p><h3>Destinations</h3><table class=\"grid\"><tr><td>-</td><td><b>Endpoint</b></td></tr><tr><td>*</td><td><a href=\"http://example.com/patientEndpoint\">http://example.com/patientEndpoint</a></td></tr></table><h3>Sources</h3><table class=\"grid\"><tr><td>-</td><td><b>Endpoint</b></td></tr><tr><td>*</td><td><a href=\"http://example.com/patientSource\">http://example.com/patientSource</a></td></tr></table><p><b>focus</b>: <a href=\"#Bundle_abc\">See above (Bundle/abc)</a></p></div>"
- },
- "eventUri" : "urn:ihe:iti:pmir:2019:patient-feed",
- "destination" : [
- {
- "endpoint" : "http://example.com/patientEndpoint"
- }
- ],
- "source" : {
- "endpoint" : "http://example.com/patientSource"
- },
- "focus" : [
- {
- "reference" : "Bundle/abc"
- }
- ]
- }
- },
- {
- "fullUrl" : "http://example.com/fhir/Bundle/abc",
- "resource" : {
- "resourceType" : "Bundle",
- "id" : "abc",
- "type" : "history",
- "entry" : [
- {
- "fullUrl" : "http://example.com/fhir/Patient/PatientPIXmFeed",
- "resource" : {
- "resourceType" : "Patient",
- "id" : "PatientPIXmFeed",
- "text" : {
- "status" : "generated",
- "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative</b></p><p><b>id</b>: PatientPIXmFeed</p><p><b>meta</b>: </p><p><b>identifier</b>: Medical record number = 8734</p><p><b>name</b>: Franz Muster , Muster </p><p><b>gender</b>: male</p><p><b>birthDate</b>: 1995-01-27</p></div>"
- },
- "contained" : [
- {
- "resourceType" : "Organization",
- "id" : "org1",
- "identifier" : [
- {
- "system" : "${system}",
- "value" : "${value}"
- }
- ],
- "address" : [
- {
- "use" : "work",
- "line" : [
- "Doktorgasse",
- "2"
- ],
- "city" : "Musterhausen",
- "postalCode" : "8888",
- "country" : "CH"
- }
- ]
- }
- ],
- "identifier" : [
- {
- "type" : {
- "coding" : [
- {
- "system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
- "code" : "MR"
- }
- ]
- },
- "system" : "${#system}",
- "value" : "${#value}"
- }
- ],
- "name" : [
- {
- "family" : "${#name.family}",
- "given" : [
- "${#name.given}"
- ]
- },
- {
- "family" : "${#name.family}",
- "_family" : {
- "extension" : [
- {
- "url" : "http://hl7.org/fhir/StructureDefinition/iso21090-EN-qualifier",
- "valueCode" : "BR"
- }
- ]
- }
- }
- ],
- "gender" : "${#gender}",
- "birthDate" : "${#birthDate}",
- "managingOrganization" : {
- "reference" : "#org1"
- }
- },
- "request" : {
- "method" : "POST",
- "url" : "Patient"
- },
- "response" : {
- "status" : "200"
- }
- }
- ]
- }
- }
+ "resourceType" : "Patient",
+ "id" : "Patient-MaidenAlice-Red",
+ "meta" : {
+ "profile" : [
+ "https://profiles.ihe.net/ITI/PIXm/StructureDefinition/IHE.PIXm.Patient"
]
- }
-```
+ },
+ "text" : {
+ "status" : "generated",
+ "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p style=\"border: 1px #661aff solid; background-color: #e6e6ff; padding: 10px;\"><b>ALICE MOHR </b> female, DoB: 1958-01-30 ( id:\u00a0IHERED-m94)</p><hr/><table class=\"grid\"><tr><td style=\"background-color: #f3f5da\" title=\"Record is active\">Active:</td><td colspan=\"3\">true</td></tr></table></div>"
+ },
+ "identifier" : [
+ {
+ "system" : "urn:oid:1.3.6.1.4.1.21367.13.20.1000",
+ "value" : "IHERED-m94"
+ }
+ ],
+ "active" : true,
+ "name" : [
+ {
+ "family" : "MOHR",
+ "given" : [
+ "ALICE"
+ ]
+ }
+ ],
+ "gender" : "female",
+ "birthDate" : "1958-01-30"
+}
+```
+
+If the patient exists then it is updated otherwise it is created.
+The response will return the updated/created patient.
-## CREATE METHOD :
-__________________________________________________________________
+---
-#### Patient Resource :
+#### Merge for resolving duplicated patient
-Send the following REST Request
+Link : <https://profiles.ihe.net/ITI/PIXm/ITI-104.html#2310442-resolve-duplicate-patient>
- POST : {serverAdress}/ch_fhir/Patient/
+The merge method allows the user to merge two patients together if two registered patients represent the same people.
+This action is **irreversible** as it deactivates a resource making it only readable and immutable.
+The request is a PUT method with the Patient to deactivate with a `activate: false` attribute and a `link` field with identifier for the kept patient resource.
-With a prefilled body as following :
+```http
+PUT http://example.org/fhir/Patient?identifier=urn:oid:1.3.6.1.4.1.21367.13.20.1000|IHERED-m94 HTTP/1.1
+Accept: application/fhir+json
+Content-Type: application/fhir+json
+```
-```json
+```json
{
- "resource" : {
- "resourceType" : "Patient",
- "id" : "PatientPIXmFeed",
- "text" : {
- "status" : "generated",
- "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative</b></p><p><b>id</b>: PatientPIXmFeed</p><p><b>meta</b>: </p><p><b>identifier</b>: Medical record number = 8734</p><p><b>name</b>: Franz Muster , Muster </p><p><b>gender</b>: male</p><p><b>birthDate</b>: 1995-01-27</p></div>"
- },
- "contained" : [
- {
- "resourceType" : "Organization",
- "id" : "org1",
- "identifier" : [
- {
- "system" : "${system}",
- "value" : "${value}"
- }
- ],
- "address" : [
- {
- "use" : "work",
- "line" : [
- "Doktorgasse",
- "2"
- ],
- "city" : "Musterhausen",
- "postalCode" : "8888",
- "country" : "CH"
- }
- ]
- }
- ],
- "identifier" : [
- {
- "type" : {
- "coding" : [
- {
- "system" : "http://terminology.hl7.org/CodeSystem/v2-0203",
- "code" : "MR"
- }
- ]
- },
- "system" : "${#system}",
- "value" : "${#value}"
- }
- ],
- "name" : [
- {
- "family" : "${#name.family}",
- "given" : [
- "${#name.given}"
- ]
- },
- {
- "family" : "${#name.family}",
- "_family" : {
- "extension" : [
- {
- "url" : "http://hl7.org/fhir/StructureDefinition/iso21090-EN-qualifier",
- "valueCode" : "BR"
- }
- ]
+ "resourceType": "Patient",
+ "identifier": [
+ {
+ "system": "urn:oid:1.3.6.1.4.1.21367.13.20.1000",
+ "value": "IHERED-m94"
+ }
+ ],
+ "active": false,
+ "name": [
+ {
+ "family": "MOHR",
+ "given": [
+ "MAIDEN"
+ ]
+ }
+ ],
+ "gender": "female",
+ "birthDate": "1958-01-30",
+ "link": [
+ {
+ "other": {
+ "identifier": {
+ "system": "urn:oid:1.3.6.1.4.1.21367.13.20.1000",
+ "value": "IHERED-994"
}
- }
- ],
- "gender" : "${#gender}",
- "birthDate" : "${#birthDate}",
- "managingOrganization" : {
- "reference" : "#org1"
+ },
+ "type": "replaced-by"
+ }
+ ]
}
-
-```
-
-
-These parameters are mandatory in CREATE method
-* name.given
-* name.family
-* birthdate
-* gender
+```
+#### Delete one or more patient(s)
-### DELETE METHOD
-______________________________________________________________________
-#### Patient Resource :
+Link: <https://profiles.ihe.net/ITI/PIXm/ITI-104.html#2310443-remove-patient>
-Send the following REST Request
+The delete operation allows suppression of the patient with its identifier thanks to a conditional deletion.
+This application allows multiple deletion if the identifier returned more than one Patient.
- Delete : {serverAdress}/ch_fhir/Patient/{uuid}
+````http
+DELETE http://example.org/fhir/Patient?identifier=urn:oid:1.3.6.1.4.1.21367.13.20.1000|IHERED-994 HTTP/1.1
+Accept: application/fhir+json
+````
-#### Bundle Resource :
+if the delete is successful the application returns a `200 OK` response otherwise it would be a `204 No Content`.
-Send the following REST Request
->DELETE : {serverAdress}/Bundle/{id}
-
-Same body as a create except :
-* request method must be "delete" at the end :
-```json
-
- "request" : {
- "method" : "DELETE",
- "url" : "Patient"
- },
-```
+### Errors returned
+---
-* Mandatory field to fill in case of DELETE method :
- * uuid
+Malformed requests can cause different types of error, for now `422 Unprocessable Entity` is mostly returned.
+Future features will allow a better granularity for code returned.
--
GitLab