Documentation en ligne

Gestion d'agendas, réservations et rendez-vous

La gestion d'agendas est utilisée pour gérer la prise de rendez-vous ou des inscriptions à des événements. Le paramétrage des agendas est accessible depuis le menu « Agendas », les réservations et leur gestion s'organisent via les formulaires et les workflows.

Il s'agit d'abord de créer le ou les agendas souhaités, en leur donnant un libellé et en précisant s'il s'agit d'un agenda pour des événements (par exemple « Stages d'été ») ou pour des rendez-vous (par exemple « Rencontre avec le Maire ») ainsi que les rôles d'édition et de visualisation de l'agenda (par défaut tous les agents ayant accès au paramétrage des agendas ont accès à l'ensemble des agendas).

Événements

Pour un agenda de type « événements », il faut y ajouter les événements adéquats, en précisant la date, le nombre de places disponibles et le nombre de places éventuelles en liste d'attente, ainsi qu'un libellé (optionnel), pour permettre ainsi aux usagers de choisir entre « Multisport, du 4 au 8 juillet (12 places disponibles) », « Natation, du 4 au 8 juillet (8 places disponibles) » et d'autres.

Sur la page d'un agenda, un récapitulatif des événements est repris, ainsi que le nombre de places déjà réservées.

Rendez-vous

Pour un agenda de type « rendez-vous », il faut définir les plages horaires concernées (par exemple, « le lundi de 13 à 18 heures et le jeudi de 19 à 22 heures ») et un ou plusieurs types de rendez-vous pour lesquels il faudra définir la durée type. Il est possible de créer plusieurs guichets permettant ainsi de gérer plusieurs guichets physiques qui vont proposer les mêmes types de rendez-vous, dans la même salle. Chaque guichet peut contenir des exceptions aux rendez-vous, qui peuvent être ajoutées manuellement ou importées depuis un fichier iCal (.ics). Les exceptions récurrentes ne sont pas prises en charge pour le moment. Vous pouvez télécharger le fichier des jours fériés en France jusqu'en 2030 sur ce lien.

Lorsque vous avez défini plusieurs type de RdV différents dans un agenda, il peut être utile de lister les différents types de RdV (RdV pour 1 personne, RdV famille...) dans un formulaire. Pour lister les types de RdV dans un champ de type liste dans un formulaire, vous pouvez faire appel à la source de données JSON suivante :

    {{agendas_url}}api/agenda/IDENTIFIANT-AGENDA/meetings/
Pour importer un fichier iCal (.ics) permettant de générer des exceptions, il faut cliquer sur l'icône https://i.imgur.com/UqjNMl4.png qui se trouve à droite de « Exceptions » en bout de ligne. Il est également possible à cet endroit d'indiquer l'URL d' un calendrier distant reprenant les exceptions aux horaires d'ouverture, et mettant ainsi ces dernières automatiquement à jour dans l'agenda.

Délais d'enregistrement

Il est possible dans les options d'un agenda de définir un nombre de jours minimal et un nombre de jours maximal, pour encadrer la période de réservation, pour, par exemple, ne plus permettre de s'inscrire trois jours avant l'événement, ou ne pas permettre l'inscription à un rendez-vous six mois plus tard. Il faut entendre ces journées en périodes de 24 heures, aussi si réglage d'un délai de réservation minimal à 1 jour, un créneau pourra être réservé le lendemain (J+1) à 11h00 si l'usager complète le formulaire à 10h50 (jour J).

Intégration avec les formulaires et les workflows

Dans l'ensemble des exemples ci-dessous, on suppose que le nom du service de gestion des agendas est le nom par défaut : « agendas ». Si ce nom a été modifié vous devez remplacer {{agendas_url}} par {{nouveau-nom_url}} dans tous les exemples.

Formulaire

Il s'agit d'abord de présenter à l'usager la liste des événements/activités ou créneaux horaires disponibles. Pour cela il faut créer dans un formulaire un champ de type liste à qui on donne un nom de variable (par exemple « event ») et que l'on alimente (dans les paramètres avancés du champ) par une « source de données » de type JSON.

Pour les agenda de type « rendez-vous », il est possible de choisir un style mieux adapté à la prise de rendez-vous en renseignant « template-meetings » dans le paramètre « Classes supplémentaires pour les styles CSS ».  Dans « Paramètres supplémentaires » , le réglage « Afficher les éléments désactivés » (désactivé par défaut) permet d'afficher, en grisé, les créneaux déjà réservés, un tel créneau n'est pas pour autant réservable.

Une fois que l'on a sélectionné « JSON » dans la liste des sources de données, il faut saisir une URL qui dépend du type d'agenda, événements ou rendez-vous.

Agenda « événements »

Pour un agenda de type « événements », qui aurait l'identifiant REUNIONS-D-INFORMATION (celui-ci est créé sur base du titre et repris sur la page de l'agenda), l'URL de la source de données sera :

  {{agendas_url}}api/agenda/REUNIONS-D-INFORMATION/datetimes/

Agenda « rendez-vous »

Pour un agenda de type « rendez-vous », qui aurait l'identifiant « RENDEZ-VOUS-PASSEPORT », il faut préciser à la fois l'identifiant de l'agenda et celui du type de rendez-vous (ici « TYPE-DE-RDV », également repris sur la page de l'agenda), et l'URL de la source de donnée sera alors :

  {{agendas_url}}api/agenda/RENDEZ-VOUS-PASSEPORT/meetings/TYPE-DE-RDV/datetimes/

Workflow

Ensuite, il faut dans le workflow à un moment ajouter une action d'appel webservice, configurée en POST, pour marquer la place comme réservée. L'URL à utiliser dans cet appel, en considérant que le champ présentant le choix avait comme identifiant «EVENT », sera {{form_var_EVENT_api_fillslot_url}}.

Il est techniquement possible d'assembler manuellement l'adresse, selon la forme {{agendas_url}}api/agenda/IDENTIFIANT-DE-L-AGENDA/fillslot/{{form_var_event_raw}} mais cette pratique est déconseillée.

Afin de permettre un lien depuis l'agenda vers la demande à l'origine de la réservation, l'appel webservice doit inclure les « Données à envoyer dans le corps de la requête » suivantes :

  • label pour le libellé du formulaire (usuellement {{form_name}}),
  • user_name pour le nom de l'usager (usuellement {{form_user_display_name}}),
  • backoffice_url pour la demande vers laquelle créer un lien (usuellement {{form_url_backoffice}}),
  • user_display_label pour le libellé qui sera présenté à l'usager (par exemple « Rendez-vous passeport »).

L'appel ne doit pas reprendre intégralement  les données de la demande (décocher « Envoyer les données du formulaire »).

L'appel pourra retourner une erreur {'err': 1, 'reason': 'sold out'} mais plus souvent, ça retournera l'identifiant de la réservation, par exemple :

  {'err': 0, 'booking_id': 14}

Ainsi, en ayant attribué un nom de variable à l'appel webservice, par exemple « reservation », on aura désormais cet identifiant de réservation accessible dans {{reservation_response_booking_id}}.  Aussi, pour un agenda de type « rendez-vous », la réponse contiendra l'information sur le guichet attribué, par exemple :

  {'err': 0, 'booking_id': 14, 'desk': {'label': 'Guichet C', 'slug': 'guichet-c'}}

Ces réponses contiendront également les adresses à appeler pour agir par la suite sur la réservation, pour demander l'annulation (cancel_url) ou pour accepter une demande ayant été mise en liste d'attente (accept_url).

  {'err': 0, 'booking_id': 14, 'api': {'cancel_url': 'https://...'}}

Ces adresses peuvent alors être utilisés dans un appel webservice, un POST (n'incluant pas les données du formulaire) vers : {{reservation_response_api_cancel_url}}.

Information sur le statut (agendas de type « événements »)

Pour les agendas de type « événements », il existe également un webservice pour connaitre le nombre de places (totales, libres ou réservées), cela passe par l'enregistrement d'un nouvel appel dans le catalogue des webservice,  avec comme URL :

  {{agendas_url}}api/agenda/REUNIONS-D-INFORMATION/status/{{form_var_event_raw}}/

Et également en spécifiant reservations comme identifiant à cet appel. Il devient alors possible d'utiliser « reservations » dans par exemple un commentaire :

  Places dispos : {{webservice.reservations.places.available}}

À propos des appels, plutôt que mettre l'identifiant de l'agenda dans tous les appels, on pourrait passer ça via une option de workflow, qui pourrait être une liste alimentée depuis {{agendas_url}}api/agenda/ (qui reprend la liste des agendas).

Liste d'attente (agendas de type « événements »)

Si un événement dispose d'une liste d'attente, le retour d'une réservation peut contenir un attribut in_waiting_list à True.

  {'err': 0, 'booking_id': 14, 'in_waiting_list': True, 'api': {...}}

Pour changer de statut vers un statut d'attente, une condition sur reservation_response_in_waiting_list peut alors être posée.

Dans le statut d'attente, pour accepter la réservation, la sortir de la file d'attente, un appel à l'API « accept » doit être fait, un POST vers {{reservation_response_api_accept_url}}.

Quand une liste d'attente existe, le webservice de statut fournit trois informations supplémentaires, waiting_list_total, waiting_list_reserved, waiting_list_available.

Réservation multiple (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/REUNIONS-D-INFORMATION/fillslot/{{form_var_event_raw}}/?count={{form_var_nb_places}}

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

Visualisation des rendez-vous et export .ics

Envoyer le fichier .ics d'un rendez-vous par courriel

Il est possible de joindre à un courriel un fichier .ics d'un rendez-vous. La personne recevant ce courriel dans Outlook n'aura qu'à cliquer sur le fichier .ics pour mettre le rendez-vous dans son agenda. Cela se fait en trois étapes dans le workflow :

  1. Création d'une donnée de traitement de type fichier
  2. Création d'une action webservice basé sur l'action webservice ayant servi à prendre le rendez-vous. Il faut paramétrer plusieurs choses
    1. URL : si l'identifiant de l'appel ayant servi à prendre le RV est reservation, l'url à utiliser sous forme de gabarit sera {{reservation_response_api_ics_url}}
    2. Données à envoyer en paramètre : vous pouvez transmettre des valeurs pour les données suivantes : comment, description, location, url
    3. La méthode doit être « GET »
    4. Le type de réponse doit être « Fichier joint »
    5. Dans « Enregistrer dans les données de traitement » vous devez sélectionner le fichier créé précédemment
  3. Création d'une action courriel dans laquelle on va joindre la donnée de traitement fichier, dûment remplie par l'action webservice

Fichier .ics de la liste des rendez-vous

Publik offre une vue sur les agendas directement depuis son backoffice, il suffit d'attribuer les droits de visualisation sur l'agenda concerné aux rôles autorisés. Les personnes autorisées disposeront alors d'une vue calendaire des rendez-vous, vue quotidienne ou mensuelle.

Alternativement, il est possible d'exporter la liste des rendez-vous vers un logiciel d'agenda type Zimbra ou Outlook, à travers une vue « ics » des demandes.

Pour ce faire, il faut construire une adresse sur la forme

{{eservices_url}}api/forms/IDENTIFIANT-DU-FORMULAIRE/ics/IDENTIFIANT-DONNEE-DE-TRAITEMENT

Par exemple : https://demarches.example.fr/api/forms/prise-de-rendez-vous-passeport/ics/rdv_datetime.
L'identifiant du formulaire est ici prise-de-rendez-vous-passeport. rdv_datetime est l'identifiant de la donnée de traitement dans laquelle on a stocké le jour et l'heure du rendez-vous sous forme structurée (identifiant sans préfixe form_var_ donc).
données de traitement
Pour obtenir le jour et l'heure sous forme structurée et pour un rendez-vous dont le créneau aurait été sélectionné dans un champ ayant comme identifiant event, la donnée de traitement rdv_datetime serait alimentée par la variable form_var_event_datetime.
affectation de la valeur à la donnée de traitement

Il manquera encore au programme tiers les autorisations nécessaires pour accéder au webservice, il faudra demander à l'administrateur de Publik d'ajouter, dans une section [api-http-auth-ics] du site-options.cfg, une entrée username = password, pour ouvrir l'accès au webservice et il faudra également ajouter à l'URL un paramètre email correspondant à un usager habilité à accéder aux demandes.

Dernière mise à jour le 16 avril 2019 18:35 — Éditer