Documentation en ligne

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 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 :
  1. 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 « » il faut sélectionner « Appels signés aux API » pour que cet appel externe ne soit pas ouvert à tous.
  2. 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/ 
Si vous travaillez sur la base d'un workflow comportant déjà une action d'annulation manuelle de la réservation, l'action globale ou le saut automatique ne devront pas amener la demande sur le statut comportant ce webservice d'annulation de réservation sinon vous provoqueriez une erreur. Il faut positionner l'appel webservice d'annulation manuelle sur un statut intermédiaire « annulation » qui sera court-circuité par le saut via déclencheur.
Si on tente d'annuler un rendez-vous depuis l'agenda alors que cancel_callback_url n'est pas renseigné, on obtiendra 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 :

  1. 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/
  2. 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.
  3. 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é ».

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.

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

Par défaut, lorsqu'un créneau ou une place sont sélectionnés via un formulaire, rien ne se passe avant la validation du formulaire. Si bien que pour des situations concurrentielles où plusieurs usagers sélectionnent le même créneau ou la même place, seul le premier à valider sera servi. Il est possible de pré-bloquer dès la sélection dans le formulaire, pour cela il faut :
  • 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.
Cela permet de poser un verrou temporaire : le créneau ou la place seront bloqués pendant 10 minutes. Durant ce laps de temps, le créneau ne sera plus considéré comme disponible, bien que la réservation ne soit pas encore définitive.
Pour avoir davantage d'information vous pouvez consulter le tutoriel sur le sujet.

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'}.

Dernière mise à jour le 16/05/2025 11:34 — Éditer