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 createOrModify
method on the PatientApi
object. This method takes one parameter: the Patient object.
const createdPatient = await api.patientApi.createOrModify(
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',
}),
)
createdPatient
{
"id": "6b1673bc-309d-44da-9aa0-47f59a9d79aa",
"rev": "1-8eb291abca109d098cff6153a8c1c95b",
"created": 1700058672503,
"modified": 1700058672503,
"author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
"responsible": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
"firstName": "Hubert",
"lastName": "Farnsworth",
"languages": [],
"active": true,
"dateOfBirth": 28410409,
"profession": "CEO/Owner of Planet Express, Lecturer at Mars University",
"nationality": "American",
"parameters": {},
"identifiers": [],
"labels": {},
"codes": {},
"notes": [],
"names": [
{
"lastName": "Farnsworth",
"firstNames": [
"Hubert",
"J"
],
"prefix": [],
"suffix": [],
"use": "official"
},
{
"firstNames": [
"Professor"
],
"prefix": [],
"suffix": [],
"use": "nickname"
}
],
"addresses": [],
"gender": "male",
"birthSex": "male",
"mergedIds": {},
"deactivationReason": "none",
"personalStatus": "unknown",
"partnerships": [],
"patientHealthCareParties": [],
"patientProfessions": [],
"properties": {},
"systemMetaData": {
"hcPartyKeys": {},
"privateKeyShamirPartitions": {},
"secretForeignKeys": [],
"cryptedForeignKeys": {},
"delegations": {},
"encryptionKeys": {},
"aesExchangeKeys": {},
"transferKeys": {},
"securityMetadata": {
"secureDelegations": {},
"keysEquivalences": {}
},
"encryptedSelf": "OvKHyVKXEhKmH8ZscWbOptX6ICgLRtRD7d5T0uFkwhI=",
"publicKeysForOaepWithSha256": [],
"tags": {}
}
}
How to update a patient ?​
To update a patient, we can use the createOrModify
method on the PatientApi
object. This method takes one parameter: the Patient object.
const updatedPatient = await api.patientApi.createOrModify(
new Patient({
...createdPatient,
modified: undefined,
note: 'Good news everyone!',
}),
)
updatedPatient
{
"id": "6b1673bc-309d-44da-9aa0-47f59a9d79aa",
"rev": "2-fecb96f0de3d1bc1eb74db5dc1c4f00e",
"created": 1700058672503,
"modified": 1700058672566,
"author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
"responsible": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
"firstName": "Hubert",
"lastName": "Farnsworth",
"languages": [],
"active": true,
"dateOfBirth": 28410409,
"profession": "CEO/Owner of Planet Express, Lecturer at Mars University",
"note": "Good news everyone!",
"nationality": "American",
"parameters": {},
"identifiers": [],
"labels": {},
"codes": {},
"notes": [],
"names": [
{
"lastName": "Farnsworth",
"firstNames": [
"Hubert",
"J"
],
"prefix": [],
"suffix": [],
"use": "official"
},
{
"firstNames": [
"Professor"
],
"prefix": [],
"suffix": [],
"use": "nickname"
}
],
"addresses": [],
"gender": "male",
"birthSex": "male",
"mergedIds": {},
"deactivationReason": "none",
"personalStatus": "unknown",
"partnerships": [],
"patientHealthCareParties": [],
"patientProfessions": [],
"properties": {},
"systemMetaData": {
"hcPartyKeys": {},
"privateKeyShamirPartitions": {},
"secretForeignKeys": [],
"cryptedForeignKeys": {},
"delegations": {},
"encryptionKeys": {},
"aesExchangeKeys": {},
"transferKeys": {},
"securityMetadata": {
"secureDelegations": {},
"keysEquivalences": {}
},
"encryptedSelf": "hAr5R8OQPyAOab95LlAddPb0Eoo3aOB3BpVUAlDaV0sDfCPymVUjKxrnCcmPdAbZ",
"publicKeysForOaepWithSha256": [],
"tags": {}
}
}
How to get a patient ?​
To get a patient, we can use the get
method on the PatientApi
object. This method takes one parameter: the patient id.
const patient = await api.patientApi.get(updatedPatient.id)
patient
{
"id": "6b1673bc-309d-44da-9aa0-47f59a9d79aa",
"rev": "2-fecb96f0de3d1bc1eb74db5dc1c4f00e",
"created": 1700058672503,
"modified": 1700058672566,
"author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
"responsible": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
"firstName": "Hubert",
"lastName": "Farnsworth",
"languages": [],
"active": true,
"dateOfBirth": 28410409,
"profession": "CEO/Owner of Planet Express, Lecturer at Mars University",
"note": "Good news everyone!",
"nationality": "American",
"parameters": {},
"identifiers": [],
"labels": {},
"codes": {},
"notes": [],
"names": [
{
"lastName": "Farnsworth",
"firstNames": [
"Hubert",
"J"
],
"prefix": [],
"suffix": [],
"use": "official"
},
{
"firstNames": [
"Professor"
],
"prefix": [],
"suffix": [],
"use": "nickname"
}
],
"addresses": [],
"gender": "male",
"birthSex": "male",
"mergedIds": {},
"deactivationReason": "none",
"personalStatus": "unknown",
"partnerships": [],
"patientHealthCareParties": [],
"patientProfessions": [],
"properties": {},
"systemMetaData": {
"hcPartyKeys": {},
"privateKeyShamirPartitions": {},
"secretForeignKeys": [],
"cryptedForeignKeys": {},
"delegations": {},
"encryptionKeys": {},
"aesExchangeKeys": {},
"transferKeys": {},
"securityMetadata": {
"secureDelegations": {},
"keysEquivalences": {}
},
"encryptedSelf": "hAr5R8OQPyAOab95LlAddPb0Eoo3aOB3BpVUAlDaV0sDfCPymVUjKxrnCcmPdAbZ",
"publicKeysForOaepWithSha256": [],
"tags": {}
}
}
How to delete a patient ?​
To delete a patient, we can use the delete
method on the PatientApi
object. This method takes one parameter: the patient id.
const deletedPatientId = await api.patientApi.delete(patient.id!)
deletedPatientId
6b1673bc-309d-44da-9aa0-47f59a9d79aa
How to filter patients ?​
To filter patients, we can use the filterBy
method on the PatientApi
object. This method takes one parameter: the filter.
const filter = await new PatientFilter(api)
.forDataOwner(loggedUser.healthcarePartyId)
.dateOfBirthBetween(28000101, 29000101)
.build()
const patients = await api.patientApi.filterBy(filter)
patients
{
"rows": [
{
"id": "6b1673bc-309d-44da-9aa0-47f59a9d79aa",
"rev": "2-fecb96f0de3d1bc1eb74db5dc1c4f00e",
"created": 1700058672503,
"modified": 1700058672566,
"author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
"responsible": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
"firstName": "Hubert",
"lastName": "Farnsworth",
"languages": [],
"active": true,
"dateOfBirth": 28410409,
"profession": "CEO/Owner of Planet Express, Lecturer at Mars University",
"nationality": "American",
"parameters": {},
"identifiers": [],
"labels": {},
"codes": {},
"notes": [],
"names": [
{
"lastName": "Farnsworth",
"firstNames": [
"Hubert",
"J"
],
"prefix": [],
"suffix": [],
"use": "official"
},
{
"firstNames": [
"Professor"
],
"prefix": [],
"suffix": [],
"use": "nickname"
}
],
"addresses": [],
"gender": "male",
"birthSex": "male",
"mergedIds": {},
"deactivationReason": "none",
"personalStatus": "unknown",
"partnerships": [],
"patientHealthCareParties": [],
"patientProfessions": [],
"properties": {},
"systemMetaData": {
"hcPartyKeys": {},
"privateKeyShamirPartitions": {},
"secretForeignKeys": [],
"cryptedForeignKeys": {},
"delegations": {},
"encryptionKeys": {},
"aesExchangeKeys": {},
"transferKeys": {},
"securityMetadata": {
"secureDelegations": {},
"keysEquivalences": {}
},
"encryptedSelf": "hAr5R8OQPyAOab95LlAddPb0Eoo3aOB3BpVUAlDaV0sDfCPymVUjKxrnCcmPdAbZ",
"publicKeysForOaepWithSha256": [],
"tags": {}
}
}
]
}
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:
const patientFilter = new PatientFilter(api)
.forDataOwner(loggedUser.healthcarePartyId!)
.dateOfBirthBetween(28000101, 29000101)
.build()
patientFilter
{}
The resulting filter object will create a filter that allows us to get all Patient
that satisfy all the following requirements:
- The
Patient
can be accessed by the logged user healthcare party - The
Patient
gender ismale
- 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 matchBy
method on the PatientApi
. This method takes one parameter: the filter object.
const filterForMatch = await new PatientFilter(api)
.forDataOwner(loggedUser.healthcarePartyId!)
.dateOfBirthBetween(28000101, 29000101)
.build()
const patientIds = await api.patientApi.matchBy(filterForMatch)
patientIds
[
"6b1673bc-309d-44da-9aa0-47f59a9d79aa"
]
How to get and modify your information as a patient​
If you are building a "patient application", where patients can join by invitation from an Healthcare professional 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 Healthcare professional 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 getAndTryDecrypt
and
modifyPotentiallyEncryptedPatient
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.
You can see an example on how to use these methods in the tutorial Inviting an existing patient to become a user.