Paramétrage avancé des workflows pour les agendas
Pour une utilisation avancée des agendas, il peut être utile de consulter leur API spécifique.
Actions depuis l'agenda
Il est possible de faire avancer le workflow directement depuis un agenda lorsqu'on annule une réservation ou bien que l'on pointe une absence / présence à un événement.
Annulation
L'annulation d'une réservation peut se faire via le workflow, c'est la méthode classique, mais il est également possible d'annuler une réservation (uniquement sur liste principale pour un événement) depuis la vue back-office des agendas (lien « Annuler » à droite des réservations dans la vue back-office d'un agenda). Le clic sur le lien « Annuler » ne déclenche des actions que si l'on a configuré le nécessaire dans le workflow.
La méthode recommandée pour cela est :
- ajouter une action globale (ex. « Annulation depuis l'agenda »), avec un déclencheur de type « Appel externe ». Cette action globale comprendra les actions de workflow souhaitées. Dans « » il faut sélectionner « Appels signés aux API » pour que cet appel externe ne soit pas ouvert à tous.
- Dans l'appel webservice de réservation du créneau, ajouter le paramètre cancel_callback_url avec pour valeur
{{ form_api_url }}hooks/IDENTIFIANT-APPEL-EXTERNE/
Si vous travaillez sur la base d'un workflow comportant déjà une action d'annulation manuelle de la réservation, l'action globale ne devra pas amener à rejouer l'appel webservice d'annulation de réservation, sinon vous provoqueriez une erreur. Pour cela, il est possible de positionner l'appel webservice sur un statut intermédiaire « annulation » par lequel ne passera pas la demande suite à l'appel du déclencheur.
Si un agent tente de passer sur liste prinicpale une réservation depuis l'agenda alors que cancel_callback_url n'est pas défini, l'agent aura un message d'alerte : « Cette réservation n'a pas d'adresse d'annulation connue. ».
Différencier l'annulation d'un évènement entier, d'une réservation individuelle
la variable form_trigger_annulation_backoffice_content_event_cancelled permet désormais de distinguer l’annulation d’un événement entier (valeur True) de celle d’une réservation individuelle, afin d’éviter des traitements inadaptés dans les démarches, notamment le déclenchement des files d’attente.
Pointage d'une absence / présence
Lorsqu'on procède au pointage d'un événement, il est possible de faire avancer le traitement des demandes associées. Pour cela il est nécessaire d'avoir dans le workflow de la demande :
- Dans l'appel webservice de réservation une variable presence_callback_url avec pour valeur {{form_api_url}}hooks/presence/ et une variable absence_callback_url avec pour valeur {{form_api_url}}hooks/absence/
- Une action globale Présence, avec un déclencheur « Appel externe », ayant pour identifiant presence. Dans « » il faut sélectionner « Appels signés aux API » pour que cet appel externe ne soit pas ouvert à tous.
- Une action globale Absence, avec un déclencheur « Appel externe », ayant pour identifiant absence. Dans « » il faut sélectionner « Appels signés aux API » pour que cet appel externe ne soit pas ouvert à tous.
Les appels seront réalisés vers l’ensemble des demandes concernées une fois le pointage de l’évènement validé par un clic sur « Marquer l'évènement comme étant pointé ».
Passage sur liste principale
Le passage sur liste principale d'une réservation peut se faire via le workflow, c'est la méthode classique, mais il est également possible de passer une réservation sur liste principale depuis la vue back-office des agendas (lien « flèche vers le haut » à droite des réservations en liste d'attente dans la vue back-office d'un agenda). Le clic sur le lien « flèche vers le haut » ne déclenche des actions que si l'on a configuré le nécessaire dans le workflow.
La méthode recommandée pour cela est :
- Ajouter une action globale (ex. « Passage sur liste principale depuis l'agenda »), avec un déclencheur de type « Appel externe ». Cette action globale comprendra les actions de workflow souhaitées. Dans « » il faut sélectionner « Appels signés aux API » pour que cet appel externe ne soit pas ouvert à tous.
- Dans l'appel webservice de réservation du créneau, ajouter le paramètre waiting_list_callback_url avec pour valeur
{{ form_api_url }}hooks/IDENTIFIANT-APPEL-EXTERNE/
Si vous travaillez sur la base d'un workflow comportant déjà une action manuelle de passage sur liste principale de la réservation, l'action globale ne devra pas amener à rejouer l'appel webservice de passage sur liste principale, sinon vous provoqueriez une erreur. Pour cela, il est possible de positionner l'appel webservice sur un statut intermédiaire « passage sur liste principale » par lequel ne passera pas la demande suite à l'appel du déclencheur.
Si un agent tente de passer sur liste prinicpale une réservation depuis l'agenda alors que waiting_list_callback_url n'est pas défini, l'agent aura un message d'alerte : « Cette réservation n'a pas d'adresse de confirmation connue, la confirmation doit se faire depuis la demande pour garder les données cohérentes. ».
Liste d'attente (agendas de type « évènements »)
Quand une liste d'attente existe, la réponse à l'appel webservice de réservation fournit quatre informations (attributs) supplémentaires, in_waiting_list, waiting_list_total, waiting_list_reserved, waiting_list_available.
L'attribut in_waiting_list est positionné à True si la demande est placée sur la liste d'attente, à False si elle est sur la liste principale.
{'err': 0, 'booking_id': 14, 'in_waiting_list': True, 'api': {...}}
On pourra donc classer les demandes qui sont sur la liste d'attente dans un statut dédié en utilisant une action de saut automatique vers ce statut, conditionnée par :
form_workflow_data_reservation_response_in_waiting_list == True
(où reservation est l'identifiant de l'appel webservice de réservation)
Pour accepter la réservation et la sortir de la file d'attente, il faut configurer une action webservice en POST vers {{form_workflow_data_reservation_response_api_accept_url}}. Cette action va prendre la demande existante sur la liste d'attente et la déplacer sur la liste principale.
Attention il ne faut pas donner à cet appel webservice qui déplace la demande depuis la liste d'attente vers la liste principale, le même identifiant que celui utilisé pour l'appel webservice initial de réservation, sinon il y aura interférence entre les variables.
Dès que la liste principale est pleine, la variable waiting_list_activated est mise à true, elle empêche les réservations supplémentaires sur la liste principale. Toutefois, dans le cas d'une réservation de plusieurs place en une seule fois, il est possible d'avoir des sur-réservations.
Il est possible de passer une réservation sur liste principale depuis la vue back-office des agendas (lien « flèche vers le haut » à droite des réservations en liste d'attente dans la vue back-office d'un agenda). Ceci est documenté dans les actions depuis l'agenda.
Bascule automatique des réservations en liste d'attente vers la liste principale
Il est possible de basculer automatique des réservations en liste d'attente vers la liste principale. L'option se configure par événement dans les options de l'évènement. Les réservations basculent automatiquement dès que des places se libèrent, par ordre d'arrivée sur la liste d'attente. Il faut que le nombre de places libérées soit suffisant pour qu'une réservation puisse basculer. Le processus de bascule automatique évalue la situation toutes les 5 minutes, la bascule n'est donc pas immédiate dès les désistements. Il tient également compte du délai minimal de réservation et ne bascule donc pas les réservations une fois le délai minimal dépassé. Les demandes sont notifiées de la même façon que lors d'une bascule manuelle depuis la vue back-office des agendas. Si le paramètre waiting_list_callback_url n'a pas été défini sur la réservation, celle-ci ne sera pas basculée automatiquement mais elle ne bloquera pas la bascule des réservations qui la suivent dans la file d'attente.
Réserver plusieurs places sur un même évènement (agendas de type « évènements »)
L'API de réservation permet également en un appel de réaliser plusieurs réservations pour le même évènement, il suffit de passer dans l'URL un paramètre count avec le nombre de places à réserver comme valeur, ex :
{{agendas_url}}api/agenda/IDENTIFIANT-AGENDA/fillslot/{{form_var_event_raw}}/?count={{form_var_nb_places}}
Réserver plusieurs évènements (agendas de type « évènements »)
Il est possible de réaliser une réservation sur plusieurs évènements plutôt qu'un seul.
Le champ « event » que l'on va alors utiliser dans le formulaire sera de type liste à choix multiple pour permettre la sélection de plusieurs évènements. Ensuite dans le workflow, l'action d'appel webservice qui pose la réservation doit utiliser l'URL suivante (noter le « s » final à fillslots) :
{{agendas_url}}api/agenda/REUNIONS-D-INFORMATION/events/fillslots/
Cet appel POST doit inclure dans le corps de la requête, les données envoyées habituellement dans le cas d'une réservation simple, et en plus les données suivantes :
- slots pour les identifiants des évènements à réserver (usuellement {{form_var_event_raw}})
- user_external_id pour lier les réservations à l'usager (usuellement {{ form_user_nameid }})
La réponse de cet appel webservice est très différente de la réponse apportée lors d'une réservation unique, elle inclut seulement :
- booking_count, le nombre d'évènement réservés
- waiting_list_events, le détail des évènements où l'inscription s'est faite sur liste d'attente
- cancelled_booking_count, le nombre d'inscriptions annulées par l'appel
Modifier les réservations
Si une nouvelle réservation multiple est effectuée pour le même usager, elle annule et remplace la précédente : si une première réservation a permis de sélectionner un évènement le lundi et un autre le mardi, une seconde réservation ne retenant que l'évènement du mardi, annulera l'inscription du lundi.
Ainsi, pour annuler toutes les réservations d'un coup, il suffit d'effectuer une nouvelle réservation avec le paramètre slots vide.
Récupérer les réservations
Pour récupérer les évènements réservés par un usager, il faut passer par un appel webservice GET à /api/agenda/SLUG-DE-LAGENDA/datetimes/, en passant le paramètre ?user_external_id=xxx. Tous les évènements sont renvoyés.
Les évènements réservés comportent une clé booked_for_external_user qui vaut main-list pour les évènements pour lesquels l'usager est réellement inscrit, ou waiting-list pour les évènements pour lesquels l'usager est sur liste d'attente.
Pré-bloquer les créneaux / places
- Dans l'action webservice de réservation, ajouter des données à envoyer dans le corps de la requête :
- lock_code : {{ session_hash_id }}
- confirm_after_lock : true
- Créer un nouvel appel webservice POST identique à l'appel de réservation mais envoyant seulement une donnée « lock_code » (et rien d'autre) remplie par {{ session_hash_id }}. Donnons lui l'identifiant « preblocage ».
- Ajouter une condition de sortie de page sur la page qui permet de choisir le créneau ou la place :
webservice.preblocage.err == 0 avec comme message d'erreur « Choisissez un nouveau créneau » - Utiliser une source de données personnalisée pour le champ liste affichant les événements / créneaux. Elle doit en effet contenir l'information ?lock_code={{ session_hash_id }}. Vous pouvez par exemple dupliquer la source de donnée automatique de l'agenda pour lui ajouter ce paramètre.
Gestion des erreurs
Lors d'une réservation une erreur peut être retournée, indiquant que l'évènement est complet, ou que le créneau horaire a, entretemps, été occupé.
Par exemple : {'err': 1, 'reason': 'sold out'}
Pour gérer cela, dans le workflow de traitement, il faut utiliser le paramètre « Action en cas d'erreur applicative » pour placer la demande dans un statut particulier, pour prévenir l'usager de l'échec. (alternativement quand même, il est possible de gérer manuellement l'erreur, en créant un saut basé sur la condition reservation_app_error_code != 0).
Pour l'appel d'annulation, une erreur {'err': 1, 'reason': 'already cancelled'} sera retournée si la réservation a déjà été annulée.
Pour l'appel d'acceptation de réservation (de bascule hors de la liste d'attente), pour une réservation qui aurait été annulée le retour sera {'err': 1, 'reason': 'booking is cancelled'} et pour une réservation qui ne serait pas dans la liste d'attente, ce sera {'err': 2, 'reason': 'booking is not in waiting list'}.