Web Services - Actual schedules

Voir la version française.

Description

Each employee has a collection with his/her actual schedules. Each resource is a 24-hour actual schedule of an employee. An employee has a schedule type resource (even if empty) for all the 24-hour periods beginning on a date for which the employee as a structure assignment.

URI	<uri_personne>/plannings_real
Category	http://schemas.holydis.com/tsq/2010#planning_real
Available for writing	Yes

Specific settings

Setting	Description
datetime-min	Filters schedules available after or durin the specified date.
datetime-max	Filters available schedules before or during the specified date.
valide	Filters schedules to those that are validated (true) or not validated (false).
valide-datetime-min	Filters schedules to those that have been validated (date available in the DateValidation field) after or during the specified date. This parameter must be associated to the valide parameter as true.
valide-datetime-max	Filters schedules to those that have been validated (date available in the DateValidation field) before or during the specified date. This parameter must be associated to the valide parameter as true.
timeZoneOffset	Specifies whether the start and end times of schedule items should be displayed taking into account the time zone (true) or without taking into account the time zone (false).

The period passed in parameter takes into account the day change time. If a different day change time from that of the person's calendar is passed as a parameter, this may have an impact on the period retrieved. If a datetime-min is entered with a time less than the person's day change time, then the previous day will be considered to retrieve the schedules. If a datetime-max is entered with a time greater than the person's day change time, then the next day will be considered to retrieve the schedules.

Example 1: For a person whose database identifier is 16000 with a calendar having a day change time of 04:00, the following request retrieves the schedules of this person from 01/19/2022 to 01/27/2022:

GET /[URI_de_base]/api/feed/personnes/16000/plannings_real?datetime-min=2022-01-20T03:00:00&datetime-max=2022-01-26T06:00:00

Example 2: For a person whose database identifier is 16000 with a calendar having a day change time of 04:00. The following request:
 

GET /[URI_de_base]/api/feed/personnes/16000/plannings_real?datetime-min=2022-01-20&datetime-max=2022-01-20

retrieves this person's schedules for 01/19/2022 only. Indeed for Timesquare the 01/20/2022 at 00:00 corresponds to 01/19/2022 because the day change time is at 04:00.

Elements

Element	Description
periode	The time period spanned by the schedule. This period indicates the start and end timestamp (24h). It also indicates the day change time associated with the calendar to which the person is assigned for the date of the schedule. If the person does not have a calendar assignment for that date, this is the default calendar day changeover time of the structure to which the person is assigned. All periods for which there is an schedule are in the time zone of the person's calendar in the period.
jourFixe	Indicates whether the schedule is fixed (true) or not (false).
publie	Indicates whether the schedule is published (true) or not (false).
valide	Indicates whether the schedule is validated (true) or not (false).
composantsPlanning?	The components (contents) of the schedule. If the element is not present that means that there is no component and that it cannot be added. It may happen if the employee is out-of-contract (he/she has no contract for the start day of the schedule’s period) or if there is a closed day in his/her calendar for the date.
dateValidation?	Validation date if the schedule is validated.
dateModification?	Last modification date.
dateEchange?	Trade date saved at the moment of the schedule trade My Timesquare.
planningOrigineEchange?	If the schedule is the result of a trade, date of the schedule with the trade was made.
dureeQuotidienne?	Daily length of the schedule. Example: PT5H30M for a daily duration of 5h30. The element is not present if there is no value, in this case there is a weekly value instead. That property is calculated, it will be ignored by the server during modifications. The duration includes breaks regardless of the basic setting.
elementsVariables	Variable elements of the schedule.
evControle	Indicates whether the variable elements have been controlled (true) or not (false).
dureeBonification?	Daily bonus duration in the schedule. Example: PT0H15M in XML for a bonus duration of 15 minutes.
dureeHebdo?	Weekly length. It is the length of the week containing this schedule if the daily duration has no value. This property is calculated, it will be ignored by the server during modifications.
timeZoneId	Time zone identifier. Example: Europe/Paris. To read the data according to the Europe/Lisbon time zone, add the User-TimeZoneId parameter to the request header with the value of the identifier of the Lisbon time zone, in this case Europe/Lisbonne. If the header parameter is missing, the data is returned raw (in the resource's time zone).
typejour	Day type.

If the person is outside the structure, the Web Service returns a 500 error.

In writing, it is only possible to add one schedule items at a time per call to the Web Service. To add multiple schedule items, it is necessary to make as many calls as there are schedule items to add.

PUT request is not allowed.

To modify a schedule, I have to delete the schedule with a DELETE request and then create a new schedule with POST requests.

When writing a schedule, the rules that apply are the same as those for the standard import of schedules.

Special case: the comment

The comment is a planning element a little different from the others in that it is not linked to a planning day (in its storage in the database). It is qualified by a date, a person concerned and a planning version.

The creation and modification of comments are managed by a PUT request.

PUT /[URI_de_base]/api/feed/personnes/[ID-PERSONNE]/plannings_real/[AAAA-MM-JJ]/commentaire

• If I use a JSON file as input, I can write almost all possible characters in the string between "". Examples of special characters in json: newline (\n), quote (").
• If I use an XML file as input, the characters < > & cannot be written because the document will no longer be "well-formed" and the XML parser will not be able to interpret it correctly (parsing error). Example of special characters in XML: newline "&#10;". In this case, I can:
  • use "escaped" sequences for these characters such as "&lt;", "&gt;", "&amp;"
    Example:
    <tsq:commentaire> Un commentaire &lt;très intéressant&gt; </tsq:commentaire>
  • place the text containing all the desired characters in a CDATA section
    Example: 
    <tsq:commentaire><![CDATA[Un commentaire <très> intéressant]]></tsq:commentaire>

Special case: deletion of a notification with an external ID

Deleting a notification with an external ID is done with the following request:

DELETE /[URI_de_base]/api/feed/plannings/convocations?idExterne=XXXXX

If a schedule containing a convocation with an external identifier is deleted, the convocation is deleted from all schedule versions.

Examples of requests

Reading

Read the actual schedule of the employee whose database identifier is 16000 on a given day (23/06/2022)

GET /[URI_de_base]/api/feed/personnes/16000/plannings_real/2022-06-23

Read the actual schedules of the employee whose database identifier is 3039 over a given period (from 10/11/2025 until 12/11/2025)

GET /[URI_de_base]/api/feed/personnes/3039/plannings_real?datetime-min=2025-11-10&datetime-max=2025-11-12

Example of XML request results

Example of JSON request results

Read the actual schedule of the employee whose database identifier is 16000 over a given period (from 20/06/2022 until 26/06/2022)

GET /[URI_de_base]/api/feed/personnes/16000/plannings_real?datetime-min=2022-06-20&datetime-max=2022-06-26

Read the actual validated schedule of the employee whose database identifier is 16000 over a given period (from 20/06/2022 until 26/06/2022)

GET /[URI_de_base]/api/feed/personnes/16000/plannings_real?datetime-min=2022-06-20&datetime-max=2022-06-26&valide=true

Read the actual not validated schedule of the employee whose database identifier is 16000 over a given period (from 20/06/2022 until 26/06/2022)

GET /[URI_de_base]/api/feed/personnes/16000/plannings_real?datetime-min=2022-06-20&datetime-max=2022-06-26&valide=false

Read the actual schedule validated over a given period (from 20/06/2022 until 26/06/2022) for the employee whose database identifier is 16000

GET /[URI_de_base]/api/feed/personnes/16000/plannings_real?valide-datetime-min=2022-06-20&valide-datetime-max=2022-06-26&valide=true

Writing

Add a schedule day containing a task on the actual schedule on a given day (on 05/11/2024) for the employee whose database identifier is 3051

POST /[URI_de_base]/api/feed/personnes/3051/plannings_real/2024-11-05

Example of XML input file

Example of JSON input file

Add a schedule day containing a home office work period on the actual schedule on a given day (on 12/02/2025) for the employee whose database identifier is 3039

POST /[URI_de_base]/api/feed/personnes/3039/plannings_real/2025-02-12

Example of XML input file

Example of JSON input file

Add a schedule day containing a notification on the actual schedule on a given day (on 05/11/2024) for the employee whose database identifier is 3051

POST /[URI_de_base]/api/feed/personnes/3051/plannings_real/2024-11-05

Example of XML input file

Example of JSON input file

Add a schedule day containing an unavailability on the actual schedule on a given day (on 05/11/2024) for the employee whose database identifier is 3051

POST /[URI_de_base]/api/feed/personnes/3051/plannings_real/2024-11-05

Example of XML input file

Example of JSON input file

Add a schedule day containing a rest day on the actual schedule on a given day (on 05/11/2024) for the employee whose database identifier is 3051

POST /[URI_de_base]/api/feed/personnes/3051/plannings_real/2024-11-05

Example of XML input file

Example of JSON input file

Add a schedule day containing a comment on the actual schedule on a given day (on 05/11/2024) for the employee whose database identifier is 3051

PUT /[URI_de_base]/api/feed/personnes/3051/plannings_real/2024-11-05/commentaire

Example of XML input file

Exemple de fichier JSON en entrée

Delete the actual schedule on a given day (le 28/10/2024) for the employee whose database identifier is 3051

DELETE /[URI_de_base]/api/feed/personnes/16000/plannings_real/2024-10-28

Delete the actual schedule on a given period (from 29/10/2024 until 30/10/2024) for the employee whose database identifier is 3051

DELETE /[URI_de_base]/api/feed/personnes/16000/plannings_real?datetime-min=2024-10-29&datetime-max=2024-10-30

Delete the notification whose database identifier is 9911 on all versions of schedules

DELETE /[URI_de_base]/api/feed/plannings/convocations?idExterne=9911

Functional error messages

• Error 400 Date renseignée non valide 
• Error 400 [DATETIME MIN] n'est pas au format xsd:dateTime
• Error 400 [DATETIME MAX] n'est pas au format xsd:dateTime
• Error 400 Date renseignée non valide
• Error 400 Le planning modifiable n'est pas disponible dans le workflow
• Error 400 Le planning réalisé n'est pas disponible dans le workflow
• Error 400 Le planning de la version précédente n'est pas validé
• Error 400 Le planning est validé et il ne peut pas être modifié
• Error 400 La personne est hors planning
• Error 400 Un jour fermé ne peut pas être modifié
• Error 400 Au moins un composant de planning doit être présent
• Error 400 Il est impossible d'insérer plus d'un composant de planning
• Error 400 Il est impossible d'insérer plus d'une tâche ou d'une pause à la fois
• Error 400 Les heures de début et de fin sont manquantes
• Error 400 Les heures de début et de fin ne sont pas des multiples de la granularité
• Error 400 Les heures de début et de fin de tâche ne sont pas des multiples de la granularité
• Error 400 Le décompte jour spécifique de l'absence complète n'est pas un multiple de la granularité
• Error 400 Le décompte spécifique d'au moins une absence partielle n'est pas un multiple de la granularité
• Error 400 Les heures de début et de fin sont manquantes
• Error 400 Les heures de début et la fin d'une plage horaire doivent être différentes
• Error 400 La période du composant de planning doit être incluse dans la période du jour
• Error 400 Le libellé de substitution pour le repos n'est pas sélectionné dans la configuration
• Error 400 Au moins un type d'absence n'est pas renseigné ou est invalide
• Error 400 Le type d'absence ne peut pas être utilisé, il n'est pas visible dans la structure de la personne
• Error 400 Le type de tâche doit être précisé
• Error 400 La tâche ne peut pas être utilisée, elle n'est pas visible dans la structure de la personne
• Error 400 Une tâche qui n'est pas télétravaillable ne peut pas être marquée comme TT ou/et fixe/variable
• Error 400 Le type de la convocation n'est pas renseigné ou est invalide
• Error 400 La convocation ne peut pas être utilisée, elle n'est pas visible dans la structure de la personne
• Error 400 Une convocation doit avoir une option (1, 2 ou 3)
• Error 400 Une convocation doit avoir un emplacement de travail (0, 1 ou 2)
• Error 400 La date de début doit être antérieure à la date de fin
• Error 400 Le commentaire ne peut pas être vide
• Error 400 La personne n'a pas de structure à la date donnée
• Error 404 ID externe inconnu
• Error 500 Composant inconnu