Export et envoi de fichiers ICS

Deux façons d'utiliser le format ICS avec Publik : exporter la liste des rendez-vous vers un logiciel d'agenda externe (Zimbra, Outlook, Thunderbird…), ou envoyer une invitation ICS à l'usager pour qu'il l'ajoute à son agenda personnel.

Export ICS vers un logiciel externe

Il est possible d'exporter la liste des rendez-vous vers un logiciel d'agenda externe (Zimbra, Outlook, Thunderbird, etc.) via une vue ICS des demandes.

Construire l'URL d'accès

Le logiciel externe accède aux rendez-vous via une URL dont le format est le suivant :

{{eservices_url}}api/forms/IDENTIFIANT-DU-FORMULAIRE/ics/IDENTIFIANT-CHAMP-DATE?api-user=IDENTIFIANT-API&api-key=CLÉ-API

L'URL ci-dessus retourne uniquement les demandes en attente. Il est possible d'inclure aussi les demandes traitées en créant une vue personnalisée, ou en ajoutant à l'url un paramètre filter=all

{{eservices_url}}api/forms/IDENTIFIANT-DU-FORMULAIRE/ics/IDENTIFIANT-CHAMP-DATE?api-user=IDENTIFIANT-API&api-key=CLÉ-API&filter=all

Il est possible de remplacer, dans l'URL, l'identifiant du champ date par celui d'un champ texte contenant une date, par exemple une donnée de traitement où le jour et l'heure du rendez-vous seraient stockés.

Obtenir un identifiant et une clé API

Pour construire l'URL ci-dessus, vous avez besoin d'un identifiant et d'une clé d'accès API.

Envoyer une invitation ics par courriel

Objectif : permettre à un usager d'ajouter automatiquement son rendez-vous à son agenda personnel en lui envoyant un fichier ICS en pièce jointe.

Situation de départ

L’usager prend un rendez-vous. Le rendez-vous s’affiche dans l’agenda en back-office. Un courriel est envoyé à l’usager avec les informations du rendez-vous dans le corps du message.

Explications

Dans l’agenda de l’agent, en back-office, le créneau sera réservé avec les informations label et user_name (forme : label – user_name). Le lien sur l’intitulé est généré grâce à backoffice_url.

Modifications à apporter

1. Le fichier ICS généré est une donnée de traitement, on crée donc une nouvelle donnée de traitement de type fichier :
   • nom : par exemple « Fichier ics »
   • type : fichier
   • identifiant : par exemple « fichierics » ({{ form_var_fichierics }})

2. On génère l’ics à partir du statut « Enregistrement du rendez-vous ». Pour cela, on ajoute une action « webservice » :

   • Nom : génération ics

   • url : {{form_workflow_data_reservation_response_api_ics_url}} ; quelques explications :

     • reservation est l’identifiant de l’appel webservice de l’agenda ; peut varier selon les workflows

     • response est le retour de l’appel au webservice (ce nom est statique et ne change jamais)

     • api_ics_url est le nom de la donnée générée par le webservice ; ce nom ne change jamais

   • Méthode : GET

   • Données à envoyer en paramètres de l'URL :

     • comment : il s’agit d’un commentaire à propos du rendez-vous. Le champ commentaire n’est pas affiché par tous les agendas, n’indiquez rien d’important dans ce champ (utilisez le champ description pour cela).

     • description : c’est la description du rendez-vous. Indiquez par exemple « rendez-vous en mairie pour votre renouvellement de passeport »

     • location : indiquer ici le lieu du rendez-vous (par exemple : Mairie de Fondcomb). Si vous indiquez une adresse précise, certains logiciels de messagerie proposent le lien vers une carte.

     • url : lien vers la démarche par exemple ({{form_url}})

     • tous les paramètres ci-dessus sont facultatifs, mais nous recommandons de renseigner au moins description et location.

   • Type de réponse : choisissez « fichier joint »
   • Identifiant : indiquez un identifiant, par exemple : « ics ». Cet identifiant sera utilisé comme nom de fichier (par exemple si l’identifiant est « fichier_ics », le fichier joint se nommera fichier_ics.ics)
   • Enregistrez dans les données de traitement : choisissez la donnée de traitement nouvellement créée, dans notre exemple « Fichier ics »

3. Joignez l’ics généré au courriel :

   • allez dans l’action « courriel » dans le statut « rendez-vous réservé ». Sous le corps du message, « Fichiers attachés », choisissez la donnée de traitement concernée, par exemple « Fichier ics ».

4. Testez !

   1. Remplissez la démarche avec une adresse courriel existante

   2. le courriel reçu contient l’invitation :

      

   3. affichage du rendez-vous dans l’agenda :

      

Aller plus loin : changer le titre du rendez-vous dans l’invitation et ajouter une description.

Il peut être intéressant d’avoir un intitulé différent pour l’agent en back-office et pour l’usager dans son agenda, et d'ajouter une description du rendez-vous.

Pour personnaliser le nom de l’événement pour l’usager, on utilise le paramètre « user_display_label » :

1. dans le statut « Enregistrement du rendez-vous », allez dans la première action « webservice », nommée dans l’exemple « Réservation ».
2. dans les données à envoyer dans le corps de la requête, ajoutez le paramètre « user_display_label » et indiquez comme valeur le nom de l’événement pour l’usager, le titre qu’il verra apparaître dans son agenda. Par exemple : « rendez-vous Mairie pour passeport »
3. testez !

Pour personnaliser la description de l’événement, on utilise le paramètre « description » :

1. dans le statut « Enregistrement du rendez-vous », allez dans la première action « webservice », nommée dans l’exemple « Réservation ».
2. dans les données à envoyer dans le corps de la requête, ajoutez le paramètre « description » et indiquez comme valeur une description du rendez-vous (raisons, pièces à apporter...). Par exemple : « Pensez à ramener un justificatif de domicile. »
3. testez !

⬇️ Fichiers à télécharger

• Agenda (.json)
• Formulaire (.wcs)
• Workflow (.wcs)