User Change Notifications¶
You can enable user change notifications by setting the Provider setting
API/API_SEND_NOTIFICATIONS
to True
. When enabled, the Registration
Server will send a user change notification event to the URL specified by
the API/API_NOTIFICATION_URL
.
Only changes to users belonging to the Provider will result in a notification. If the user’s Provider is changed, then no further notifications will be sent for the user, unless notifications have been enabled for the new Provider.
Notification Format¶
Notifications are sent by performing an HTTP POST to the URL specified by
API/API_NOTIFICATION_URL
. The body of the POST request is a JSON
(http://www.json.org) encoded message (content type “application/json”):
{
"updated": "",
"username": "",
"status": "ok",
"distributor": "",
"email": "",
"language": "",
"department": "",
"reference": "",
"authid": ""
}
The notification message always includes all fields of the user record. That is, both fields that have changed, and those that have not.
Each message will include only one of the following: "inserted"
, "updated"
or "deleted"
( in which all fields are included):
- If a new user was added then
"inserted": true
will be included in the notification.- If an existing records has changed, then
"updated"
specifies which fields have changed as a comma separated list. For example:"status,email,department"
. The value of this field cannot be empty because a notification is not sent if the user record is not changed by an update.- If the user has been deleted permanently, then
"deleted": true
is included in the notification.
For example, when a user is added the message may look like this:
{
"inserted": true,
"username": "$EGCO-1234",
"status": "not-activated",
"distributor": "EGCO",
"email": "json@example.com",
"language": "en_us",
"department": null,
"reference": null,
"authid": "json_sample"
}
If the same user is later deleted then the message may look as follows:
{
"deleted": true,
"username": "$EGCO-1234",
"status": "to-delete",
"distributor": "EGCO",
"email": "json@example.com",
"language": "en_us",
"department": null,
"reference": null,
"authid": "json_sample"
}
The "username"
field may never change. This is the TeamDrive registration name
of the user, or a so-called “magic” username. A magic username can be identified by
the fact that it starts with a $
followed by the user’s original Provider code. Magic
usernames are generated by the Registration Server, if a user is only identified
by an email address during registration. This is, for example, the case when using
an external authentication service.
The "status"
field is set to "ok"
if the user account is active. Otherwise,
the status is set to a list of status conditions. There are three status conditions:
"not-activated"
, "disabled"
and "to-delete"
. For example:
"status": "not-activated,disabled"
"not-activated"
is the status condition set after registration, before the email address of the user has been confirmed."disabled"
status condition is set to temporarily disabled the user’s account. Disabled accounts cannot be accessed by the TeamDrive Client."to-delete"
is set in order to schedule an account for deletion.
"distributor"
specified the user’s Provider code. The fields "email"
and
"language"
may be set by the TeamDrive Client.
The values of the fields
"department"
and "reference"
are determined by external systems. These fields
are not used by TeamDrive, however, "reference"
can be used to identify a user
when making API calls. In this case the setting CLIENT/EXT_USER_REFERENCE_UNIQUE
should
be set to True
in order to ensure that only one user is referenced.
The "authid"
is used by external authentication services,
see External Authentication. This value identifies the user in authentication
service’s database. This value may never change.
If not used, the fields "department"
, "reference"
and "authid"
will be
null
.
Notification Result Handling¶
The Registration Server expects an HTTP “200 OK” or “201 Created” result from notification POST. If the Registration Server does not receive one of these results, an error is logged, and the notification is delayed, and sent later.
This means, for example, if the receiving is service is not available for a period of time, notifications will not be lost.
Once a message has been delayed, all subsequent notifications for the Provider are also delayed. This is to ensure that messages are sent in the order in which the changes occurred.
The “Send Notifications” Auto Task is responsible for sending delayed notifications.
“Send Notifications” Auto Task¶
The “Send Notifications” Task sends notifications that have been delayed for some reason. The task runs every 5 minutes by default.