Web Services - Les plannings réalisés

View the English version.

Description

Chaque personne a une collection avec ses plannings réalisés. Chaque ressource est le planning réalisé d'une personne pendant 24 heures. Une personne a une ressource de type planning (même s'il est vide) pour toutes les périodes de 24 heures qui commencent à une date pour laquelle la personne a une affectation de structure.

URI	<uri_personne>/plannings_real
Catégorie	http://schemas.holydis.com/tsq/2010#planning_real
Disponible en écriture	Oui

Paramètres spécifiques

Paramètre	Description
datetime-min	Filtre les plannings disponibles après la date spécifiée ou le même jour.
datetime-max	Filtre les plannings disponibles avant la date spécifiée ou le même jour.
valide	Filtre les plannings à ceux qui sont validés (true) ou non validés (false).
valide-datetime-min	Filtre les plannings à ceux qui ont été validés (date disponible dans le champ DateValidation) après la date spécifiée ou le même jour. Ce paramètre doit nécessairement être associé au paramètre valide à true.
valide-datetime-max	Filtre les plannings à ceux qui ont été validés (date disponible dans le champ DateValidation) avant la date spécifiée ou le même jour. Ce paramètre doit nécessairement être associé au paramètre valide à true.
timeZoneOffset	Précise si les heures de début et de fin des éléments de planification doivent s'afficher en tenant compte du fuseau horaire (true) ou sans tenir compte du fuseau horaire (false).

La période passée en paramètre prend en compte l'heure de changement de jour. Si une heure de changement de jour différente de celle du calendrier de la personne est passée en paramètre, cela peut avoir un impact sur la période récupérée. Si une datetime-min est renseignée avec une heure inférieure à l'heure de changement de jour de la personne, alors c'est le jour précédent qui sera considéré pour récupérer les plannings. Si une datetime-max est renseignée avec une heure supérieure à l'heure de changement de jour de la personne, alors c'est le jour suivant qui sera considéré pour récupérer les plannings.

Exemple 1 : Pour une personne dont l'identifiant en base est 16000 avec un calendrier ayant une heure de changement de jour à 04:00, la requête suivante récupère les plannings de cette personne du 19/01/2022 au 27/01/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

Exemple 2 : Pour une personne dont l'identifiant en base est 16000 avec un calendrier ayant une heure de changement de jour à 04:00. La requête suivante :

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

récupère les plannings de cette personne du 19/01/2022 uniquement. En effet pour Timesquare le 20/01/2022 à 00:00 correspond au 19/01/2022 car l'heure de changement de jour est à 04:00.

Eléments

Elément	Description
periode	La période de temps couverte par le planning. Cette période de 24h indique l'horodatage de début et de fin. Elle indique également l'heure de changement de jour associée au calendrier auquel la personne est affectée pour la date du planning. Si la personne n'a pas d'affectation de calendrier pour cette date, c'est l'heure de changement de jour du calendrier par défaut de la structure à laquelle la personne est affectée. Toutes les périodes pour lesquelles il existe un planning sont dans le fuseau horaire du calendrier de la personne sur la période.
jourFixe	Indique si la journée de planning est fixe (true) ou pas (false).
publie	Indique si la journée planning est publiée (true) ou pas (false).
valide	Indique si la journée de planning est validée (true) ou pas (false).
composantsPlanning?	Les composants (le contenu) du planning. Si l'élément n'est pas présent c'est qu'il n'y a pas de composant et qu'aucun ne peut être ajouté. Ça arrive si la personne est hors contrat (elle n'a pas d'affectation de contrat pour la date du début de la période du planning) ou qu'elle a un jour fermé dans son calendrier pour la date.
dateValidation?	La date de la validation si le planning est validé.
dateEchange?	La date d'échange enregistrée s'il y a eu un échange depuis My Timesquare.
planningOrigineEchange?	Si le jour de planning est issu d'un échange, le jour de planning de la personne avec laquelle l'échange a été effectué.
dureeQuotidienne?	La durée quotidienne du planning. Exemple : PT5H30M pour une durée quotidienne de 5h30. L'élément n'est pas présent si elle n'a pas de valeur et dans ce cas on a une durée hebdomadaire à la place. Cette propriété est calculée, elle va être ignorée par le serveur lors d'une modification. La durée comprend les pauses quel que soit le paramétrage en base.
dureeBonification?	La durée de la bonification pour cette journée du planning. Exemple : PT0H15M en XML pour une durée de bonification de 15 minutes.
dureeHebdo?	La durée hebdomadaire. C'est la durée de la semaine qui contient ce planning au cas où la durée quotidienne n'a pas de valeur. Cette propriété est calculée, elle va être ignorée par le serveur lors d'une modification.
timeZoneId	L’identifiant de fuseau horaire. Exemple : Europe/Paris. Pour lire les données en fonction du fuseau horaire de Europe/Lisbonne, il faut ajouter en en-tête de la requête le paramètre User-TimeZoneId avec comme valeur l’identifiant du fuseau de Lisbonne, en l’occurrence Europe/Lisbonne. En l’absence du paramètre en en-tête, les données sont renvoyées brutes (dans le fuseau horaire de la ressource).
typejour	Le type de jour.

Si la personne est hors structure, le Web Service renvoie une erreur 500.

En écriture, il est uniquement possible d'ajouter un composant de planning à la fois par appel au Web Service. Pour ajouter plusieurs éléments de planning, il est nécessaire d'effectuer autant d'appels qu'il y a d'éléments de planning à ajouter.

Le PUT n'est pas autorisé. 

Pour modifier un planning, je dois supprimer le planning avec une requête DELETE puis créer un nouveau planning avec les requêtes POST.

En cas d'écriture de planning, les règles qui s'appliquent sont les mêmes que celles de l’import standard des plannings.

Cas particulier : le commentaire

Le commentaire est un élément de planning un peu différent des autres dans la mesure où il n’est pas lié à un jour de planning (dans son stockage en base). Il est qualifié par une date, une personne concernée et une version de planning.

La création et la modification de commentaires sont gérées par une requête PUT.

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

• Si j'utilise un fichier JSON en entrée, je peux écrire presque tous les caractères possibles dans le string entre "". Exemples de caractères spéciaux en json : nouvelle ligne (\n), citation (").
• Si j'utilise un fichier XML en entrée, les caractères < > & ne peuvent pas être écrits car le document ne sera plus "well-formed" et le parser XML ne sera pas capable de l'interpréter correctement (erreur de parsing). Exemple de caractères spéciaux en XML : nouvelle ligne "&#10;". Dans ce cas, je peux :
  
  • utiliser des séquences "escaped" pour ces caractères telles que "&lt;", "&gt;", "&amp;"
    Exemple :
    <tsq:commentaire> Un commentaire &lt;très intéressant&gt; </tsq:commentaire>
  • placer le texte contenant tous les caractères souhaités dans une section CDATA
    Exemple : 
    <tsq:commentaire><![CDATA[Un commentaire <très> intéressant]]></tsq:commentaire>

Cas particulier : suppression d'une convocation avec ID externe

La suppression d'une convocation avec un identifiant externe se fait avec la requête suivante :

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

En cas de suppression d'une journée de planning contenant une convocation avec un identifiant externe, la convocation est supprimée de toutes les versions de plannings.

Exemples de requêtes

Lecture

Lire le planning réalisé de la personne dont l’identifiant en base est 16000 sur un jour donné (le 23/06/2022)

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

Lire les plannings réalisés de la personne dont l’identifiant en base est 16004 sur une période donnée (du 13/02/2023 au 19/02/2023)

GET /[URI_de_base]/api/feed/personnes/16004/plannings_real?datetime-min=2023-02-13&datetime-max=2023-02-19

Exemple de résultat XML de la requête

Exemple de résultat JSON de la requête

Lire les plannings réalisés validés de la personne dont l’identifiant en base est 16000 sur une période donnée (du 20/06/2022 au 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

Lire les plannings réalisés non validés de la personne dont l’identifiant en base est 16000 sur une période donnée (du 20/06/2022 au 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

Lire les plannings réalisés validés sur une période donnée (du 20/06/2022 au 26/06/2022) pour la personne dont l’identifiant en base est 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

Ecriture

Ajouter une journée de planning contenant une tâche sur un planning réalisé sur un jour donné (le 05/11/2024) pour la personne dont l’identifiant en base est 3051

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

Exemple de fichier XML en entrée

Exemple de fichier JSON en entrée

Ajouter une journée de planning contenant une plage télétravaillée sur un planning réalisé sur un jour donné (le 12/02/2025) pour la personne dont l’identifiant en base est 3039

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

Exemple de fichier XML en entrée

Exemple de fichier JSON en entrée

Ajouter une journée de planning contenant une convocation sur un planning réalisé sur un jour donné (le 05/11/2024) pour la personne dont l’identifiant en base est 3051

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

Exemple de fichier XML en entrée

Exemple de fichier JSON en entrée

Ajouter une journée de planning contenant une indisponibilité sur un planning réalisé sur un jour donné (le 05/11/2024) pour la personne dont l’identifiant en base est 3051

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

Exemple de fichier XML en entrée

Exemple de fichier JSON en entrée

Ajouter une journée de planning contenant un repos sur un planning réalisé sur un jour donné (le 05/11/2024) pour la personne dont l’identifiant en base est 3051

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

Exemple de fichier XML en entrée

Exemple de fichier JSON en entrée

Ajouter une journée de planning contenant un commentaire sur un planning réalisé sur un jour donné (le 05/11/2024) pour la personne dont l’identifiant en base est 3051

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

Exemple de fichier XML en entrée

Exemple de fichier JSON en entrée

Supprimer le planning réalisé sur un jour donné (le 28/10/2024) pour la personne dont l’identifiant en base est 3051

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

Supprimer le planning réalisé sur une période donnée (du 29/10/2024 au 30/10/2024) pour la personne dont l’identifiant en base est 3051

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

Supprimer la convocation sur toutes les versions de planning dont l’identifiant externe est 9911

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

Messages d'erreur fonctionnels

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