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 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: GenderEnum.MALE,
    gender: GenderEnum.MALE,
    profession: 'CEO/Owner of Planet Express, Lecturer at Mars University',
    names: [
      new HumanName({
        given: ['Hubert', 'J'],
        family: 'Farnsworth',
        use: HumanNameUseEnum.OFFICIAL,
      }),
      new HumanName({
        given: ['Professor'],
        use: HumanNameUseEnum.NICKNAME,
      }),
    ],
    nationality: 'American',
  }),
)
createdPatient
{
  "id": "8255caa9-0bb3-4a30-a58c-f658cfb9dc39",
  "rev": "1-48805c7da607a65f3f9254e5e81bf77e",
  "identifiers": [],
  "created": 1700058627586,
  "modified": 1700058627586,
  "author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
  "responsible": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
  "tags": {},
  "codes": {},
  "names": [
    {
      "family": "Farnsworth",
      "given": [
        "Hubert",
        "J"
      ],
      "prefix": [],
      "suffix": [],
      "use": "official"
    },
    {
      "given": [
        "Professor"
      ],
      "prefix": [],
      "suffix": [],
      "use": "nickname"
    }
  ],
  "languages": [],
  "addresses": [],
  "gender": "male",
  "birthSex": "male",
  "mergedIds": [],
  "active": true,
  "deactivationReason": "none",
  "personalStatus": "unknown",
  "dateOfBirth": 28410409,
  "profession": "CEO/Owner of Planet Express, Lecturer at Mars University",
  "notes": [],
  "nationality": "American",
  "relatives": [],
  "patientPractitioners": [],
  "patientProfessions": [],
  "properties": {},
  "systemMetaData": {
    "hcPartyKeys": {},
    "privateKeyShamirPartitions": {},
    "secretForeignKeys": [],
    "cryptedForeignKeys": {},
    "delegations": {},
    "encryptionKeys": {},
    "aesExchangeKeys": {},
    "transferKeys": {},
    "securityMetadata": {
      "secureDelegations": {},
      "keysEquivalences": {}
    },
    "encryptedSelf": "PPuBv6yKGUO/bX+WTxpsBM4N9yv5BxifjSO1n1DBoJw=",
    "publicKeysForOaepWithSha256": [],
    "tags": {}
  },
  "firstName": "Hubert",
  "lastName": "Farnsworth"
}

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,
    notes: [
      new Annotation({
        markdown: mapOf({ en: 'Good news everyone!' }),
      }),
    ],
  }),
)
updatedPatient
{
  "id": "8255caa9-0bb3-4a30-a58c-f658cfb9dc39",
  "rev": "2-ddc878449bd4cd2fb7af49a23b4d5804",
  "identifiers": [],
  "created": 1700058627586,
  "modified": 1700058627645,
  "author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
  "responsible": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
  "tags": {},
  "codes": {},
  "names": [
    {
      "family": "Farnsworth",
      "given": [
        "Hubert",
        "J"
      ],
      "prefix": [],
      "suffix": [],
      "use": "official"
    },
    {
      "given": [
        "Professor"
      ],
      "prefix": [],
      "suffix": [],
      "use": "nickname"
    }
  ],
  "languages": [],
  "addresses": [],
  "gender": "male",
  "birthSex": "male",
  "mergedIds": [],
  "active": true,
  "deactivationReason": "none",
  "personalStatus": "unknown",
  "dateOfBirth": 28410409,
  "profession": "CEO/Owner of Planet Express, Lecturer at Mars University",
  "notes": [
    {
      "id": "3008f72c-3a06-46b6-84fc-205fee901c31",
      "tags": {},
      "markdown": {},
      "encryptedSelf": "xLPoepdC/4rsg12yZSTi3DlqHQxelcIhSIHgCtH3HfWZ3emCgFin2X1xt4slTp7kPsMIFt3AJRlR7s09KNtsPA=="
    }
  ],
  "nationality": "American",
  "relatives": [],
  "patientPractitioners": [],
  "patientProfessions": [],
  "properties": {},
  "systemMetaData": {
    "hcPartyKeys": {},
    "privateKeyShamirPartitions": {},
    "secretForeignKeys": [],
    "cryptedForeignKeys": {},
    "delegations": {},
    "encryptionKeys": {},
    "aesExchangeKeys": {},
    "transferKeys": {},
    "securityMetadata": {
      "secureDelegations": {},
      "keysEquivalences": {}
    },
    "encryptedSelf": "r17b+KCZbf/ZVT6WS6eO+remfJybbhBzhbktJ+HgZnc=",
    "publicKeysForOaepWithSha256": [],
    "tags": {}
  },
  "firstName": "Hubert",
  "lastName": "Farnsworth"
}

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": "8255caa9-0bb3-4a30-a58c-f658cfb9dc39",
  "rev": "2-ddc878449bd4cd2fb7af49a23b4d5804",
  "identifiers": [],
  "created": 1700058627586,
  "modified": 1700058627645,
  "author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
  "responsible": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
  "tags": {},
  "codes": {},
  "names": [
    {
      "family": "Farnsworth",
      "given": [
        "Hubert",
        "J"
      ],
      "prefix": [],
      "suffix": [],
      "use": "official"
    },
    {
      "given": [
        "Professor"
      ],
      "prefix": [],
      "suffix": [],
      "use": "nickname"
    }
  ],
  "languages": [],
  "addresses": [],
  "gender": "male",
  "birthSex": "male",
  "mergedIds": [],
  "active": true,
  "deactivationReason": "none",
  "personalStatus": "unknown",
  "dateOfBirth": 28410409,
  "profession": "CEO/Owner of Planet Express, Lecturer at Mars University",
  "notes": [
    {
      "id": "3008f72c-3a06-46b6-84fc-205fee901c31",
      "tags": {},
      "markdown": {},
      "encryptedSelf": "xLPoepdC/4rsg12yZSTi3DlqHQxelcIhSIHgCtH3HfWZ3emCgFin2X1xt4slTp7kPsMIFt3AJRlR7s09KNtsPA=="
    }
  ],
  "nationality": "American",
  "relatives": [],
  "patientPractitioners": [],
  "patientProfessions": [],
  "properties": {},
  "systemMetaData": {
    "hcPartyKeys": {},
    "privateKeyShamirPartitions": {},
    "secretForeignKeys": [],
    "cryptedForeignKeys": {},
    "delegations": {},
    "encryptionKeys": {},
    "aesExchangeKeys": {},
    "transferKeys": {},
    "securityMetadata": {
      "secureDelegations": {},
      "keysEquivalences": {}
    },
    "encryptedSelf": "r17b+KCZbf/ZVT6WS6eO+remfJybbhBzhbktJ+HgZnc=",
    "publicKeysForOaepWithSha256": [],
    "tags": {}
  },
  "firstName": "Hubert",
  "lastName": "Farnsworth"
}

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
8255caa9-0bb3-4a30-a58c-f658cfb9dc39

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": "8255caa9-0bb3-4a30-a58c-f658cfb9dc39",
      "rev": "2-ddc878449bd4cd2fb7af49a23b4d5804",
      "identifiers": [],
      "created": 1700058627586,
      "modified": 1700058627645,
      "author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
      "responsible": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
      "tags": {},
      "codes": {},
      "names": [
        {
          "family": "Farnsworth",
          "given": [
            "Hubert",
            "J"
          ],
          "prefix": [],
          "suffix": [],
          "use": "official"
        },
        {
          "given": [
            "Professor"
          ],
          "prefix": [],
          "suffix": [],
          "use": "nickname"
        }
      ],
      "languages": [],
      "addresses": [],
      "gender": "male",
      "birthSex": "male",
      "mergedIds": [],
      "active": true,
      "deactivationReason": "none",
      "personalStatus": "unknown",
      "dateOfBirth": 28410409,
      "profession": "CEO/Owner of Planet Express, Lecturer at Mars University",
      "notes": [
        {
          "id": "3008f72c-3a06-46b6-84fc-205fee901c31",
          "tags": {},
          "markdown": {},
          "encryptedSelf": "xLPoepdC/4rsg12yZSTi3DlqHQxelcIhSIHgCtH3HfWZ3emCgFin2X1xt4slTp7kPsMIFt3AJRlR7s09KNtsPA=="
        }
      ],
      "nationality": "American",
      "relatives": [],
      "patientPractitioners": [],
      "patientProfessions": [],
      "properties": {},
      "systemMetaData": {
        "hcPartyKeys": {},
        "privateKeyShamirPartitions": {},
        "secretForeignKeys": [],
        "cryptedForeignKeys": {},
        "delegations": {},
        "encryptionKeys": {},
        "aesExchangeKeys": {},
        "transferKeys": {},
        "securityMetadata": {
          "secureDelegations": {},
          "keysEquivalences": {}
        },
        "encryptedSelf": "r17b+KCZbf/ZVT6WS6eO+remfJybbhBzhbktJ+HgZnc=",
        "publicKeysForOaepWithSha256": [],
        "tags": {}
      },
      "firstName": "Hubert",
      "lastName": "Farnsworth"
    }
  ]
}

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 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 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
[
  "8255caa9-0bb3-4a30-a58c-f658cfb9dc39"
]

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 Practitioner 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 Practitioner 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.