User synchronisation

Scenario outline

Your company has a central database with information about employees. Name, email, the name of their manager and (often) a cost center. Specifics varies between organisations, but usually an Active Directory or payroll system will be the source of truth for employee data.

You want to synchronise this data with Skovik, so that when a new colleague joins they will be set up in Skovik automatically.

Under this scenario we recommend the following approach.

1. Make a list of required data

Determine what pieces of information you'll need to send to Skovik. Name and email is mandatory, but you'll almost always also want to set the manager, an employee number and an associated cost center. If your business is spread over multiple jurisdictions you may need to consider which legal entity the employee is employed at.

2. Figure out where it's at

Figure out which systems contain this information today. Sometimes everything will be stored in one place, but if not, you could either (a) pull from multiple sources or (b) adjust internal data flows so that everything is available in one place.

3. Write the code

The integration code itself will be event based (when relevant properties for an employee changes) or scheduled (say every 3 hours). Both will work equally well from our perspective, but event-based integrations are rare. We usually recommend the scheduled-based approach.

Scheduled integration

The scheduled script will run every few hours and do something along these lines:

1. Extract a list of users from your system (or systems).
2. Extract a list of users in Skovik (via a series of GET requests, using pagination).
3. Iterate through the list from your system, compare each user with the data in the list pulled from Skovik, and divide the users into four groups: (a) missing in Skovik (b) should be removed from Skovik (c) needs an update in Skovik (d) no action required
4. For each group, make the relevant POST/PUT/DELETE request to add, remove or update these users in Skovik.

• The steps 1-4 should all occur during one "run" of the scheduled script.
• When steps 1 and 2 are completed you'll have two in-memory lists, for example two arrays of dicts.
• During step 3 you'll create four new lists, corresponding to the desired changes in Skovik.
• In the 4th step you'll make the relevant requests to Skovik, effectively synchronizing your system with ours.

Event-based integration

When an event is triggered (a user is added/updated/removed), make the appropriate HTTP request to Skovik. Make sure that events will be emitted for the relevant events.

📘

Manager changes

When changing someone's manager, keep in mind that the manager must exist in Skovik. For scheduled integrations (the most common type) one must consider that the new manager for an employee may not exist in Skovik yet.

An easy solution is to toggle a flag if the manager couldn't be found in the list pulled from Skovik and don't set a manager. Then, after iterating through the whole list, check if the flag is set and trigger an immediate re-run in case it was. During this re-run you are guaranteed to have the manager present.

🗑

Accidental deletion

A small error in your integration code may cause accidental deletion of all employees. An easy way of avoiding such an error is to include a sanity check in the synchronisation script.

This check would run after step four above, and if the percentage of removed (or modified) accounts is larger than ~20%, the script should terminate and report an error.

While we can sometimes help you recreate deleted employees, the work involved is not trivial so it's much better to avoid the situation altogether.