Repository files navigation

Electronic medical records and data craves the need for innovation. The way patient health records are stored and secured today do not showcase our technological advancement in this area in the past decade, and hospitals continue to use age-old data management systems for patient data. This is partly due to strict regulations around privacy and security of medical data, which has stifled the use of latest technology to make medical data management more transparent and useful for both patients as well as doctors.

This code pattern showcases a medical data/access management platform built using blockchain. The application shows the platform from the point of view of 4 stakeholders -

• The solution admin is the admin of a conglomerate of hospitals, and has the highest of access levels in the hierarchy. They have the ability to onboard a new organization (hospital) to the conglomerate and assign/de-assign hospital admins on their dashboard.
• The organization (hospital) admin is the admin of a particular hospital which is part of the conglomerate/solution. They have the ability to onboard new users with the role of either patient or doctor, or remove a user.
• The doctor is a user in the organization with the appropriate role and has the ability to upload documents for their patients and download/view documents of their patients to which they have been granted access.
• The patient is a user in the organization with the appropriate role and has the ability to upload documents on their own, view them, view the document access logs and also manage access to their documents on their dashboard.

This code pattern is for developers who want to integrate with the Blockchain Solution Manager, Blockchain Document Store and the IBM Blockchain Platform. When you have completed it, you will understand how to:

• Connect the Blockchain Solution Manager and Blockchain Document Store with the IBM Blockchain Platform.
• Create a VueJS web app that has multiple dashboards on a single page application, which can communicate in realtime with each other.
• Create a NodeJS server that is deployed to Kubernetes on IBM Cloud, and connected with a Redis database deployed on the IBM Cloud.
• Store and retrieve data from a Redis datastore for persistent storage through a NodeJS server.
• Make REST calls to an external service.
• Use JWT (JSON web token) tokens for user management.

1. All the stakeholders of the application (solution admin, hospital admin, doctor and patient) begin the user flow by logging into their respective dashboards.
2. Clicking the login button leads to the login portal of the Blockchain Solution Manager, hosted on the IBM cloud.
3. The login portal uses OpenAPI Connect and allows the user the login through any onboarded identity provider (in our example, we have on-boarded IBMID ad GoogleID). Successful authentication leads to the JWT credentials for the user.

4. The solution admin flow begins at the admin component, and requires the user to authenticate themselves through the login flow described above.
5. After successful authentication, the user can access the solution admin dashboard. They are able to view the solution, and add/remove hospitals from the solution using the Admin API's.
6. All the admin API's connect with the Blockchain Solution Manager through REST to process the user queries.
7. The Blockchain Solution Manager connects with the IBM Blockchain Platform and updates the ledger appropriately.

8. The hospital admin flow begins at the organization component, and requires the user to authenticate themselves through the login flow described above.
9. After successful authentication, the user can access the hospital admin dashboard. They are able to add/remove any user in their respective hospital with the on-boarded roles (patient/doctor in our case) using the organization API's.
10. All the organization API's connect with the Blockchain Solution Manager through REST to process the user queries.
11. The Blockchain Solution Manager connects with the IBM Blockchain Platform and updates the ledger appropriately.

12. The doctor flow begins at the doctor component, and requires the user to authenticate themselves through the login flow described above.
13. After successful authentication, the user can access the doctor dashboard. They are able to upload a medical record for a patient who is part of their hospital and download any medical record associated with a patient to which they have access to, using the Doctor API's. The ACL's for all the patient documents is application level and is maintained through the Document ACL flow described below.
14. All the doctor API's connect with the Blockchain Document Store through REST to process the user queries.
15. The Blockchain Document Store connects with the IBM Blockchain Platform and updates the ledger appropriately.

16. The patient flow begins at the patient component, and requires the user to authenticate themselves through the login flow described above.
17. After successful authentication, the user can access the patient dashboard. They are able to upload a medical record for themselves, download any of their medical records, view the access logs of their documents, and view/manage permissions to their documents, using the Patient API's. The ACL's for all the documents is application level and is maintained through the document ACL flow described below.
18. All the patient API's connect with the Blockchain Document Store through REST to process the user queries.
19. The Blockchain Document Store connects with the IBM Blockchain Platform and updates the ledger appropriately.

20. The doctor and patient component are connected with the Redis API's that invoke methods to manage the document level access control across hospitals.
21. The Redis API's talk to a NodeJS server deployed in a Docker container in a Kubernetes cluster on the IBM Cloud.
22. The server talks to two Redis databases which hold the access-per-document and access-per-user permissions.

• IBM Blockchain Platform gives you total control of your blockchain network with a user interface that can simplify and accelerate your journey to deploy and manage blockchain components on the IBM Cloud Kubernetes Service.
• IBM Blockchain Solution Manager: The Blockchain Document Store service includes the IBM Blockchain Solution Manager component, which enables organizations to easily manage blockchain networks, solutions, services, and users.
• IBM Blockchain Document Store is a comprehensive document management service for IBM Blockchain Platform business networks.
• IBM Cloud Kubernetes Service creates a cluster of compute hosts and deploys highly available containers. A Kubernetes cluster lets you securely manage the resources that you need to quickly deploy, update, and scale applications.
• IBM Cloud Databases for Redis Service: Redis is an open source, in-memory data structure store, used as a database, cache and message broker. It supports data structures such as strings, hashes, lists, sets, sorted sets with range queries, bitmaps, hyperloglogs and geospatial indexes with radius queries.

• Nodejs is an open-source, cross-platform JavaScript run-time environment that executes JavaScript code server-side.
• Vuejs is a progressive framework for building user interfaces.
• Redis is an open source (BSD licensed), in-memory data structure store, used as a database, cache and message broker.
• Bootstrap is a free and open-source front-end Web framework. It contains HTML and CSS-based design templates for typography, forms, buttons, navigation and other interface components, as well as optional JavaScript extensions.
• Docker is a computer program that performs operating-system-level virtualization, also known as Containerization.

We find that Blockchain can be finicky when it comes to installing Node. We want to share thisStackOverflow response - because many times the errors you see with Compose are derived in having installed either the wrong Node version or took an approach that is not supported by Compose:

• IBM Cloud account
• Docker - latest
• Docker Compose - latest
• NPM - latest
• nvm - latest
• Node.js - Node v8.9.x
• Git client - latest

1. Set up your machine
2. Create IBM cloud services
3. Create a solution
4. Clone the repository
5. Modify the configuration files
6. Run the application

Install the following dependencies -

• Docker: Go to the Docker website and download the installer. After installation, run Docker.
• git: Installgit which is a free and open source distributed version control system.

• Create theIBM Cloud Kubernetes Service. You can find the service in theCatalog. For this code pattern, we can use theFree cluster, and give it a name. Note, that the IBM Cloud allows one instance of a free cluster and expires after 30 days.

• Create two instances ofDatabases for Redis Service. You can find the service in theCatalog.

Note: You can use just one instance of Redis as well. Modify the code in the server repository to allow for this.

• Create theIBM Blockchain Service. You can find the service in theCatalog.

• Create theBlockchain document store andBlockchain solution manager services. These services are not currently available publicly on theIBM cloud catalog. You can reach out toRak-Joon Choi (rak-joon.choi@us.ibm.com) to provision these services for you. Follow the servicedocumentation to connect theBlockchain document store to theBlockchain service.

• After configuring your services in the previous step, we now move on to creating a solution using our custom swagger url for theblockchain solution manager service. Go to thePatch endpoint (/v1/solutions) underSolution and authorize using the api by going to the/v1/logins url in a new tab, logging in asAdministrator, and getting the JWT. Add the token prepended bybearer such that it looks likebearer <JWT>. After authorization, click ontry it out to execute the api, and paste the following JSON in theon-boarding section. Give the namemedrec_demo to the solution.

{  "onboardingdata": {    "solution": {      "id": "medrec_demo",      "name": "demo for medrec pattern"    },    "roles": [      {        "id": "role_patient",        "name": "Patient",        "solutionId": "medrec_demo",        "isBlockchainRole": true      },      {        "id": "role_doctor",        "name": "Doctor",        "solutionId": "medrec_demo",        "isBlockchainRole": true      }    ]  }}

• After creating the solution successfully, add yourself as the admin of the solution. Go to thePost endpoint (/v1/solutions/{solutionId}/administrators) underSolution and authorize using the api by going to the/v1/logins url in a new tab, logging in asAdministrator, and getting the JWT. Add the token prepended bybearer such that it looks likebearer <JWT>. After authorization, click ontry it out to execute the api, and type your email id undersolutionAdministrators in the JSON object. Providemedrec_demo as thesolutionId.

git clone https://github.com/IBM/Medical-Blockchain.gitcd Medical-Blockchain

• Modify the redis config file:
  • Go to the previously provisioned redis services on IBM Cloud.
  • Click onService credentials.
  • Click onNew credential button.
  • Once the new credentials are created, click onview credentials.
  • From the JSON object, extract the URI fromconnection.rediss.composed[0].
  • From the JSON object, extract the certificate fromconnection.rediss.certificate.certificate_base64.
  • Navigate to theserver/config.json file in the cloned repository.
  • Replace the URI and certificate values in the marked places.
  • Repeat the steps for the second provisioned service, and enter it in the second spot in the config file.

• Modify the blockchain config file:
  • Go to the/v1/logins url for your blockchain document store service.
  • Login as administrator.
  • Extract theiss field from the decoded JWT and remove/onboarding string from it.
  • Navigate to thesrc/secrets/config.json file in the cloned repository.
  • Replace theiss field with the extracted value above.
  • Replace theblockchain_channel field with the name of the channel provided during connecting the blockchain service to the document store.

• Running the application locally:
  • To run the application on the local system, execute therun-application.sh file.
  • Go tolocalhost:8080 to see the running application.

• Running the application on kubernetes:
  • Navigate to server directory -cd server.
  • Build the docker image for the server -docker build -t <DOCKERHUB_USERNAME>/medrec-server .
  • Replace the image name inmanifest.yml, where indicated.
  • Apply the manifest to the previously provisioned kubernetes cluster.
  • Navigate to/src/apis/RedisApi.js and replace thebaseURL value with the Kubernetes load balancer IP.
  • Build and run the Vue application by executing the below in the repository home.
  • Go tolocalhost:8080 to see the running application.

docker build -t medrec-vue .docker run -d --restart always --name medrec-vue -p 8080:8080 medrec-vue

Note: You can also deploy the Vue App to Kubernetes, by modifying the manifest.yml to support two pods.

This code pattern is licensed under the Apache Software License, Version 2. Separate third-party code objects invoked within this code pattern are licensed by their respective providers pursuant to their own separate licenses. Contributions are subject to theDeveloper Certificate of Origin, Version 1.1 (DCO) and theApache Software License, Version 2.

Apache Software License (ASL) FAQ