Skip to main content

Handling patients

In this section, we will learn how to manage patients. Patient is a class that represents a patient in the system. It contains all the information about the patient.

How to create a patient?

To create a patient, we can use the createOrModifyPatient method on the PatientApi object. This method takes one parameter: the Patient object.

const createdPatient = await api.patientApi.createOrModifyPatient(
new Patient({
firstName: 'Hubert',
lastName: 'Farnsworth',
dateOfBirth: 28410409,
birthSex: 'male',
gender: 'male',
profession: 'CEO/Owner of Planet Express, Lecturer at Mars University',
names: [
new PersonName({
firstNames: ['Hubert', 'J'],
lastName: 'Farnsworth',
use: 'official',
}),
new PersonName({
firstNames: ['Professor'],
use: 'nickname',
}),
],
nationality: 'American',
}),
)
Output
{
"id": "aff58060-8802-4f1a-91a6-e8bb9a343544",
"identifiers": [],
"labels": {},
"codes": {},
"names": [
{
"firstNames": [
"Hubert",
"J"
],
"prefix": [],
"suffix": [],
"lastName": "Farnsworth",
"use": "official"
},
{
"firstNames": [
"Professor"
],
"prefix": [],
"suffix": [],
"use": "nickname"
}
],
"languages": [],
"addresses": [],
"mergedIds": {},
"active": true,
"deactivationReason": "none",
"partnerships": [],
"patientHealthCareParties": [],
"patientProfessions": [],
"parameters": {},
"properties": {},
"rev": "1-26940e83585225c4a919e8dac2241e90",
"created": 1664530613307,
"modified": 1664530613307,
"author": "b36fa6cb-d7a8-40f0-bcf6-af6ce0decb78",
"responsible": "ab623d88-baed-40b9-91b7-ab26e9a08db5",
"firstName": "Hubert",
"lastName": "Farnsworth",
"gender": "male",
"birthSex": "male",
"personalStatus": "unknown",
"dateOfBirth": 28410409,
"profession": "CEO/Owner of Planet Express, Lecturer at Mars University",
"nationality": "American",
"systemMetaData": {
"hcPartyKeys": {},
"privateKeyShamirPartitions": {},
"secretForeignKeys": [],
"cryptedForeignKeys": {},
"delegations": {
"ab623d88-baed-40b9-91b7-ab26e9a08db5": {}
},
"encryptionKeys": {
"ab623d88-baed-40b9-91b7-ab26e9a08db5": {}
},
"aesExchangeKeys": {},
"transferKeys": {}
}
}

How to update a patient?

To update a patient, we can use the createOrModifyPatient method on the PatientApi object. This method takes one parameter: the Patient object.

const updatedPatient = await api.patientApi.createOrModifyPatient({
...createdPatient,
modified: undefined,
note: 'Good news everyone!',
})
Output
{
"id": "aff58060-8802-4f1a-91a6-e8bb9a343544",
"identifiers": [],
"labels": {},
"codes": {},
"names": [
{
"firstNames": [
"Hubert",
"J"
],
"prefix": [],
"suffix": [],
"lastName": "Farnsworth",
"use": "official"
},
{
"firstNames": [
"Professor"
],
"prefix": [],
"suffix": [],
"use": "nickname"
}
],
"languages": [],
"addresses": [],
"mergedIds": {},
"active": true,
"deactivationReason": "none",
"partnerships": [],
"patientHealthCareParties": [],
"patientProfessions": [],
"parameters": {},
"properties": {},
"rev": "2-9da777d089dc3a159d76ab29fff2acd2",
"created": 1664530613307,
"modified": 1664530613678,
"author": "b36fa6cb-d7a8-40f0-bcf6-af6ce0decb78",
"responsible": "ab623d88-baed-40b9-91b7-ab26e9a08db5",
"firstName": "Hubert",
"lastName": "Farnsworth",
"gender": "male",
"birthSex": "male",
"personalStatus": "unknown",
"dateOfBirth": 28410409,
"profession": "CEO/Owner of Planet Express, Lecturer at Mars University",
"note": "Good news everyone!",
"nationality": "American",
"systemMetaData": {
"hcPartyKeys": {},
"privateKeyShamirPartitions": {},
"secretForeignKeys": [],
"cryptedForeignKeys": {},
"delegations": {
"ab623d88-baed-40b9-91b7-ab26e9a08db5": {}
},
"encryptionKeys": {
"ab623d88-baed-40b9-91b7-ab26e9a08db5": {}
},
"aesExchangeKeys": {},
"transferKeys": {}
}
}

How to get a patient?

To get a patient, we can use the getPatient method on the PatientApi object. This method takes one parameter: the patient id.

const patient = await api.patientApi.getPatient(updatedPatient.id!)
Output
{
"id": "aff58060-8802-4f1a-91a6-e8bb9a343544",
"identifiers": [],
"labels": {},
"codes": {},
"names": [
{
"firstNames": [
"Hubert",
"J"
],
"prefix": [],
"suffix": [],
"lastName": "Farnsworth",
"use": "official"
},
{
"firstNames": [
"Professor"
],
"prefix": [],
"suffix": [],
"use": "nickname"
}
],
"languages": [],
"addresses": [],
"mergedIds": {},
"active": true,
"deactivationReason": "none",
"partnerships": [],
"patientHealthCareParties": [],
"patientProfessions": [],
"parameters": {},
"properties": {},
"rev": "2-9da777d089dc3a159d76ab29fff2acd2",
"created": 1664530613307,
"modified": 1664530613678,
"author": "b36fa6cb-d7a8-40f0-bcf6-af6ce0decb78",
"responsible": "ab623d88-baed-40b9-91b7-ab26e9a08db5",
"firstName": "Hubert",
"lastName": "Farnsworth",
"gender": "male",
"birthSex": "male",
"personalStatus": "unknown",
"dateOfBirth": 28410409,
"profession": "CEO/Owner of Planet Express, Lecturer at Mars University",
"note": "Good news everyone!",
"nationality": "American",
"systemMetaData": {
"hcPartyKeys": {},
"privateKeyShamirPartitions": {},
"secretForeignKeys": [],
"cryptedForeignKeys": {},
"delegations": {
"ab623d88-baed-40b9-91b7-ab26e9a08db5": {}
},
"encryptionKeys": {
"ab623d88-baed-40b9-91b7-ab26e9a08db5": {}
},
"aesExchangeKeys": {},
"transferKeys": {}
}
}

How to delete a patient?

To delete a patient, we can use the deletePatient method on the PatientApi object. This method takes one parameter: the patient id.

const deletedPatient = await api.patientApi.deletePatient(patient.id!)
Output
// TODO Add output

How to filter patients?

To filter patients, we can use the filterPatients method on the PatientApi object. This method takes one parameter: the filter.

const filter = await new PatientFilter()
.forDataOwner(loggedUser.healthcarePartyId!)

.dateOfBirthBetween(28000101, 29000101)
.build()

const patients = await api.patientApi.filterPatients(filter)
Output

Filter builder

To create a filter, we can use the PatientFilter builder methods. This builder allows us to create complex filter object.

In the example above, we created the filter this way:

new PatientFilter()
.forDataOwner(loggedUser.healthcarePartyId!)

.dateOfBirthBetween(28000101, 29000101)
.build()

The resulting filter object will create a filter that allows us to get all Patient that satisfy all the following requirements:

  • The Patient is owned by the logged user healthcare party
  • The Patient gender is male
  • The Patient is born between January 1st 2800 and January 1st 2900

How to get a list of Patient ids?

In some circumstances, you might want to get a list of Patient ids instead of the Patient entities themselves. To do so, you can use the matchPatients method on the PatientApi. This method takes one parameter: the filter object.

const filterForMatch = await new PatientFilter()
.forDataOwner(loggedUser.healthcarePartyId!)

.dateOfBirthBetween(28000101, 29000101)
.build()

const patientIds = await api.patientApi.matchPatients(filterForMatch)
Output
["aff58060-8802-4f1a-91a6-e8bb9a343544"]

How to get and modify your information as a patient

note

The features described in this section are currently available only in the dart sdk.

If you are building a "patient application", where patients can join by invitation from an HCP you may incur in a problem with the decryption of the data of the Patient entity for the user of the application.

This is because when the HCP invites the patient to the application he can't share any existing data with him until the patient logs in for the first time and creates a public key. Therefore, the patient will not be able to decrypt any data, including his administrative information stored on the patient entity, and for this reason methods like getPatient will fail.

However, you can still access and modify any unencrypted data using the methods getPatientAndTryDecrypt and modifyEncryptedPatient of the PatientApi. The method getPatientAndTryDecrypt returns a PotentiallyEncryptedPatient, which is either a normal Patient if the encrypted data could be decrypted, or an EncryptedPatient if only the unencrypted data is available. The method modifyEncryptedPatient instead takes in input an EncryptedPatient and allows you to modify any non-encrypted field of the Patient entity.