API user preference migration 2023
Until February 2023 contact methods as well as notification preferences were part of the user REST resource. They have now been moved into their own resources.
Why was this change introduced?
Our goal was to enable users to manage multiple contact methods and give them the opportunity to have full freedom in configuring their notification devices, as well as to differentiate between their account's email and notification email. This change also gave us the chance to deliver a complete overhaul of the UI experience in web and mobile apps and set the future path for even more upcoming notification methods.
The old user resource request / response schema
The new user resource request / response schema
Moved resources
Resource / field | Moved from | Moved to |
---|---|---|
user.email | /api/users | /api/users/{id}/contacts/emails |
user.mobile | /api/users | /api/users/{id}/contacts/phone-numbers |
user.landline | /api/users | /api/users/{id}/contacts/phone-numbers |
user.notificationPreferences | /api/users | /api/users/{id}/notification-preferences/alerts |
user.lowPriorityNotificationPreferences | /api/users | /api/users/{id}/notification-preferences/alerts |
user.onCallNotificationPreferences | /api/users | /api/users/{id}/notification-preferences/duties |
user.subscribedAlertUpdateStates | /api/users | /api/users/{id}/notification-preferences/updates |
user.subscribedAlertUpdateNotificationTypes | /api/users | /api/users/{id}/notification-preferences/updates |
user.subscriptionNotificationTypes | /api/users | /api/users/{id}/notification-preferences/subscriptions |
Note that the email field still exists in the new user resource schema, that is because this email field still determines the user account's email that is used for logins or things like password recovery. The new email resource however is used to manage alert or incident specific notifications.
How does the live migration work in particular?
the migration status is tracked on a per user basis
contact and preference resources were created automatically for every user based on the current user.* fields
when using the new UI in web or mobile (or the new APIs) with create or update operations the user is flagged, this will result in GET /users, /users/x, /users/current requests to no longer contain the old but the new schema for this particular user
When sending the old user schema in update (PUT) operations the user's contacts and preferences are reset to the state of the content of the user.* fields (just like the second migration step described above). Additionally the flag is removed and the old schema is returned by GET resources again.
What action do I have to take?
Unless you are using the API or Terraform to manage user notification preferences there is no action required. Refer to the section Migrating ilert-go and/or Terraform to follow a migrating guide for both ilert-go and Terraform.
If you are using custom workflows to create or update user preferences, your workflows should continue to work. However to prevent confusion of end-users wanting to make updates to their preferences using the new UI experience, we suggest removing the migrated fields from your user payload: mobile, landline, notificationPreferences, lowPriorityNotificationPreferences, onCallNotificationPreferences, subscribedAlertUpdateStates, subscribedAlertUpdateNotificationTypes
Please make sure that your users have already started to use the new UI to manage their preferences, before removing the fields and running the updates - otherwise their preferences will be dropped.
In case you need support, feel free to reach out any time.
Migrating ilert-go and/or Terraform
Ilert-go and Terraform were both updated to a new major version.
Client | Old version | New version |
---|---|---|
v2.6.0 | v3.0.0 | |
v1.11.4 | v2.0.2 |
While many inconsistency issues were addressed and quality of life improvements plus bug fixes were implemented, the user resource was updated accordingly and new resources for user notification preferences were introduced in both clients.
There are four possible cases for the migration:
| You do not have to take any action. |
| Be aware of the moved resources.
When none of the migrated fields (except |
| Terraform: remove field |
| Terraform/ilert-go: remove all fields associated to notification settings (and field |
When all migration steps are done you can safely update your ilert-go/Terraform to the latest.
Migration example for Terraform
The following example visualizes a transition of a pre-v2 user resource to the new user resource and notification settings resources.
Pre v2 script
New v2 script
Last updated