This document describes a recommended way of syncing users from a customer to Learnifier via the Learnifier Public API.

Prerequisites

The customer’s data is considered master data, i.e. if a user is present at the customer it should be created at Learnifier, and if a Learnifier user is not at the customer, the Learnifier user should be removed or hidden.

The customer provides a unique id that is used to identify a user. This id is called “external id” on the Learnifier side. The external id is a case-sensitive string and consists of alphanumeric characters.

The customer needs to set up API authorization via keys to be able to access the Learnifier Public API. See https://learnifier.com/api for more information. The keys need to be Back Office keys so the key has full access to Learnifier.

The synchronization is done over all users in the realm, and not individual clients.

Recommended algorithm

• Fetch all Learnifier users via GET /users. Make sure to check the result to see if there are more users available. It might be necessary to call GET /users several times using the limit and offset parameters to retrieve all users. 

• Fetch all local users

• For each local user

  • Find matching Learnifier user (using the external id)

    • If user is missing 

      • create the user  via (POST /users), 

      • remove Learnifier user from local list 

      • continue to next user

  • Remove Learnifier user from local list

  • Compare local user details with Learnifier user

    • If different use PATCH /users/{userId} to update the Learnifier user. Optionally use the autoClearEmail flag, see discussion in section below)

  • For all Learnfier users still in the local list

    • Delete (DELETE /users/{userId}) or deactivate/lock user (PATCH /users/{userId} to set hardLock to true)

If the number of users is large the user sync can use substantial system resources in Learnifier so only run this periodically, e.g. once a day or once a week.

AutoClearEmail

When updating a user the flag “autoClearEmail” can be used. The email (or username if email is not used) will then be automatically cleared on the duplicates.

This simplifies the algorithm for the user sync when changing email/username and the email/username already is in use. 

If not used, the algorithm needs to remove the duplicate user or change the email/username before the change is issued else the operation will fail.

Using autoClearEmail may result in Learnifier users without email or username. They will still be accessible from the API using the external id.

Mixing Learnifier users with synched users

The algorithm outlined above does not take into consideration a mix of users that is created directly in Learnifier and users that are synchronized from the customer. An example of this could be administrators created directly in Learnifier while all learners are synced from the customer.

A simple way of distinguishing between the two categories of users is to check if the user has an external id or not. A user created directly in Learnifier will not have an external id. Modify the algorithm above to ignore users that do not have an external id.