Skip to main content

Handling users

Creating a user​

To create a user, you first need to create a User object and call the create method on the UserApi object.

//4 random characters to guarantee login uniqueness
const uniqueId = Math.random().toString(36).substring(4)

const userToCreate = new User({
  login: `john${uniqueId}`,
  email: `john${uniqueId}@hospital.care`,
  passwordHash: 'correct horse battery staple',
})

const createdUser = await api.userApi.createOrModify(userToCreate)
createdUser
{
  "id": "1ad0454d-0554-4008-ac05-80c5cf847ad1",
  "rev": "1-a2935837fdb2119e0f01d695c4807c08",
  "created": 1700058624896,
  "properties": {},
  "roles": {},
  "login": "johnkcq59ip2d",
  "passwordHash": "*",
  "groupId": "test-group",
  "sharingDataWith": {},
  "email": "johnkcq59ip2d@hospital.care",
  "authenticationTokens": {}
}
caution

The login and email fields must be unique. If you try to create a user with a login or email that already exists, the API will return a 400 error.

Creating a temporary authentication token for a User​

Sometimes, you may want to create a temporary authentication token for a user that will expire in a fixed amount of time. You can do that using the createToken method, that takes as parameters the id of the user for which create the token and the duration of the token, in seconds.

const token = await api.userApi.createToken(createdUser.id, 3600)
token
3a632a54-6c8f-48da-9e6f-3e4b350afbb3

Now it will be possible for the user to log in using the newly created token, that will expire after 1 hour.

note

A User can always create an authentication token for themselves, but only Admins can create authentication tokens for other users.

Creating a user associated to a patient​

The user you just created will be able to connect to the application but will not be able to manage data because it is not connected to a data owner.

You will often need to create a patient that can connect to iCure. In that case you can use createAndInviteUser:

const loggedUser = await api.userApi.getLogged()
const loggedPractitioner = await api.practitionerApi.get(loggedUser.healthcarePartyId)

if (
  !loggedPractitioner.addresses.find((a) =>
    a.telecoms.some((t) => t.system === ContactPointTelecomTypeEnum.EMAIL && !!t.value),
  )
) {
  //An email address is required for the healthcare professional to send the invitation
  loggedPractitioner.addresses.push(
    new Location({
      telecoms: [
        new ContactPoint({
          system: ContactPointTelecomTypeEnum.EMAIL,
          value: `hcp${uniqueId}@hospital.care`,
        }),
      ],
    }),
  )
}

const patientToCreate = new Patient({
  firstName: 'Argan',
  lastName: 'Poquelin',
  addresses: [
    new Location({
      addressType: LocationAddressTypeEnum.HOME,
      telecoms: [
        new ContactPoint({
          system: ContactPointTelecomTypeEnum.EMAIL,
          value: `argan${uniqueId}@moliere.fr`,
        }),
      ],
    }),
  ],
  dateOfBirth: 19730210,
  ssin: '1973021014722',
})
const createdPatient = await api.patientApi.createOrModify(patientToCreate)

const createdPatientUser = await api.userApi.createAndInviteFor(createdPatient)
createdPatient
{
  "id": "a37c4073-f96e-440c-8757-57a3a0ef7daf",
  "rev": "1-732bd01ebeeaa1d4dd9aa7cde40b724f",
  "identifiers": [],
  "created": 1700058624945,
  "modified": 1700058624945,
  "author": "17e392da-8e36-4e4e-abd7-7eef3e434395",
  "responsible": "3ed06450-17e5-47b6-ba4f-7a0a084df56b",
  "tags": {},
  "codes": {},
  "names": [
    {
      "family": "Poquelin",
      "given": [
        "Argan"
      ],
      "prefix": [],
      "suffix": [],
      "text": "Poquelin Argan",
      "use": "official"
    }
  ],
  "languages": [],
  "addresses": [
    {
      "addressType": "home",
      "notes": [],
      "telecoms": [
        {
          "system": "email",
          "value": "argankcq59ip2d@moliere.fr"
        }
      ]
    }
  ],
  "gender": "unknown",
  "birthSex": "unknown",
  "mergedIds": [],
  "active": true,
  "deactivationReason": "none",
  "ssin": "1973021014722",
  "personalStatus": "unknown",
  "dateOfBirth": 19730210,
  "notes": [],
  "relatives": [],
  "patientPractitioners": [],
  "patientProfessions": [],
  "properties": {},
  "systemMetaData": {
    "hcPartyKeys": {},
    "privateKeyShamirPartitions": {},
    "secretForeignKeys": [],
    "cryptedForeignKeys": {},
    "delegations": {},
    "encryptionKeys": {},
    "aesExchangeKeys": {},
    "transferKeys": {},
    "securityMetadata": {
      "secureDelegations": {},
      "keysEquivalences": {}
    },
    "encryptedSelf": "xaiIQeZAXayBnN/P0dBrOh0eNzyyvdxkkCxgqNqbiCk=",
    "publicKeysForOaepWithSha256": [],
    "tags": {}
  },
  "firstName": "Argan",
  "lastName": "Poquelin"
}
createdPatientUser
{
  "id": "0947dac5-6a61-4970-acc0-16183b93b731",
  "rev": "1-95bbb91bda2325688d1104d65cf4d246",
  "created": 1700058625027,
  "name": "argankcq59ip2d@moliere.fr",
  "properties": {},
  "roles": {},
  "login": "argankcq59ip2d@moliere.fr",
  "groupId": "test-group",
  "patientId": "a37c4073-f96e-440c-8757-57a3a0ef7daf",
  "sharingDataWith": {},
  "email": "argankcq59ip2d@moliere.fr",
  "authenticationTokens": {}
}
note

The createAndInviteUser method will send the patient an email with the link to the application. The email will contain the username and a temporary password.

caution

For this process to succeed the following conditions must be met:

  • the practitioner and the patient must have an email address or a mobile phone number.
  • the email address or the phone number of the patient must not be in use by another user in the database.

Loading a user by id​

To load a user by id, you can use the get method on the userApi:

const loadedUser = await api.userApi.get(createdUser.id)
loadedUser
{
  "id": "1ad0454d-0554-4008-ac05-80c5cf847ad1",
  "rev": "2-9333ab6c1a4e73df1ab1c02bee15c687",
  "created": 1700058624896,
  "properties": {},
  "roles": {},
  "login": "johnkcq59ip2d",
  "passwordHash": "*",
  "groupId": "test-group",
  "sharingDataWith": {},
  "email": "johnkcq59ip2d@hospital.care",
  "authenticationTokens": {}
}

Loading a user by email​

To load a user by email, you can use the getByEmail method on the userApi:

const loadedUserByEmail = await api.userApi.getByEmail(createdUser.email)
loadedUserByEmail
{
  "id": "1ad0454d-0554-4008-ac05-80c5cf847ad1",
  "rev": "2-9333ab6c1a4e73df1ab1c02bee15c687",
  "created": 1700058624896,
  "properties": {},
  "roles": {},
  "login": "johnkcq59ip2d",
  "passwordHash": "*",
  "groupId": "test-group",
  "sharingDataWith": {},
  "email": "johnkcq59ip2d@hospital.care",
  "authenticationTokens": {}
}

Filtering users​

To filter users, you can use the filterBy method on the userApi.

The following filters are available:

  • Filtering on a collection of ids
  • Filtering by patient id
const users = await api.userApi.filterBy(
  await new UserFilter(api).byPatientId(createdPatient.id).build(),
)
users
{
  "rows": [
    {
      "id": "0947dac5-6a61-4970-acc0-16183b93b731",
      "rev": "2-dbd73dcd586a0105bb863dd232c847db",
      "created": 1700058625027,
      "name": "argankcq59ip2d@moliere.fr",
      "properties": {},
      "roles": {},
      "login": "argankcq59ip2d@moliere.fr",
      "groupId": "test-group",
      "patientId": "a37c4073-f96e-440c-8757-57a3a0ef7daf",
      "sharingDataWith": {},
      "email": "argankcq59ip2d@moliere.fr",
      "authenticationTokens": {}
    }
  ]
}

Update a user​

To update a user, you first need to load the user you want to update, then modify the fields you want to update and call the createOrModify method on the userApi.

const userToModify = await api.userApi.get(createdUser.id)
const modifiedUser = await api.userApi.createOrModify(
  new User({ ...userToModify, passwordHash: 'wrong horse battery staple' }),
)
modifiedUser
{
  "id": "1ad0454d-0554-4008-ac05-80c5cf847ad1",
  "rev": "3-50786a0413e173011c45b48ada7207de",
  "created": 1700058624896,
  "properties": {},
  "roles": {},
  "login": "johnkcq59ip2d",
  "passwordHash": "*",
  "groupId": "test-group",
  "sharingDataWith": {},
  "email": "johnkcq59ip2d@hospital.care",
  "authenticationTokens": {}
}

Delete a user​

To delete a user, you call the delete method on the UserApi and pass the id of the user to be deleted.

const deletedUserId = await api.userApi.delete(createdUser.id)
deletedUserId
4-ebaca07d4c6d7217f704d9bf83d4d30e

For the gory details of all you can do with users using the SDK, check out the UserApi documentation.