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 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.