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.
Annulation depuis l'agenda
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 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 » n'est effectif que si l'on a configuré le nécessaire dans le workflow.
- ajouter une action globale (ex. « Annulation depuis l'agenda »), avec un déclencheur de type « Appel externe ». Cette action doit comprendre un saut automatique vers un statut permettant d'informer l'utilisateur de l''annulation du rendez-vous (mais sans appel webservice d'annulation, cf. infra)
- dans le webservice de réservation du créneau, vérifier que l'URL à passer dans le paramètre cancel_callback_url est {{form_api_url}}hooks/IDENTIFIANT-APPEL-EXTERNE/
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.
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.
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'}.