Pixm Connector

Prerequisites

• Java 11 with maven.
• WildFly 18.

Build project locally

After cloning this repository to your local installation launch

    > mvn clean install

from the project root directory.

The artifact pixm_fhir_server.war will be created in target/ directory.

Deploy on WildFly server

After building the project through Maven, the artifact created just has to be added to your local WildFly installation in the folder

    {$wildfly.home}/standalone/deployments

Overview

Here is a quick overview of the available functionnality from PIXm connector

Request a Patient Cross Reference on a specific Target Identifier (ITI-83)

Once the project deployed on your WildFly, you can now call it to request a cross Referenced Patient in the Patient Registry.

Parameters allowed are :

• The Patient Identifier and the Target System attributed to this identifier
• The Target System you want the cross reference from.
• The format returned.

Cardinality for these parameters will be described in each profile since it's the main difference between each.

IHE Profile

The URL to call is

    {wildfly18.address}/pixm_fhir_server/fhir_ihe/Patient/$ihe-pix

CH Profile

The URL to call is

    {wildfly18.address}/pixm_fhir_server/fhir_ch/Patient/$ihe-pix

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

The corresponding url will be :

    {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

sourceIdentifier=https://your.domain|id

or of an adress, which must follows the pattern x.x.x.x.x.x.x.x.x.x

sourceIdentifier=urn:oid:x.x.x.x.x.x.x.x.x.x|id

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.

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.

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.

Requests on Patient resources (ITI-93)

PIXm connector implements query for ITI-93

Many of those requests will take an ITI-93 Bundle as a Pramaeter

Create

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 information to permits cross referenciation.

The request takes only one argument, a bundle with three required components :

• A Message header.
• A Bundle of type history, describing the Patient resource to be created.

The "required" fields in the Patient are :

• A name (either Family, or Given, or both).
• A Country.
• A Gender.
• An Identifier. (?)

A MessageHeader shall contains

A history type bundle shall contains

If the Creation is succesful, an http response 200 will be returned, with a Bundle containing the Patient information, and an Endpoint to view the Patient in browser.

If it's not the case, a myriad of error can be returned to help you pinpoint why your request cannot be interpreted.

The Resource could not be parsed or failed basic FHIR validation rules. In the case of an error 400 being returned, please check the following guidelines to verify your query.

• The Bundle does not countain minimum information needed for creation verify if the following arguments are given in the Patient and have the corresponding types and size.
  • A name (either Family, or Given, or both).
  • A Country.
  • A Gender.
  • An Identifier. (?)

The Bundle might be malformed, and does not countain one of the main component - A Message header. - A Bundle of type history, describing the Patient resource to be created.

Two main event can cause an 404 response.

• The endpoint provided for the request might be wrong, check the validity of the url on your endpoint. Usually, your endpoint should look like

    {wildfly18.address}/pixm_fhir_server/fhir_ihe/Patient/$create?{Bundle}

Check your wildfly18 address then, by opening it in a web browser you should get a 403 Forbidden error thrown out, indicating you're indeed pointing at the right server.

• The other common reason causing this error is the Resource type asked not being supported by PIXm. This means the part "/Patient" in the url is not right, either because you choosed another Resource type (like an Observation or a Bundle instead of Patient) which does not support the operation create, or because you mistyped it.

This error is complementary to the 400 Bad Request error. Whereas the 400 happens when the bundle is "syntactically" malformed. For example, a required element is not present in the bundle. The inside value of the parameter might be completly abnormal. In the case of an error 422, the Bundle object sent is SEMANTICALLY erroneous.

In this case, check the core of your request, maybe the Message Header Value is incoherent. Maybe one of the value in the Patient does not have any endpoint.

In this case the best way to solve this error is by checking the Payload sent to the server, maybe a Value is erroneous. This error case sends an Operation Outcome REsource with it, you should check it as it contains additional information about where the error shoud come from exactly.

This error is surely none of your doing. If one of this occurs, send a Ticket to the corresponding authority providing you the service.

Update

The Update method allows the user to update a Patient in the Patient Registry through PIXm. The Request sent is the same as the create method, The endpoint is the only difference between the two, since it encapsulates the method used. It also needs the sourceIdentifier from the Patient to modify, if you're not sure about it, you can always use the @Read Method described under.

You can then follow the create operation explanation above for in-detail details about the parameters needed.

The returned value is the Updated Patient. Error values returned contain the same as the Create operation and even more. We will not go through the errors already explained in the Create section but will add information on the errors :

Is returned when the token for authentication is not valid to perform this method.

When the resource pointed is not found

When the resource sended is not of the same version as the resource stored in patient registry

Merge

The merge method allows the user to merge two patients together if it is deemed reasonable to think those two registered patients represent the same people

Delete

Read