Absences Data Sync

Overview

This article describes how to synchronize absences between shyftplan and an external system.

In the following sections you will find a detailed description of how to perform the synchronization.

shyftplan and other systems must be aligned on when an employee was/will be absent from work, or how many days of absence he has taken in a given year.

Each absence is related to one specific absence reason, which is its own object with its own ID in shyftplan (absence_reasons).

According to the company's regulations, synchronization of absences can be a more or less complex task.

Use cases:

• Simple use case: Absences are created, approved or refused, and deleted by users in shyftplan only, the external system updates its representation of the absence accordingly

• Advanced use case: Absences are created in shyftplan (by employees, mostly), but must be approved/refused in an external system. A sync is needed from shyftplan (on creation) and to shyftplan (on approval/refusal).

• Typical use case: Absence creation, approval and refusal happen in shyftplan and/or in the external system and must be synced to the other end. For example, some types of absences are maintained by HR managers who don't use shyftplan for their work.

  

ℹ️ Please consider:

• In other than the most simple cases (where shyftplan is seen as Source Of Truth), a decision regarding system priority is needed.

• It often makes sense not to maintain a complete, identical list of all possible absence reasons in both shyftplan and the external system. Instead you can map a number of shyftplan absence reasons to one reason in the external system (called "other sp reasons") - or vice versa.

• Your middleware has to know what to do when the sync process requests a state change for an absence and an error occurs. Examples are conflicts with other (pre-existing) absences, "vanished"/deleted absences or conflicting shift assignments,

• To find out when absences (or most other shyftplan objects) are deleted you can install webhooks - see guides on developer.shyftplan.com.

Key concepts

1. Days are not calendar days

Absences in shyftplan have a field called days that cannot be left empty.

• Days stores a non-negative integer number.

• When an absence changes to the accepted state, this number will be deducted from the employee's entitlement for the year.

• Note: The GUI would help you here with the suggestion of a reasonable value, taking into account settings in the company profile (public holidays that don't count) and the respective employment profile (usual work schedule). A different suggestion is made for absences that are set up to be calculated according to planned shifts of the employment.
  When you use the API, however, you have to calculate this number on your own (or get it from an external system)

2. Shifts collision handling for absences

• You can create an absence for an employee (with a POST on /absences) even though she has shifts at the time: Set the field force_collision to true.

• To do the same, but additionally remove the employee from the conflicting shifts (by deleting those staff shifts), set force_collision_and_remove to true.

• After that, the absence will remember the shifts that were deleted. You can see the details by querying the absence via GET /absences/{id}, if you set the parameter include_deleted_staff_shifts_info to true.

💡 Good to know: Approving/declining an absence without PUT

• To change the state of an absence from new to accepted (or refused) you can use PUT /absences/{id}.

• Another way is to use POST /absences/{id}/approve and POST /absences/{id)/decline - this has the advantage that you don't have to provide all the (required and additionally filled in) absence fields again

Direction of transfer

External system -> shyftplan

shyftplan -> external system

API documentation links

Find our complete API documentation on developer.shyftplan.com