# SanteDB within Instant OpenHIE ## Creating a Santedb package ### Pre-requisites: * Clone the openhie/instant repo: * Have docker installed - There is a prerequisite documentation on the openhie wiki which explains the docker requirements: * Be familiar with how to create an Instant OpenHIE package: {% hint style="info" %} Example project can be found at: {% endhint %} ### 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. {% tabs %} {% tab title="instant.json" %} ``` { "id": "santempi", "name": "client-registry", "description": "OpenHIE CR Based on SanteMPI", "type": "infrastructure", "version": "v2.1.3", "dependencies": ["client", "core"] } ``` {% endtab %} {% endtabs %} #### 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. {% hint style="info" %} More information on the importer folder can be found: {% endhint %} ## Running the SanteDB Package ### Run on Docker Navigate to the OpenHIE/Instant repository. Type the following commands ``` yarn yarn docker:build ``` Next we need to run the images ``` yarn docker:instant init -t docker santempi -c="" ``` 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: ``` whitet@Mohawks-MBP instant % docker container ls CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 58d391d05922 santesuite/santedb-mpi:2.1.3 "mono /santedb/Sante…" 33 seconds ago Up 28 seconds 0.0.0.0:2100->2100/tcp, :::2100->2100/tcp, 0.0.0.0:8082->8080/tcp, :::8082->8080/tcp santedb-mpi c27b8358cd41 hapiproject/hapi:v5.2.1 "catalina.sh run" 57 seconds ago Up 54 seconds 8080/tcp hapi-fhir 3056b77f1a9b mysql:5.7 "docker-entrypoint.s…" About a minute ago Up 57 seconds 3306/tcp, 33060/tcp hapi-mysql 161a5071d2ca jembi/openhim-core:5 "docker-entrypoint.s…" About a minute ago Up 47 seconds 0.0.0.0:5000-5001->5000-5001/tcp, :::5000-5001->5000-5001/tcp, 0.0.0.0:5050-5052->5050-5052/tcp, :::5050-5052->5050-5052/tcp, 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp openhim-core 8903414d9b11 mongo:4.2 "docker-entrypoint.s…" About a minute ago Up About a minute 27017/tcp mongo-1 c1e4e3e15802 postgres "docker-entrypoint.s…" 22 hours ago Up 33 seconds 5432/tcp sdb-postgres 7874397ec2ae intrahealth/opencr:6195bd8 "/bin/sh -c 'dockeri…" 22 hours ago Up 37 seconds 0.0.0.0:3004->3000/tcp, :::3004->3000/tcp opencr e42421df077c intrahealth/elasticsearch:latest "/usr/local/bin/dock…" 22 hours ago Up 42 seconds 0.0.0.0:9200->9200/tcp, :::9200->9200/tcp, 9300/tcp es b79d9cd172fd jembi/openhim-console:1.14 "/docker-entrypoint.…" 22 hours ago Up 55 seconds 0.0.0.0:9000->80/tcp, :::9000->80/tcp openhim-console d2a1eb344eee mongo:4.2 "docker-entrypoint.s…" 22 hours ago Up About a minute 27017/tcp mongo-2 a53e45cd7c94 mongo:4.2 "docker-entrypoint.s…" 22 hours ago Up About a minute 27017/tcp mongo-3 whitet@Mohawks-MBP instant % ``` There are other containers available. These are the minimum required to use the santedb package with the instant openhie project. You can navigate to and be brought to the login screen. * default username is: * default password is: instant101 #### 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](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LZ0_pjgTp_kx4hqTZ3a%2F-MdSyKE1N4iLqUWVpuzI%2F-MdTG1NR3tXy_hqFguu2%2FScreen%20Shot%202021-06-30%20at%202.52.26%20PM.png?alt=media\&token=c0918610-878b-44c0-8fd4-684c77f55e14) #### 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 r**equest 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 ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LZ0_pjgTp_kx4hqTZ3a%2F-MdSyKE1N4iLqUWVpuzI%2F-MdTHNbHyAN2xCdFO9zH%2FScreen%20Shot%202021-06-30%20at%202.58.22%20PM.png?alt=media\&token=ac2cbb43-6d29-401b-b532-9d64220b337f) 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. ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LZ0_pjgTp_kx4hqTZ3a%2F-MdSyKE1N4iLqUWVpuzI%2F-MdTI6n9S-88PdvZL5mM%2FScreen%20Shot%202021-06-30%20at%203.01.40%20PM.png?alt=media\&token=eb66b079-ba77-4cfc-9da1-8fc079958dfc) #### ### Run on Kubernetes Navigate to the OpenHIE/Instant repository. Type the following commands ``` yarn yarn docker:build ``` Next we need to run the images ``` yarn docker:instant init -t k8s santempi -c="" ``` 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) ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LZ0_pjgTp_kx4hqTZ3a%2F-MgHdJdVN7RoqOmkBwI9%2F-MgQdrmlzXeHY6Vv4ljH%2FScreen%20Shot%202021-08-06%20at%209.29.05%20AM.png?alt=media\&token=60c50d51-9a2e-4327-8882-b0aad0e480dc) You can navigate to and be brought to the login screen. * default username is: * default password is: instant101 **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: ``` kubectl get pods ``` 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) ``` kubectl describe pod santedb-66bf68f744-xpsnh ``` The above command will display the details of this pod. At the top of the JSON blob you can see the IP Address. ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LZ0_pjgTp_kx4hqTZ3a%2F-MgHdJdVN7RoqOmkBwI9%2F-MgQgt1WrQQ2iGV0h4zq%2FScreen%20Shot%202021-08-06%20at%209.41.35%20AM.png?alt=media\&token=a51f1a4d-b979-47f4-aca7-1e180afe23c1) Now you can add the IP Address as the **host** for the route. ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LZ0_pjgTp_kx4hqTZ3a%2F-MgHdJdVN7RoqOmkBwI9%2F-MgQhCQ4M17Y91DK7KMh%2FScreen%20Shot%202021-08-06%20at%209.43.35%20AM.png?alt=media\&token=b54e1381-aaca-436e-8890-6b791966aba4) 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. ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LZ0_pjgTp_kx4hqTZ3a%2F-MgHdJdVN7RoqOmkBwI9%2F-MgS-1ukm5iUO8bkpsfn%2FScreen%20Shot%202021-08-06%20at%203.45.44%20PM.png?alt=media\&token=00687cbe-d745-47bd-9015-2d41743e2b58) ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LZ0_pjgTp_kx4hqTZ3a%2F-MgHdJdVN7RoqOmkBwI9%2F-MgS-FrE8K1QmU0ICibK%2FScreen%20Shot%202021-08-06%20at%203.46.15%20PM.png?alt=media\&token=fcf8fca4-d99d-49ae-9509-3bb6444d30c3) ## 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](https://help.santesuite.org/developers/service-apis/openid-connect#discovery-configuration). A quick method to authenticate yourself with: ``` POST http://localhost:8082/auth/oauth2_token HTTP/1.1 Content-Type: application/x-www-form-urlencoded X-SanteDBClient-Claim: PolicyOverride=1;PurposeOfUse=EMERG Host: mpi-test.local:8080 Content-Length: 112 grant_type=password&scope=2.25.3049340304933&username=administrator&password=Mohawk123&client_id=fiddler&client_secret=fiddler ``` ### 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 {% hint style="info" %} 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. {% endhint %} 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](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LZ0_pjgTp_kx4hqTZ3a%2F-MdSyKE1N4iLqUWVpuzI%2F-MdTK3kyUTWOx1eC9UQu%2FScreen%20Shot%202021-06-30%20at%203.10.13%20PM.png?alt=media\&token=f3b20c42-fb8c-4b64-b29e-ce2620dc1b33) #### Congratulations, you have now verified your santedb package within the instant openhim!