What is IPEHR?

The IPEHR (InterPlanetary EHR) project is held to propose an alternative way of storing medical data registries. Patients’ data will be stored in the Filecoin network and will be accessed directly by stakeholders according to their personal access rights. Access rights and documents’ indexes will be stored on a blockchain in a smart contract. Every data subject will have full unalienable control over his data and manage access rights on a personal level.

The project is under active development and will gradually be supplemented.

Key features of the IPEHR solution:

• all data is stored in provider-independent decentralized storage;
• data encryption;
• self-management of user’s access rights;
• data integrity and authenticity are guaranteed by a smart contract.

According to the RFP application the first stage of this project is developed with 7 milestones:

• Development of MH-ORM and structure of storage of medical data
• The functionality of encryption and saving/reading personal data to/from Filecoin
• Access rights management on a blockchain
• BsnGateway. Implementation of OpenEHR API, integration with MH-ORM
• Public data publishing features using the Chainlink network
• Application to manage your own medical data and access
• Testing, documentation, and deployment

Workflow example

The following methods are based on the standard specification of OpenEHR

P.S. For creating a UUID you can use a generator (e.g uuidgenerator)

Hou to create and work with a user

Disclaimer: you have to register a user and must log in under your credentials before doing any actions. We recommend saving all essential information such as userID, tokens, EhrSystem, and the other data in a separate file for easy access to copy-paste it

How to register a user

Precondition: Open swagger

1. Choose Register user method and click Try it out
2. Fill in EhrSystemId (any system name or UUID format). In Request form put your userID (e.g user1), password and click Execute

Result: you see that the user is successfully created. You can use your userID and password to log in

Watch video instruction 📹

Hou to login under the user

Precondition: Open swagger and register under registered user OR use exciting user

1. Choose Login user method and click Try it out
2. Fill in AuthUserId (userID that you got before), EhrSystemId (that you put when register). In Request form put your userID and password that you registered before and click Execute

Result: you've got access and a refresh token which can be used instead password for future actions

Watch video instruction 📹

Hou to refresh JWT token

Precondition: Open swagger and login under registered user

1. Choose Refresh JWT method and click Try it out
2. Fill in AuthUserId (it is your REFRESH token in the format "Bearer XXX" where XXX is your refresh token), AuthUserId (that you are logged in) and EhrSystemId, click Execute

Result: your access and refresh tokens are updated. If you failed it means that you were logged out, try to log in again.

Watch video instruction 📹

How to logout

Precondition: Open swagger and login under registered user

1. Choose Logout User method and click Try it out
2. Fill in AuthUserId (it is your ACCESS token in the format "Bearer XXX" where XXX is your access token), AuthUserId (that you are logged in) and EhrSystemId, click Execute

Result: you are successfully logged out

Watch video instruction 📹

How to create EHR

Create a general EHR

Precondition: Open swagger and login under registered user

1. Choose Create EHR method and click Try it out
2. Fill in Authorization (you Bearer and access token), AuthUserId (your userID), EhrSystemId (any system name or UUID) and Prefer (return=representation) and click Execute

Result: While the request is running, the document is saved to IPFS, the indexes and meta-information about the document are written to a smart contract on the blockchain, and a deal is started to store the document in Filecoin. You will get a requestid in the response header, which can be used to get more information about the request's status.

Watch video instruction 📹

Check if the file is available on the IPFS network

Precondition: Execute Create EHR and Get created EHR by ID steps

1. Copy the CID value from the EhrCreate section
2. Check if the file is available on the IPFS network using the link ipfs.io/ipfs/XXX where XXX is your CID value

Result: The document will be downloaded to your computer, but you will not be able to read the content because it is encrypted

Watch video instruction 📹

Check if the execution of the transaction is available on the goerli.etherscan.io

Precondition: Execute Create EHR and Get created EHR by ID steps

1. Copy the hash of a transaction in sections such as SetEhrDocs or SetDocAccess
2. Check the execution of the transaction using the goerli.etherscan.io explorer

Result: You see the execution of the transaction

Watch video instruction 📹

Check Filecoin document storage transaction is complete

Precondition: Execute Create EHR and Get created EHR by ID steps. Wait until FilecoinStartDeal status change from 'Pending' to 'Success' (usually takes about 24 hours)

1. Copy the dealId
2. Go to filfox.info/en/deal/XXX and paste to the search your dealId instead of XXX

Result: You see file and data stored on filecoin

Watch video instruction 📹

Create EHR with EHR_ID

1. Choose Create EHR with id method and click Try it out
2. Fill in Authorization (you Bearer and access token), AuthUserId (your userID), EhrSystemId (that you paste when registered the user), Prefer (return=representation) and ehr_id (UUID as a user-specified EHR identifier) and click Execute

Result: in the response, you see a created EHR with structured data in JSON format and exact ehr_id that you put before

Watch video instruction 📹

Create EHR with different parameters, such as subject id and id namespace

1. Choose PUT Create EHR method click Try it out
2. Fill in Authorization (your Bearer and access token), AuthUserId (your userID), EhrSystemId (that you paste when registered the user) and specify ehr_id (also UUID format)
3. Change params in the Request field: ** "subject" -> "external_ref" -> "id" -> "value" -> put here id (e.g num123) ** "subject" -> "external_ref" -> "id" -> "namespace" -> put here namespace (e.g testnamespace)
4. Click Execute

Result: You see a created EHR with structured data in JSON format in the response. There are no subject_id and subject_space fields, they can be only requested with GET request

Watch video instruction 📹

How to get EHR with different parameters

Get created EHR by request id

Precondition: Execute Create EHR steps and copy AuthUserId and requestid

1. Choose Get request by ID method
2. Paste AuthUserId and request_id values, fill in Authorization (you Bearer and access token) and click Execute

Result: In the response, you will get additional information about the progress of this request, including the transaction hashes in the blockchain, the file cid in IPFS, and the dealCid - the transaction id in Filecoin

Watch video instruction 📹

Get info on created summary EHR by the subject id

Precondition: Create EHR with subject_id and subject_namespace. Copy params subject_id and subject_namespace to a buffer

1. Choose Get EHR summary by subject id method and click Try it out
2. Paste subject_id, subject_namespace and Authorization (you Bearer and access token), AuthUserId from previously created EHR and click Execute

Result: in the response, you see created before EHR with the requested subject_id and subject_namespace. Here you can find exact EHR without ehr_id

Watch video instruction 📹

Get info on created EHR summary by id

Precondition: EHR was created and ehr_id is copied to a buffer

1. Choose Get EHR summary by summary id method and click Try it out
2. Fill in (or paste) ehr_id, Authorization (you Bearer and access token), AuthUserId (your userID) and EhrSystemId (that you paste when registered the user) field and click Execute

Result: in the response, you see created before EHR which was found with ehr_id

Watch video instruction 📹

Get info on EHR status version by time

Precondition: EHR was created and ehr_id, AuthUserId, Prefer, and time_created are copied to a buffer

1. Choose Get EHR_STATUS version by time method and click Try it out
2. Fill in ehr_id, AuthUserId, Authorization (you Bearer and access token), Prefer, and time_created (or any other time between creation EHR and current time in format "2022-06-22T13:26:39.042+00:00") with copied information and click Execute

Result: in the response, you see the EHR status version by the exact time

Watch video instruction 📹

Getting info on EHR_STATUS by version id

Precondition: EHR was created and make sure that ehr_id, AuthUserId, version_id (look at "ehr_status" -> "value") are copied to a buffer

1. Choose Get EHR_STATUS by version id method and click Try it out
2. Fill in ehr_id, Authorization (you Bearer and access token), AuthUserId (your userID), EhrSystemId and version_id (e.g 8cf1779d-f050-4be3-a671-579bf277f294::openEHRSys.example.com::1 where ::1 is version of EHR) with copied information and click Execute

Result: in the response, you see the EHR status EHR_STATUS by version id (in the example it is ::1 at the end which means requested the first version)

Watch video instruction 📹

How to update EHR status

Precondition: EHR was created and ehr_id, AuthUserId are copied to a buffer

1. Choose Update EHR_STATUS method and click Try it out

2. Fill in Authorization (you Bearer and access token), AuthUserId (your userID) and EhrSystemId (that you paste when registered the user) with copied information

3. Fill in a new ehr_id according to the UUID format

4. Fill in If-Match with current version_id (e.g the current version is 8cf1779d-f050-4be3-a671-579bf277f294::openEHRSys.example.com::1)

5. Fill in Request with a body template (also can find it here):

   { "_type": "EHR_STATUS", "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1", "name": { "value": "EHR Status" }, "uid": { "_type": "OBJECT_VERSION_ID", "value": "8849182c-82ad-4088-a07f-48ead4180515::openEHRSys.example.com::2" }, "subject": { "external_ref": { "id": { "_type": "HIER_OBJECT_ID", "value": "324a4b23-623d-4213-cc1c-23f233b24234" }, "namespace": "DEMOGRAPHIC", "type": "PERSON" } }, "other_details": { "_type": "ITEM_TREE", "archetype_node_id": "at0001", "name": { "value": "Details" }, "items": [] }, "is_modifiable": true, "is_queryable": true }

6. In the body change data (e.g. "is_queryable": false instead of "is_queryable": true) and click Execute

Result: in the response, you see an updated EHR. Now you can find EHR with a new version and in new version, you will see that the changed param has a new value

Watch video instruction 📹

How to work with composition

Create composition

Precondition: EHR was created and ehr_id, AuthUserId, and Prefer (return=representation) are copied to a buffer

1. Choose Create composition method and click Try it out
2. Fill in ehr_id,Authorization (you Bearer and access token), AuthUserId (your userID), EhrSystemId (that you paste when registered the user) and Prefer with copied information
3. In the Request put information (body of JSON) from this file and click Execute

Result: in the response, you see a created composition with a lot of information inside (e.g archetype_node_id, composer, health_care_facility etc)

Watch video instruction 📹

Get composition by version id

Precondition: Composition is created

1. Choose Get composition by version id method and click Try it out
2. Fill in ehr_id, Authorization (you Bearer and access token), AuthUserId (your userID), versioned_object_uid, EhrSystemId (that you paste when registering the user) with copied information Click Execute

Result: in the response, you see composition by version id

Watch video instruction 📹

Update composition by version id

Precondition: EHR was created and ehr_id, AuthUserId, and Prefer (return=representation) are copied to a buffer and Composition is created

1. Choose Update composition by version id method and click Try it out
2. Fill in ehr_id, Authorization (you Bearer and access token), AuthUserId (your userID), versioned_object_uid, EhrSystemId (that you paste when registered the user), If-Match and Prefer with copied information
3. In the Request change information and click Execute

Result: in the response, you see an updated composition

Watch video instruction 📹

Delete composition by version id

Precondition: EHR was created and ehr_id, AuthUserId, and Prefer (return=representation) are copied to a buffer and Composition is created

1. Choose Delete composition by version id method and click Try it out
2. Fill in ehr_id, Authorization (you Bearer and access token), AuthUserId (your userID), preceding_version_uid, EhrSystemId (that you paste when registered the user) with copied information
3. Click Execute

Result: composition by version id is deleted. You can additionally check it by trying to Get composition by id

Watch video instruction 📹

Execute ad-hoc (non-stored) AQL query

Execute AQL query

1. Choose Execute ad-hoc (non-stored) AQL query method and click Try it out
2. Fill in Authorization (you Bearer and access token), AuthUserId (your userID)
3. Fill in Request with AQL request

   { "q": "SELECT c/uid/value, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic FROM EHR e[ehr_id/value=$ehr_id] CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.health_summary.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v2] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp", "offset": 0, "fetch": 10, "query_parameters": { "ehr_id": "07fa4e05-df30-4a2b-9612-6bf1d28ff80c", "systolic_bp": 140 } }

4. Click Execute Result: In the response, you see a requested information

Watch video instruction 📹

How to set and get access to the document

How to get access to a document

Precondition: Open swagger and login under registered user

1. Choose Get a document access list method and click Try it out
2. Fill in Authorization (you Bearer and access token), AuthUserId (your userID), and click Execute

Result: in the response you see list of documents

Watch video instruction 📹

How to set user access to the document

Precondition: Open swagger and login under registered user

1. Choose Set user access to the document method and click Try it out
2. Fill in Authorization (you Bearer and access token), AuthUserId (your userID). In Request fill in the access level (e.g owner, admin, read, noAccess), cid (paste from created ehr) and userID (user that you want to set access, then click Execute

Result: the request to change the level of access to the document was successfully created

Watch video instruction 📹