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 vers un calendrier d'exceptions Publik.
• Envoyer une invitation ICS à l'usager pour qu'il l'ajoute à son agenda personnel

Export ICS d'une liste de rendez-vous

Il est possible d'exporter la liste des rendez-vous via une vue ICS des demandes de RDV.

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>?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>?api-user=IDENTIFIANT-API&api-key=CLÉ-API&filter=all

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 réservation du rendez-vous dans 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)