Skip to main content

Handling Observations

In this section, we will learn how to manage observations. Observations are used to store data that is not part of the patient's medical record, such as blood pressure measurements.

note

We assume in the examples below that you have already created a patient. If not, please follow the Handling patients guide.

How to create Observations?​

To create Observations, we can use the createOrModifyFor method on the ObservationApi object. This method takes two parameters: the patient's id and the Observation object.

const createdObservation = await api.observationApi.createOrModifyFor(
  patient.id,
  new Observation({
    tags: new Set([new CodingReference({ type: 'IC-TEST', code: 'TEST' })]),
    localContent: mapOf({ en: new LocalComponent({ stringValue: 'Hello world' }) }),
    openingDate: 20220929083400,
  }),
)
createdDataSample
{
  "id": "2c091d0b-4630-4917-8771-12b6da9ebed3",
  "identifiers": [],
  "batchId": "852379c3-f351-49b2-b72d-6efda481ae13",
  "healthcareElementIds": [],
  "index": 0,
  "valueDate": 20231115143004,
  "openingDate": 20220929083400,
  "created": 1700058604557,
  "modified": 1700058604557,
  "author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
  "performer": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
  "localContent": {},
  "qualifiedLinks": {},
  "codes": {},
  "tags": {},
  "systemMetaData": {
    "secretForeignKeys": [
      "eee6d63e-1186-454e-9a24-73097d49f0e6"
    ],
    "cryptedForeignKeys": {},
    "delegations": {},
    "encryptionKeys": {},
    "securityMetadata": {
      "secureDelegations": {},
      "keysEquivalences": {}
    },
    "encryptedSelf": "ZjsOUIEHhMIwZHDgmpW0Eay2Qe5vwA8lzOmvaNChyiG1dBk7ulnGBSVH/9RpatDg56KEPSpnsQk4Pu5TBcJBf07plfVj0L/eR/qnvN5lhNE=",
    "tags": {}
  },
  "notes": []
}

In this example, we created an Observation with the IC-TEST tag code and TEST tag type. We also added a comment and an opening date.

info

Behind the scenes: the createOrModifyFor method will encrypt the Observation and send it to the iCure backend. From now on you will be able to retrieve the content of this Observation only if you have the correct key to decrypt it.

How to retrieve Observations?​

To retrieve an Observation, we can use the get method on the ObservationApi. This method takes one parameter: the Observation's id.

const dataSample = await api.observationApi.get(createdObservation.id)
dataSample
{
  "id": "2c091d0b-4630-4917-8771-12b6da9ebed3",
  "identifiers": [],
  "batchId": "852379c3-f351-49b2-b72d-6efda481ae13",
  "healthcareElementIds": [],
  "index": 0,
  "valueDate": 20231115143004,
  "openingDate": 20220929083400,
  "created": 1700058604557,
  "modified": 1700058604557,
  "author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
  "performer": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
  "localContent": {},
  "qualifiedLinks": {},
  "codes": {},
  "tags": {},
  "systemMetaData": {
    "secretForeignKeys": [
      "eee6d63e-1186-454e-9a24-73097d49f0e6"
    ],
    "cryptedForeignKeys": {},
    "delegations": {},
    "encryptionKeys": {},
    "securityMetadata": {
      "secureDelegations": {},
      "keysEquivalences": {}
    },
    "encryptedSelf": "ZjsOUIEHhMIwZHDgmpW0Eay2Qe5vwA8lzOmvaNChyiG1dBk7ulnGBSVH/9RpatDg56KEPSpnsQk4Pu5TBcJBf07plfVj0L/eR/qnvN5lhNE=",
    "tags": {}
  },
  "notes": []
}

How to update Observations?​

In order to update an Observation, we can use the createOrModifyFor method on the ObservationApi. This method takes two parameters: the patient's id and the Observation object.

info

The patient's id must be the same as the one used to create the Observation.

If you linked the Observation to the wrong patient, you have to delete the first Observation and create a new one with the correct patient's id.

const updatedObservation = await api.observationApi.createOrModifyFor(
  patient.id,
  new Observation({
    ...createdObservation,
    localContent: mapOf({ en: new LocalComponent({ stringValue: 'Hello world updated' }) }),
    modified: undefined,
  }),
)
updatedDataSample
{
  "id": "2c091d0b-4630-4917-8771-12b6da9ebed3",
  "identifiers": [],
  "batchId": "852379c3-f351-49b2-b72d-6efda481ae13",
  "healthcareElementIds": [],
  "index": 0,
  "valueDate": 20231115143004,
  "openingDate": 20220929083400,
  "created": 1700058604557,
  "modified": 1700058604611,
  "author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
  "performer": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
  "localContent": {},
  "qualifiedLinks": {},
  "codes": {},
  "tags": {},
  "systemMetaData": {
    "secretForeignKeys": [
      "eee6d63e-1186-454e-9a24-73097d49f0e6"
    ],
    "cryptedForeignKeys": {},
    "delegations": {},
    "encryptionKeys": {},
    "securityMetadata": {
      "secureDelegations": {},
      "keysEquivalences": {}
    },
    "encryptedSelf": "Gj++ujQMPfmUMeahN/mxt1nvROmK5GfrwV8t2U4WTFjFm99bgNW+v6KC1BecLhiZ8xWFhvhL37JfaeOi/LSwf3xhxYsap4G6xLuylhdA4IQ=",
    "tags": {}
  },
  "notes": []
}

How to delete Observations?​

To delete an Observation, you can use the delete method on the ObservationApi. This method takes one parameter: the Observation's id.

const deletedObservation = await api.observationApi.delete(updatedObservation.id)
deletedDataSample
2c091d0b-4630-4917-8771-12b6da9ebed3

How to filter Observations?​

To retrieve a list of Observation, we can use the filterBy method on the ObservationApi. This method takes one parameter: the filter object.

We can build the filter object using the ObservationFilter builder.

const filter = await new ObservationFilter(api)
  .forDataOwner(loggedUser.healthcarePartyId)
  .byLabelCodeDateFilter('IC-TEST', 'TEST')
  .forPatients([patient])
  .build()

const filteredObservations = await api.observationApi.filterBy(filter)
filteredDataSamples
{
  "rows": [
    {
      "id": "2c091d0b-4630-4917-8771-12b6da9ebed3",
      "identifiers": [],
      "batchId": "852379c3-f351-49b2-b72d-6efda481ae13",
      "healthcareElementIds": [],
      "index": 0,
      "valueDate": 20231115143004,
      "openingDate": 20220929083400,
      "created": 1700058604557,
      "modified": 1700058604611,
      "author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
      "performer": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
      "localContent": {},
      "qualifiedLinks": {},
      "codes": {},
      "tags": {},
      "systemMetaData": {
        "secretForeignKeys": [
          "eee6d63e-1186-454e-9a24-73097d49f0e6"
        ],
        "cryptedForeignKeys": {},
        "delegations": {},
        "encryptionKeys": {},
        "securityMetadata": {
          "secureDelegations": {},
          "keysEquivalences": {}
        },
        "encryptedSelf": "Gj++ujQMPfmUMeahN/mxt1nvROmK5GfrwV8t2U4WTFjFm99bgNW+v6KC1BecLhiZ8xWFhvhL37JfaeOi/LSwf3xhxYsap4G6xLuylhdA4IQ=",
        "tags": {}
      },
      "notes": []
    }
  ]
}

Filter builder​

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

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

const dataSampleFilter = new ObservationFilter(api)
  .forDataOwner(loggedUser.healthcarePartyId)
  .byLabelCodeDateFilter('IC-TEST', 'TEST')
  .forPatients([patient])
  .build()
dataSampleFilter
{}

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

  • The Observation is owned by the logged user's healthcare party
  • The Observation has a tag with type IC-TEST and code TEST
  • The Observation is linked to patient

How to get a list of Observation ids?​

In some circumstances, you might want to get a list of Observation ids instead of the Observations themselves. To do so, you can use the matchBy method on the ObservationApi. This method takes one parameter: the filter object.

const matchFilter = await new ObservationFilter(api)
  .forDataOwner(loggedUser.healthcarePartyId)
  .forPatients([patient])
  .build()

const matchedObservationIds = await api.observationApi.matchBy(matchFilter)
matchedDataSampleIds
[
  "2c091d0b-4630-4917-8771-12b6da9ebed3"
]