Subscribing to iCure events

At some point, you may want to listen to iCure events. For example, you may want to be notified when a patient is created or modified. This is possible with the iCure Medtech SDK.

What is an event ?

An event is a message sent by iCure to notify that something has happened. For example, when a new patient is created, iCure sends an event to all the users that are listening to this event.

Currently, iCure supports the following event types for the following entities:

	CREATE	UPDATE	DELETE
Patient	✅	✅	✅
Observation	✅	❌	✅
Condition	✅	✅	✅
Notification	✅	✅	✅
User	✅	✅	✅

How to listen to events ?

note

We assume that you already know the How to authenticate a user guide.

As an example, we will listen to CREATE events for Observation objects. This methodology can be applied to any other type of event and objects.

const events: Observation[] = []
const statuses: string[] = []

const connection = (
  await api.observationApi.subscribeToEvents(
    ['CREATE'], // Event types to listen to
    await new ObservationFilter(api)
      .forDataOwner(loggedUser.healthcarePartyId)
      .byLabelCodeDateFilter('IC-TEST', 'TEST')
      .build(),
    async (ds) => {
      events.push(ds)
    },
    {}, // Options
  )
)
  .onConnected(() => statuses.push('CONNECTED'))
  .onClosed(() => statuses.push('CLOSED'))

The subscribeToEvents method takes 4 parameters:

• The first parameter is an array of event types. In this example, we only listen to CREATE events (see the table above for the full list of event types).
• The second parameter is a filter. In this example, we only listen to events that are created by the logged user and that have the IC-TEST tag code and TEST tag type.
• The third parameter is a callback that is called when an event is received. In this example, we push the received event in an array called events.
• The fourth parameter is an options object. In this example, we don't use any options.

The subscribeToEvents method returns a Connection object. This object has 2 methods:

• onConnected is called when the connection is established
• onClosed is called when the connection is closed

caution

If you subscribe to multiple event types, you will not have access to the event type that triggered the callback. You may want to use a different connection for each event type if you need to distinguish them.

Example

To test this example, we will create a Observation object with the IC-TEST tag code and TEST tag type.

note

We assume that you already have a patient created. If not, you can add the following code below before the DataSample creation.

Create a patient

const patient = await api.patientApi.createOrModify(
  new Patient({
    firstName: 'John',
    lastName: 'Snow',
  }),
)

patient

{
  "id": "59d1b21e-2c59-442c-9cfd-62580015fc2e",
  "rev": "1-5102cd5af6c40bf390bbd1cb6d5ab96c",
  "identifiers": [],
  "created": 1700058630425,
  "modified": 1700058630425,
  "author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
  "responsible": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
  "tags": {},
  "codes": {},
  "names": [
    {
      "family": "Snow",
      "given": [
        "John"
      ],
      "prefix": [],
      "suffix": [],
      "text": "Snow John",
      "use": "official"
    }
  ],
  "languages": [],
  "addresses": [],
  "gender": "unknown",
  "birthSex": "unknown",
  "mergedIds": [],
  "active": true,
  "deactivationReason": "none",
  "personalStatus": "unknown",
  "notes": [],
  "relatives": [],
  "patientPractitioners": [],
  "patientProfessions": [],
  "properties": {},
  "systemMetaData": {
    "hcPartyKeys": {},
    "privateKeyShamirPartitions": {},
    "secretForeignKeys": [],
    "cryptedForeignKeys": {},
    "delegations": {},
    "encryptionKeys": {},
    "aesExchangeKeys": {},
    "transferKeys": {},
    "securityMetadata": {
      "secureDelegations": {},
      "keysEquivalences": {}
    },
    "encryptedSelf": "5gXmw1FfelxPcMArzq1sODqsVLiIkZm8GwbT0/1SSWY=",
    "publicKeysForOaepWithSha256": [],
    "tags": {}
  },
  "firstName": "John",
  "lastName": "Snow"
}

const dataSample = 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' }) }),
  }),
)

dataSample

{
  "id": "77060e3d-4439-49c7-bdb0-9b464de25694",
  "identifiers": [],
  "batchId": "a51859e0-f921-4d45-ac48-9ecbf290814b",
  "healthcareElementIds": [],
  "index": 0,
  "valueDate": 20231115143030,
  "openingDate": 20231115143030,
  "created": 1700058630491,
  "modified": 1700058630491,
  "author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
  "performer": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
  "localContent": {},
  "qualifiedLinks": {},
  "codes": {},
  "tags": {},
  "systemMetaData": {
    "secretForeignKeys": [
      "4aa57e92-e1d6-4ef3-bd37-0a4e28bbbea5"
    ],
    "cryptedForeignKeys": {},
    "delegations": {},
    "encryptionKeys": {},
    "securityMetadata": {
      "secureDelegations": {},
      "keysEquivalences": {}
    },
    "encryptedSelf": "zyj8F40IJ8o+dEgRoVckA7Bi50x/yQwCypxzX9D2DHJfeIfd4AK2A2Mfo9pcRG1qFyW6C/8YKXLwHBqtX5MwMTqtpc3JzdmmA0CpSmPe7GY=",
    "tags": {}
  },
  "notes": []
}

How to stop listening to events ?

To stop listening to events, you can call the close method on the Connection object.

connection.close()

events

[
  {
    "id": "77060e3d-4439-49c7-bdb0-9b464de25694",
    "identifiers": [],
    "batchId": "a51859e0-f921-4d45-ac48-9ecbf290814b",
    "healthcareElementIds": [],
    "index": 0,
    "valueDate": 20231115143030,
    "openingDate": 20231115143030,
    "created": 1700058630491,
    "modified": 1700058630491,
    "author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
    "performer": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
    "localContent": {},
    "qualifiedLinks": {},
    "codes": {},
    "tags": {},
    "systemMetaData": {
      "secretForeignKeys": [
        "4aa57e92-e1d6-4ef3-bd37-0a4e28bbbea5"
      ],
      "cryptedForeignKeys": {},
      "delegations": {},
      "encryptionKeys": {},
      "securityMetadata": {
        "secureDelegations": {},
        "keysEquivalences": {}
      },
      "encryptedSelf": "zyj8F40IJ8o+dEgRoVckA7Bi50x/yQwCypxzX9D2DHJfeIfd4AK2A2Mfo9pcRG1qFyW6C/8YKXLwHBqtX5MwMTqtpc3JzdmmA0CpSmPe7GY=",
      "tags": {}
    },
    "notes": []
  }
]

statuses

[
  "CONNECTED",
  "CLOSED"
]