SanteDB within Instant OpenHIE

Instructions on how to integrate SanteDB with the instant openhie project

Creating a Santedb package

Pre-requisites:

Example project can be found at: https://github.com/santedb/santempi-openhie-package

Create a fresh SanteDB Package

The minimum needed to create a package is an instant.json file, a Docker folder, and a Kubernetes folder. The instant.json file will look something like shown below. 

{
    "id": "santempi",
    "name": "client-registry",
    "description": "OpenHIE CR Based on SanteMPI",
    "type": "infrastructure",
    "version": "v2.1.3",
    "dependencies": ["client", "core"]
 }

Docker Folder

The docker folder will need the following items:

  • A compose.sh file

  • A docker-compose.yml file

  • Either docker-compose.config.yml files and/or a docker-compose.dev.yml file

  • Potentially an Importer folder, which while not necessarily required, will make life easier - this would enable you to preconfigure channels, instead of having to manually create them.

Kubernetes Folder

The Kubernetes folder will need the following items:

  • A k8s.sh file

  • Kubernetes resource files, in our example we have:

    • db-deployment.yaml

    • db-service.yaml (These are for the Postgres Image)

    • santedb-deployment.yaml

    • santedb-service.yaml (This are for the santedb-mpi image)

    • santedb-mpi-app-persistentvolumeclaim.yaml, santedb-mpi-config-persistentvolumeclaim.yaml, santedb-mpi-seed-persistentvolumeclaim

  • Potentially an Importer folder, which while not necessarily required, will make life easier - this would enable you to preconfigure channels, instead of having to manually create them.

More information on the importer folder can be found: https://openhie.github.io/instant/docs/how-to/configure-openhim-mapping-mediator

Running the SanteDB Package

Run on Docker

Navigate to the OpenHIE/Instant repository. Type the following commands

Next we need to run the images

The above command is specifying to run docker, specifying the package santempi (Which will link to the id property of the instant.json file), and specifying a path of where to find the image.

It make take several minutes to build. And after it's complete, you may need to wait a couple more minutes for the santedb-mpi server to be fully initialized. Once it's done, you should see something that looks like the following:

There are other containers available. These are the minimum required to use the santedb package with the instant openhie project.

You can navigate to http://localhost:9000 and be brought to the login screen.

Channels - If using the example project

If you've used the example project, or have used an Importer, you should be able to see santedb channels.

Currently the channels need to be public, in order to access SanteDB

Channels - If creating manually

If you are creating a channel manually, click on the green + Channel near the bottom left.

For basic info give a channel name, and a brief description. In this example we are going to use the admin API, so you could call the channel Santedb MPI Admin

For request matching there are two things you need to do

  • enter a URL pattern (in our case /ami) - make sure you unclick Auto-add regex delimiters

  • Make the channel public

Finally, for Routes, add a new route with the following info:

  • Route Name: SanteDB Admin

  • Host: santedb-mpi (this is referencing the docker container name)

  • Port: 8080 (this is referencing the internal docker port on the container)

  • Forward existing Authorization Headers: yes

Click set route.

Run on Kubernetes

Navigate to the OpenHIE/Instant repository. Type the following commands

Next we need to run the images

The above command is specifying to run docker, specifying the package santempi (Which will link to the id property of the instant.json file), and specifying a path of where to find the image. The only difference between this and docker, is you're changing the keyword 'docker' to 'k8s'.

The kubernetes deployments will take much longer to build than the docker deployments. Afterwards it will look something like the following image (Note: This might change depending on what packages you're running)

You can navigate to http://localhost:9000 and be brought to the login screen.

Manually Adding Channels

To manually add a santedb channel, once logged in, click on the channel section and the green Channel + button.

Adding a channel is almost identical to docker. (See above) - The differences is when adding a route, instead of using the container name, as in docker, you will need to use the IP Address of the pod.

To obtain the pod:

The pod we want is the santeDB pod, santedb-66bf68f744-xpsnh (This will change as the name is dynamic, but it should be prefixed with santedb)

The above command will display the details of this pod. At the top of the JSON blob you can see the IP Address.

Now you can add the IP Address as the host for the route.

One quick note when manually adding channels, you may need to check to ensure the role has permission to access the channel. You can check by clicking on the Clients tab on the left hand side. Check the role you are attempting to use, if you see an X over the santedb channels, you can click the x and it will change the permission.

Testing, and viewing transactions

We will now test to make sure we can see SanteDB transactions in openHIM. You will need to generate a bearer token in order to successfully access santedb services. We will test with an administrator account, so we will be using the SanteMPI Admin Channel.

To generate a bearer token:

SanteDB requires that you use a bearer token to access services on the SanteDB server. For full documentation see the OpenID Connect Documentation. A quick method to authenticate yourself with:

Testing the channels

To test we are going to make API calls using something like Postman, or maybe curl. For this demo I will use postman.

Under the Authorization tab for postman, select type as Bearer Token - In the value, enter the bearer token that you have generated.

We are going to make a simple get request using http://localhost:5001/ami/SecurityUser

We're targeting port 5001 here, as this is one of the ports open in the openhim-core container. If successful, our request should redirect through the openhim-core, to santedb. And a transaction should have been created.

You should see a 200 response. Now, go back to the OpenHIM console. You should see transactions being displayed. It will look similar to the image below:

Transactions

Congratulations, you have now verified your santedb package within the instant openhim!

PreviousFeature ConfigurationNextUsing Virtual Appliances

Last updated

Was this helpful?