# Pour aller plus loin

Pour aller plus loin

Des ressources complémentaires pours les personnes (administrateurs fonctionnels) qui construisent des démarches dans Publik.

RechercheRecherche

* Liste des connecteurs
* Dématérialiser une démarche
* Tester une démarche
* Mises à jour
* CNIL, RGPD et vie privée
* Une GRC n’est pas un logiciel de gestion de courrier (GEC)
* RGAA
* Une GRC n’est pas un logiciel de gestion de la relation client (CRM)
* Écoconception
* Référentiel simplicité
* Comparatif Publik / demarches-simplifiees.fr

# Utiliser les filtres Django pour manipuler les données

Utiliser les filtres Django pour manipuler les données

Introduction aux filtres Django

Les filtres permettent de transformer ou de manipuler les données dans Publik. Ils sont utilisés directement dans les gabarits Django via le symbole|, appelé pipe (prononcépaïpe).

Syntaxe générale :form_var_chose|nom_du_filtre

Exemple simple

Si vous souhaitez convertir une valeur en minuscules :{{ form_var_titre|lower }}

Combinaison de filtres

Les filtres peuvent être chaînés :{{ form_var_title|first|lower }}Cela extrait le premier caractère deform_var_titleet le convertit en minuscule.

Filtres avec paramètres

Certains filtres acceptent des paramètres :form_var_chose|nom_du_filtre:parametre

Le paramètre peut être un nombre (sans guillemets) :form_var_chose|add:2

Le paramètre peut être une chaîne de caractères (encadrée par des guillemets) :form_var_chose|startswith:"toto"

En savoir plus

Cette page ne détaille que les filtres classiquement utilisés avec Publik. La façon la plus complète de comprendre l'utilisation des filtres et de regarder ladocumentation Django en la matière.

Il existe une page spécifique de la documentation Publik pour lesfiltres de requête.

Types de données

Dans les gabarits ou les conditions Django, il est souvent nécessaire de convertir une donnée d’un type à un autre, par exemple vers une date ou un nombre. Ces conversions permettent de réaliser des calculs, des comparaisons, ou de gérer plus facilement le format d’affichage. Pour cela, on utilise des filtres. Voici les principaux types de données gérés par Publik :

* chaîne de caractères: type par défaut pour toutes les données de Publik ;
* date: utilisé pour les champs de type « date » ;
* decimal: nombre à virgule, utile pour les comparaisons et les calculs de tarifs ;
* datetime: combinaison de la date et de l’heure, utilisée notamment pour la gestion des rendez-vous ;
* time: heure seule.

Conversion de types

La syntaxe pour convertir une variable est la suivante :form_var_chose|<type>

<type>pouvant être :date,decimal,datetimeoutime.

Lorsque la conversion échoue, Django retourne une chaîne de caractères vide. Publik respecte ce principe.

Exemples pratiques

* form_var_date|date--> transforme la valeur en date
* form_var_date|datetime--> transforme la valeur en date + heure
* form_var_tarif|decimal--> transforme la valeur en nombre

Précisionsur les nombres, le filtre|decimal:2donne un nombre à 2 chiffres après la virgule maisne transforme pasform_var_tarifen nombre.

Manipuler et formater les dates

Modifier le format d'affichage

Le filtre|datepermet de personnaliser l’affichage des dates :{{ today|date:"Y-m-d" }}--> affiche la date au format ISO, par exemple 2025-01-07{{ today|date:"d/m/Y" }}--> affiche la date au format plus habituel 07/01/2025

Calculs d'âge

Les filtres suivants calculent l'âge d'une date par rapport à aujourd'hui :

* En jours :form_var_date|age_in_days--> le résultat est un nombre, qui est négatif quand l'évènement est dans le futur
* En jours ouvrés :form_var_date|age_in_working_days
* En jours ouvrés, samedi inclus :form_var_date|age_in_working_days_with_saturday
* En mois :form_var_date|age_in_months
* En années :form_var_date|age_in_years
* En heures :form_var_date|age_in_hours--> fonctionne également avec une variable au format datetime. Cela permet par exemple de déclencher l'envoi d'un courriel exactement 48 heures avant un rendez-vous.

Les filtresage_in_*ci-dessus permettent de calculer l'âge en fonction de la date du jour. Il est également possible de calculer le nombre d’heures, de jours, de mois ou d’années entre deux dates. Pour réaliser ces calculs, utilisez la syntaxe suivante :form_var_date1|age_in_years:form_var_date2--> ici calcule le nombre d'années, years pouvant être remplacé selon l'unité voulue

Dans unecondition Django:form_var_datenaissance|age_in_years >= 18--> vraie si la personne est majeure

Dans ungabarit:Vous avez aujourd'hui{{ form_var_datenaissance|age_in_years }}ans.{% if form_var_datenaissance|age_in_years >= 18 %}Vous êtes majeur·e.{% endif %}

Ajout de jours ou d'heures à une date

Vous pouvez ajouter ou retirer des jours, des heures, ou des minutes à une date donnée grâce à des filtres spécifiques :

* form_var_date|add_days:3--> ajoute 3 jours àform_var_date
* form_var_date|add_hours:-6--> retranche 6 heures àform_var_date
* form_var_date|add_minutes:15--> ajoute 15 minutes àform_var_date

Un nombre négatif permet de retirer des jours, des heures ou des minutes.

Ajout de jours ouvrés

Pour ajouter des jours ouvrés, utilisez les filtres suivants :

* form_var_date|add_working_days:5--> ajoute 5 jours ouvrés àform_var_date
* form_var_date|add_working_days_with_saturday:5--> ajoute 5 jours ouvrés en incluant le samedi àform_var_date

Ajustement des jours ouvrés

D'autres filtres permettent de travailler avec les jours ouvrés :

* form_var_date|is_working_day--> indique si la date est un jour ouvré
* form_var_date|is_working_day_with_saturday--> indique si la date est un jour ouvré, samedi inclus
* form_var_date|adjust_to_working_day--> affiche le prochain jour ouvré
* form_var_date|adjust_to_working_day_with_saturday--> affiche le prochain jour ouvré en incluant le samedi

Comparer deux dates

Utilisez les opérateurs standards pour comparer deux dates :

* form_var_date1 != form_var_date2--> Les deux dates sont différentes
* form_var_date1 > form_var_date2--> date1 est strictement après date2
* form_var_date1 <= form_var_date2--> date1 est avant ou égal à date2

Attention: Si cela ne fonctionne pas, vérifiez que vos variables sont bien des dates et utilisez si nécessaire le filtre|datepour les convertir.

Filtres pour les opérations mathématiques

Les filtres suivants permettent d'effectuer des calculs simples. Ils retournent un nombre (ou zéro si le calcul ne peut pas être effectué) :

Calculs de base :

xxx|add:2--> ajoute 2 à xxxxxx|subtract:2--> soustrait 2 de xxxxxx|multiply:2--> multiplie xxx par 2xxx|divide:2--> divise xxx par 2xxx|modulo:yyy--> renvoie le reste de la division de xxx par yyy

Comparaison :

xxx|decimal > 2--> vérifie si xxx est supérieur à 2

Utilisation avec des variables :

Les filtres acceptent également des variables comme arguments :

"2"|add:xxx--> ajoute la valeur de xxx à 2xxx|subtract:yyy--> soustrait la valeur de yyy à la valeur de xxx

Division par zéro :

xxx|divide:0--> en cas de division par zéro, le filtre retourne une chaîne vide

Ordre d'exécution des filtres :

Les filtres sont appliqués de gauche à droite, sans parenthèses pour structurer les priorités. Par exemple :

form_var_prix1|add:form_var_prix2|multiply:1.2|decimal:2--> additionne deux prix, puis calcule la TVA, et enfin formate le résultat avec deux décimales.

Pour gérer des calculs complexes (l'usage de parenthèse n'étant pas autorisé), il faut passer par des résultats intermédiaires :

{% with var1=prix1|multiply:1.2 var2=prix2|multiply:1.055 %}{{ var1|add:var2|decimal:2 }}{% endwith %}--> additionne deux prix, calculés avec des TVA différentes.

Arrondir un nombre :

xxx|ceil--> arrondit au nombre entier supérieurxxx|floor--> arrondit au nombre entier inférieur

Valeur absolue :

xxx|abs--> renvoie toujours une valeur positive

Comparer des nombres

Utilisez les opérateurs standards pour comparer deux nombres :

* form_var_nombre1!= form_var_nombre2--> Les deux nombres sont différents
* form_var_nombre1 > form_var_nombre2--> nombre1 est strictement supérieur à nombre2
* form_var_nombre1<= form_var_nombre2--> nombre1 est inférieur ou égal à nombre2

Attention: Si cela ne fonctionne pas, vérifiez que vos variables sont bien des nombres et utilisez si nécessaire le filtre|decimal.

Transformer un nombre en jours, heures et minutes

Le filtre|durationpermet de convertir une durée exprimée en minutes en un format lisible, soit en heures et minutes, soit en jours, heures et minutes. Voici comment l'utiliser :

{{ form_var_mon_nombre|duration }}--> siform_var_mon_nombrecontient 125, cela renverra :2h05.{{ form_var_mon_nombre|duration:"long" }}--> Siform_var_mon_nombrecontient 125, cela renverra : 2 heures et 5 minutes.

Filtres sur les chaînes de caractère

Filtre | Description
--------------------
|startswith:"toto" | renvoie True (vrai) si la chaîne de caractère commence par "toto", False sinon
|endswith:"toto" | renvoie True (vrai) si la chaîne de caractère se termine par "toto", False sinon
|lower | permet d'obtenir une variable en minuscules
|upper | permet d'obtenir une variable en majuscules
|capfirst | permet d'obtenir une chaîne avec une majuscule sur la première lettre
|title | permet d'obtenir une variable comprenant une majuscule aux premières lettres de chaque mot
|slugify | permet d'obtenir une chaîne en minuscules non accentuées, espaces convertis en tirets
|unaccent | permet d'obtenir une chaîne de caractères non accentués
|default:"" | permet d'obtenir un texte (chaîne vide, en l'occurence) si la variable n'est pas spécifiée (serait "None" sinon)
|removeprefix | permet de supprimer un préfixe.{{ "Ma valeur"|removeprefix:"Ma "}}va donnervaleur
|removesuffix | permet de supprimer un suffixe. {{ "Ma valeur"|removesuffix:" valeur"}}va donnerMa
|strip | permet de retirer les espaces en début et fin de chaîne
|linebreaks | permet de forcer les retours à la ligne dans un texte contenant plusieurs paragraphes, il produit de l’HTML qui doit donc être marqué par |safe pour être interprété comme tel
|is_empty | vérifie si la variable existe, ou si la valeur existe et est non vide
|as_numeral | convertit un nombre en toutes lettres ("42", devient "quarante-deux")
|as_numeral_currency | convertit un nombre en toutes lettres avec les centimes ("42,50", devient "quarante-deux et cinquante centimes")
|sha256 | pour obtenir un hachage selon la fonction SHA256.
|integer | pour obtenir un entier (principalement utile lors d'appels webservices)
|phonenumber_fr | convertit un numéro de téléphone français en 5 groupes de 2 chiffres séparés entre eux par un espace ("0123456789", devient "01 23 45 67 89"). Le filtre prend en option le séparateur des paires de chiffres :|phonenumber_fr:""donnera "0123456789"
|is_french_mobile_phone_number | vérifie si la variable pointe un numéro de téléphone mobile (06 ou 07)

Lors de l'utilisation defirstof, il est important de noter que les filtres s'appliquent directement aux valeurs, y compris si celles-ci sontNone. Cela peut transformer une valeur vide en une chaîne non vide.

{% firstof form_var_nom1|upper form_var_nom2|upper %}

Dans cet exemple, siform_var_nom1est vide (None), le filtreupperrenverra la chaîne"NONE"au lieu de passer àform_var_nom2.

Pour éviter ce comportement et garantir un résultat attendu, il est recommandé d'utiliser une des approches suivantes :

* Appliquer un filtredefaultavantupper:Cela permet de remplacer les valeursNonepar une chaîne vide avant de les convertir en majuscules.{% firstof form_var_nom1|default:""|upper form_var_nom2|default:""|upper %}
* Combinerfirstofavec une variable temporaire :Ici, la transformation en majuscules est effectuée après la sélection de la première valeur non vide.{% firstof form_var_nom1 form_var_nom2 as nom %}{{ nom|upper }}

Filtres sur les blocs de champs

Obtenir la liste des valeurs d’un champ

Le filtre|getlistextrait toutes les valeurs d’un champ spécifique au sein d’un bloc de champs.

Exemple :Pour afficher les valeurs du champnomdans un bloc de champs nommémonbloc:form_var_monbloc|getlist:"nom"

Faire la somme des valeurs d’un champ

Le filtre|sumpermet d’additionner les valeurs d’un champ dans un bloc de champs ou dans une liste de nombres.

Exemple avec un bloc de champs :Pour calculer la somme des valeurs du champmontantdans un bloc de champs nommémonbloc:form_var_monbloc|getlist:"montant"|sum

Exemple avec une liste obtenue via un filtre de requête :Pour additionner les valeurs du champmontantd’un modèle de fiche nommésubventions:cards|objects:"subventions"|getlist:"montant"|sum

Autres filtres spécifiques

|splittransforme la valeur d'une variable en liste en utilisant un séparateur.Par défaut, le séparateur est l’espace.Exemple :"un deux trois"|split→["un", "deux", "trois"].Vous pouvez définir un autre séparateur, comme la virgule, par exemple :xxx|split:","

|has_rolevérifie si un utilisateur possède un rôle spécifique.Exemple :session_user|has_role:"Agent"

|rename_filerenomme un fichier.Le paramètre.$extrécupère l’extension du fichier d’origine.

Exemple simple :{{ form_var_fichierarenommer|rename_file:"RIB.$ext }}

Exemple avancé (nom dynamique basé sur plusieurs champs) :{% with nom_fichier="dutexte"|add:form_var_votrechamp|add:"-"|add:form_var_autrechamp|add:".$ext" %}{{form_var_fichierarenommer|rename_file:nom_fichier }}{% endwith %}

|convert_image_formatconvertit une image dans un autre format (JPEG, PDF ou PNG)Exemple :{{ form_var_image|convert_image_format:"jpeg" }}{{ form_url|qrcode|convert_image_format:"pdf" }}

|as_templateinterprète une variable comme un gabarit.

|check_no_duplicatesvérifie l’absence de doublons dans une liste.Exemple :{% if forms|objects:"slug_formulaire"|filter_by:"un_champ"|filter_value:unevaleur|getlist:"un_champ"|check_no_duplicates %}code>pas de doublon (on vérifie si des doublons existe){% else %}{{forms|objects:"slug_formulaire"|filter_by:"un_champ"|filter_value:unevaleur|getlist:"un_champ"|join:","}} (pour renvoyer la liste des doublons){% endif %}

|housenumber_numberextrait la partie numérique d’un numéro de rue.Exemple :"42bis"|housenumber_number→42

|housenumber_btqextrait la partie non-numérique d’un numéro de rue.Exemple :"42bis"|housenumber_btq→"bis".

|strip_emojisupprime les émojis d’un texte.

|repeat:nrépète une valeur un certain nombre de fois.Exemple :"hello"|repeat:3→"hellohellohello".

Paramétrage avancé

* Utiliser les variables
* Utiliser les balises de gabarit
* Utiliser les conditions
* Utiliser les gabarits (templates)
* Utiliser les filtres
* Utiliser les filtres de requête
* Connecteur avec un fichier tableur (CSV)
* Stockage des données dans une base (JSON)
* Sources de données
* Pages d’inspection et de debug
* Configuration de Matomo
* Envoyer un paramètre à un formulaire grâce à une URL

Guide administrateur fonctionnel

* Gestion d’identités
* Studio
* Catégories
* Fabrique de formulaires
* Fabrique de workflows
* Importer et exporter les démarches
* Modifier le contenu des portails
* Agendas : Évènements et rendez-vous
* Créer des rapports statistiques
* Développer des applications métier avec Publik
* Progressive Web App (PWA)
* Paramétrage avancé
* Les tutos

# Le guide de l’administrateur fonctionnel

Le guide de l’administrateur fonctionnel

L'administrateur fonctionnel a pour mission de dématérialiser des démarches administratives.

Une démarche dématérialisée se compose d'unformulaireet d'un circuit de traitement, appeléworkflowqui implique les interventions d'usagers et d'agents, définis selon la ou desfonction(s)et/ou le ou lesrôle(s)qui leur aura été attribué(s).

Chaque démarche dématérialisée se compose d'un formulaire propre. En revanche, une démarche peut reposer sur le même circuit de traitement qu'une autre démarche, ce qui facilite grandement la dématérialisation de démarches similaires.

Dématérialiser une démarche administrative

Le formulaire d'une démarche dématérialisée est destiné à être saisi (par l'usager lui-même ou par unagent d'accueil) pour formaliser une demande d'usager traitable par ungestionnaire.

Le workflow formalise quant à lui le circuit de traitement que les demandes relatives à une démarche sont vouées à emprunter. Il indique les étapes de traitement, ainsi que les opérations qui doivent être réalisées à chacune d'elles, pour aboutir à la clôture de la demande.

Le rôle d'un utilisateur définit ses droits sur le formulaire. En tant qu'agent, le rôle adéquat attribué à mon compte va me permettre d'accomplir des actions à chaque étape du workflow, pour orienter la progression d'une demande en cours de traitement.

Mettre une démarche en ligne, cela peut être l'occasion de la simplifier. Plutôt que de simplement répliquer mécaniquement une démarche papier existante, il faut se poser la question de la modernisation de la démarche. Notre

[fiche d'aide à la dématérialisation](https://doc-publik.entrouvert.com/pour-aller-plus-loin/dematerialiser-une-demarche/)

peut vous aider à faire le point en la matière.

Mais si vous êtes pressés vous préférez peut-êtredématérialiser une démarche en 10 minutes: Le portail agent de Publik permet à l'administrateur fonctionnel de fabriquer et de mettre en production une démarche très facilement à partir d'un workflow existant.

Formulaires et workflows

Configuré par défaut pour des besoins élémentaires, Publik propose des fonctionnalités susceptibles d'offrir une personnalisation poussée desformulairesetworkflows.

Utilisateurs et rôles

L'ensemble des permissions dans l'application est géré par lesrôlesque l'on attribue auxutilisateurs. Leur gestion appartient aussi à l'administrateur fonctionnel.

Autres fonctionnalités

L'administrateur fonctionnel va aussi, en fonction des permissions qui lui sont accordées, pouvoir gérer :

* L'import export de démarches.
* L'édition ducontenu des portails agents et citoyens.
* L'outil de gestion de réservations et de rendez-vous.
* L'outil de génération de statistiques.

* Studio
* Les tutos

# Utiliser les conditions

Utiliser les conditions

Les conditions sont des formules qui vont se réveler vraies ou fausses, on va pouvoir les utiliser pour :

* afficher (ou pas) un champ ou une page
* permettre (ou pas) de quitter une page
* déclencher (ou pas) une action de workflow

Il ne faut pas confondre les conditions avec lesgabaritsqui eux produisent du texte (même s'il y a des usages approchant comme lesfiltres)

Pour vérifier qu'une condition fonctionne quelle qu'elle soit, il est souvent très utile de consulter lespages d'inspection.

Les exemples qui suivent respectent la syntaxe Django, qui est celle qui devra être utilisée par défaut. Historiquement, les conditions étaient écrites en langage Python. Vérifiez que c'est bien la syntaxe Django qui est sélectionnée dans votre condition (à côté de l'engrenage), si vous souhaitez utiliser ces exemples.

Condition sur les dates

Les conditions sur les dates sont monnaie courante et assez spécifiques.

Si nous avons un champ date ayant comme identifiant « date »,  nous utiliseronsform_var_date|datepour obtenir une chaîne de caractère utilisable dans l'écriture des conditions. Par ailleurs la variabletodayest un objet date qui contient la date du jour. il faudra lui aussi le transformer en une chaîne de caractère à l'aide dufiltre|datepour l'exploiter dans l'écriture des conditions. Quelques exemples :

* On peut faire varier la façon dont une date va s'afficher grâce à des paramètres du filtre |date. Par exemple avec la variable today (qui contient la date du jour), on aura :

{{ today|date:"Y-m-d" }} --> affiche la date au format ISO, par exemple 2019-02-25{{ today|date:"d/m/Y" }} --> affiche la date au format plus habituel 25/02/2019

* On pourra souhaiter ne récupérer que :L'année :today|date:"Y"Le mois :today|date:"m"Le jour :today|date:"d"
* Pour vérifier qu'une date est postérieure à la date du jour on écriraform_var_date|date > today|date: cette condition sera vraie si la date de la variable est postérieure à la date du jour.
* Pour vérifier qu'une date 1 est postérieure à une date 2 on écriraform_var_date1|date > form_var_date2|date: cette condition sera vraie si la date 1 est postérieure à la date 2.
* |add_daysva permettre de soustraire ou d'ajouter des jours à une date. Pour déclencher une action 2 jours avant une date particulière (vérifier qu'on est à deux jours ou moins d'une échéance), on écrira par exempleform_var_date|date|add_days:-2 >= today|date: cette condition deviendra vraie deux jours avant la date de la variable, elle sera fausse jusqu'à -2 jours avant la date de la variable.
* Pour vérifier que la date se situe à plus de 30 jours avant la date du jour, on écriraform_var_date|date|add_days:30 <= today|date: cette condition sera vraie si la date de la variable est inférieure de 30 jours ou plus à la date du jour, fausse sinon.
* Le même type de calcul est possible en se basant sur un délai lié à un nombre d'heures. On utilise alorsform_var_date|add_hours:3(on ajoute 3 heures à la date sélectionnée).
* Pour contrôler l'âge d'un enfant lors d'une inscription. Par exemple, une inscription ouverte aux seuls enfants nés de 2014 à 2016 inclus. On utilisera alors cette condition :form_var_date_naissance|date:"Y" >= 2014 and form_var_date_naissance|date:"Y" <= 2016

Pour plus d'informations sur les filtres date dans Publik consulter la sectionfiltres sur les dateset pour creuser encore plus loin consulter la documentation Django pour uneréférence complète concernant l'utilisation du filtre dateet dufiltre time.

Calculs

Les filtres django sont plus adaptés pour effectuer des calculs sur les variables. Reportez-vous à la pagehttps://doc-publik.entrouvert.com/admin-fonctionnel/parametrage-avance/utiliser-les-filtres/#filtres-permettant-des-operations-mathematiques.

Utiliser une liste à choix multiples

Mettons une telle liste, avec des valeurs simplement définies dans le backoffice (i.e. pas de source de données), l'identifiant du champ est mis à foobar.

Mettons une demande remplie, avec deux éléments cochés.

On va avoir comme variablesform_var_foobar : "pomme, poire"(type chaine de caractère)

* voir si l'élément « poire » a été coché :

"poire" in form_var_foobar

* voir si l'élément « poire » n'a pas été coché :

"poire" not in form_var_foobar

* évidemment ça marche aussi pour plusieurs cases à cocher, voir si  les éléments « poire » ET « pomme » ont été cochés :

"poire" in form_var_foobar and "pomme" in form_var_foobar

* ou bien voir si l'un ou l'autre élément a été coché :

"poire" in form_var_foobar or "pomme" in form_var_foobar

* et de manière générale, toutes les opérations possibles sur les ensembles peuvent également avoir lieu en passant par le type approprié (set) et donner des expressions plus lisibles que des successions de and/or etc.

Conditionner la valeur d'une variable (if... else)

Prenons l'exemple d'une démarche que l'on peut faire pour soi ou pour le compte d'un tiers. On pose une question dont la réponse est stockée dans form_var_nature_demande (c'est soit « Me concerne », soit « Concerne quelqu'un d'autre »).

En fonction de la réponse, je veux stocker dans une donnée de traitement « Commune » (form_var_commune),  la commune de la personne concernée (information demandée sur une page particulière) ou la commune du demandeur (demandée sur une autre page). Lorsque la demande est faite pour un tiers, il faut prendre la commune de la personne concernée, la commune du demandeur sinon. Pourmodifier la valeur d'une donnée de traitementform_var_commune, on va écrire sous forme degabarit Django:

{% if form_var_nature_demande == "concerne quelqu'un d'autre" %} {{form_var_commune_personne_concernee}}

{% else %} {{

form_var_commune_demandeur }}

{% endif %}

Les champs d'un formulaire sont tous définis, même si l'usager n'est pas passé par la page contenant tel ou tel champ. Nos deux variablesform_var_commune_personne_concerneeetform_var_commune_demandeurexistent donc toujours.

Condition de sortie de bloc de champ

Plus d'informations sur la page desblocs de champs.

* Studio
* Les tutos

# Guide de développement

Guide de développement

Pour les personnes intéressées par le développement dans et autour de Publik, de l’installation d’un environnement de développement à a création d’une intégration graphique, du l’utilisation des API au développement d’un connecteur.

* Contribuer à Publik
* Installation d’un environnement de développement local
* Intégration graphiqueIntégration graphique nativeIntégration graphique personnaliséeCréation grapique avec intégration personnaliséeInfrastructure SCSSClasses CSS réutilisables
* Vue d’ensemble sur les connecteurs
* Échanges avec un logiciel de demandes «métier»
* Développement d’un connecteur avec Passerelle
* Raccordement avec un portail métier (SSO)
* Développement d’une cellule alimentée par JSON
* API de gestion d’identités et d’accès (authentic)Gestion des utilisateursGestion des rôlesGestion des relations d’héritage entre rôlesAutres fonctionsApprovisionner et déprovisionner les utilisateurs depuis authenticAppeler l’API depuis un logiciel ne gérant que les données « plates »
* Téléservices (w.c.s.)ParamétrageAPI Web ServicesDépréciation des conditions et expressions Python
* API AgendasObtenir les créneaux d’un agendaRéservation d’un créneauGestion des agendasGestion des évènementsGestion des rendez-vousGestion des réservations
* API PortailsGestion des ressourcesPaiement en ligne
* API Agendas (ancienne version)

# Guide d’administration système

Guide d’administration système

Veuillez utilisez le menu de gauche pour consulter la documentation d'architecture, d'installation et d'exploitation.

* ArchitecturePrésentation généraleStructure d’une briqueDépendances logiciellesHébergement SaaSSécurité du SaaS et conformité au RGPDEnregistrements DNS : délégation de domaine
* InstallationPré-requisConfiguration des dépotsCréation des bases de donnéesInstallation des composantsDéploiement des instancesHaute disponibilité
* ExploitationPilotageMises à jourJournal des évènementsFeature flags

# Classes CSS réutilisables

Classes CSS réutilisables

En complément du système de grille CSS, les thèmes Publik fournissent une série
de classes CSS réutilisables.

Classes « responsive »

pk-mobile-only | Limite l’affichage à la vue « mobile » du site, c’est-à-dire quand la
  largeur de l’écran est faible, par défaut inférieure ou égale à 800 pixels.
--------------------------------------------------------------------------------------------------------------------------------------------------------------------
pk-desktop-only | Limite l’affichage à la vue « ordinateur » du site, c’est-à-dire dans
  la situation inverse, quand la largeur de l’écran est par défaut supérieure à
  800 pixels.

Classes pour les cellules

pk-no-border | Retire la bordure de la cellule.
-----------------------------------------------
pk-transparent | Assure un fond transparent à la cellule.
foldable | Rend le contenu d’une cellule pliable.
folded | Associée à la classe foldable, définit le contenu
   d’une cellule comme étant plié par défaut.
links-list | Permet de donner à une cellule de texte le style commun
   « titre et liens », pour cela le texte doit contenir un titre
   (<h2>) suivi d’une liste de liens (<ul>).
pk-information | Donne à la cellule le style de bloc d’information.
pk-attention | Donne à la cellule le style de bloc d’attention.
pk-error | Donne à la cellule le style de bloc d’erreur.
pk-success | Donne à la cellule le style de bloc de réussite.
pk-cell-bold-title | Met en gras le titre d’une cellule.
pk-cell-center-title | Place au centre le titre d’une cellule.

Classes pour les champs des formulaires

pk-budget-table | Met en forme un champ de type « tableau » pour la saisie
  d’informations budgétaires (libellés alignés à gauche, utilisation de toute
  la largeur, colonne de saisie des nombres poussée sur la droite).
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
pk-compact-file | Dispose les champs de type « Fichier » dans une version compacte,
  moins haute.
pk-hidden | Cache le champ (applicable uniquement aux champs de type « Liste »).
pk-important | Marque le champ comme étant particulièrement important, le rendu sera
  généralement un libellé mis en gras.
pk-information | Marque le champ commentaire avec le style de bloc d’information.
pk-attention | Marque le champ commentaire avec le style de bloc d’attention.
pk-error | Marque le champ commentaire avec le style de bloc d’erreur.
pk-blocks-zebra | Alterne les couleurs de fond des lignes des blocs de champs.
pk-horizontal-checkboxes | Aligne horizontalement les cases à cocher d’un champ « liste à choix multiple ».
pk-horizontal-radiobuttons | Aligne horizontalement les boutons radio d’un champ « liste ».
pk-vertical-items | Aligne verticalement les éléments d’un champ de type « liste à choix multiple »
  ou « liste », quand ils sont affichés sous forme d’images.
pk-tall-map | Augmente la hauteur d’un champ de type « carte ».

Classes pour des éléments de texte

pk-button | Applique une apparence de bouton à un lien.
-------------------------------------------------------
pk-big-button | Applique une apparence de bouton de grande taille à un lien.
pk-button-delete, pk-big-button-delete | Applique une apparence de bouton de type "supprimer" (si le style est défini pour votre thème)
pk-button-submit, pk-big-button-submit | Applique une apparence de bouton de type "valider" (si le style est défini pour votre thème)
pk-button-cancel, pk-big-button-cancel | Applique une apparence de bouton de type "annuler" (si le style est défini pour votre thème)

Les classespk-buttonetpk-big-buttonlistées ci-dessus
  peuvent également être appliquées aux cellules de type « Lien ».

Classes pour les tableaux

pk-data-table | Applique un style commun de présentation au tableau, obligatoire
      pour que les autres styles de tableau prennent effet. Cela concerne les
      balises <table>, la classe n’est pas nécessaire pour l’affichage de
      fiches sous forme de tableau.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
pk-table-headers | Applique aux entêtes de colonne un style distinctif, par défaut
      proche de celui des titres de cellule.
pk-table-borders | Applique des bordures de tous les côtés des cellules du
      tableau.
pk-table-center | Centre par défaut le contenu de toutes les cellules.
pk-table-zebra | Alterne les couleurs de fond des lignes.
pk-table-fit-container | Donne au tableau la largeur du conteneur.
pk-table-wrapper | Permet aux usagers de mobiles de faire défiler le tableau
      horizontalement. Cette classe ne s’applique pas à la balise
      <table> elle-même, elle doit se poser sur une balise
      <div> englobant le tableau.

Classes pour l’impression

pk-print-only | Affiche ce contenu uniquement à l’impression, pas à l’écran.
----------------------------------------------------------------------------
pk-no-print | Affiche ce contenu uniquement à l’écran, pas à l’impression.

Modifier le contenu des portails

* Les cellulesCellules contenu génériqueCellules démarchesCellules espace agentsCellules fiche(s)Cellules visualisation des données statistiquesCellules paiementCellules avancées
* Mettre en place un portail Agents
* Classes CSS réutilisables
* Créer un menu personnalisé

* Studio
* Les tutos

# Création de document

Création de document

Généralités

L'action « Création de document », permet de générer un document relatif à une demande d'usager lorsqu'elle atteint le statut auquel cette action appartient.

Si une donnée de traitement de type « fichier » existe dans le workflow, il sera possible de lier le document créé à cette donnée en sélectionnant cette donnée de traitement qui apparaît dans la liste déroulante « Enregistrer le document généré comme donnée de traitement ».

Édition

Les étapes d'édition de l'action « Création de document » sont les suivantes :

* Sélectionner toute fonction, ou tout rôle d'utilisateur habilité à générer le document.
* Cocher le champ « Joindre le document généré à l'historique du formulaire » lorsque le document doit être intégré au sein duJournal d'une demande d'usager.
* Saisir le texte du bouton qui, une fois actionné par le gestionnaire en cours de traitement d'une demande, activera la génération du document lorsque le demande atteindra le statut qui contient cette action.
* Choisir le modèle du document à générer s'il existe. Il est également possible de renseigner un gabaritpour obtenir le fichier servant de modèle.
* Rédiger le texte d'information qui explicitera, pour le gestionnaire, l'effet induit en cliquant sur le bouton « Création de document ».

Modèle de document

Les modèles de document sont des documents au format Open Document (faits par exemple avec LibreOffice ou un MS Office ultérieur à 2010) de n'importe quel type (texte, feuille de calcul, présentation, graphique) dans lesquels sont insérés des variables LibreOffice qui ont pour valeur une variable issue de Publik.

Insérer des variables

Le paragraphe concernant l'insertion des variables ne concerne que les documents ODT.

S'agissant des documents ODS (tableur),

les variables peuvent être insérées directement dans une cellule en y écrivant par exemple

{{ form_var_IDENTIFIANT }}

Pour insérer une variable :

* Aller dansInsertion -> Champs -> Autres... -> Onglet « Variables ».
* ChoisirChamp utilisateurdans la colonneType.
* ChoisirTextedans la colonneFormat.
* Définir un nom explicite, ex:Civilité.
* Donner comme valeur une variable ({{form_number}}, {{form_var_champchoisi}}, ...) ou une expression, par exemple :{% if form_var_pays == "France" %}0800 123 456{% else %}+33 1 1234 5678{% endif %}.

Vous pouvez réutiliser cette variable plusieurs fois dans le document, elle aura toujours la même valeur.

Pour insérer une donnée de tableau, utilisez les indices. Par exemple :

{{ form_var_test.0 }}

Boite de dialogue d'insertion dans LibreOffice

Insérer des images

Il est possible d'inclure des images tirées des données d'une demande dans le document. Pour cela il faut inclure une image dans le modèle de document et éditer son nom (dans LibreOffice, clic droit, « Propriétés », onglet « Options »).

Il faut alors indiquer, dans le champ nom, le gabarit qui pointera le champ fichier contenant l'image souhaitée, ainsi :

{{ form_var_image_raw }}

Si vous voulez insérer plusieurs images dans un même document, il faudra utiliser des fichiers image différents pour chaque élément image du modèle de document. Libreoffice stocke en interne la référence à l'image par son contenu. Ce qui fait que si vous utilisez trois fois la même image, Libreoffice ne saura pas les différencier malgré vos gabarits, et vous vous retrouverez avec 3 fois la même image sur le document final.Vous pouvez donc modifier légèrement votre première image (modifier le nom ne suffit pas, car c'est le contenu de l'image qui est utilisé par Libreoffice) ou en utiliser une autre pour chaque gabarit d'image dans votre document.

Insérer un QR code pointant vers une URL

La procédure est la même que pour une image mais dans le nom de l'image il faudra par exemple placer le texte suivant pour créer une image contenant un QR code pointant vers l'URL en back-office de la demande :

{{ form_url_backoffice|qrcode }}

N'importe quelle URL ou chaîne de caractère ASCII peut être intégrée sous la forme d'une image lisible par tablette ou smartphone; cela peut être utilisé pour du pointage à l'entrée d'un lieu (billetterie, halte-garderie, etc...).

Insérer une nouvelle ligne

Il est possible d'insérer une nouvelle ligne dans le document avec la balise {% newline %}.

Choisir une police de texte

Pour des raisons de compatibilité, il est vivement recommandé d'utiliser les polices de texte natives à LibreOffice. Néanmoins, si vous utilisez une autre police, vous pouvez forcer son utilisation dans le document créé en appliquant les étapes suivantes au modèle du document :

* Lors de la création du document dans LibreOffice, vérifier dans Fichier/Propriétés, sur l'onglet Polices, que la case "Incorporer les polices dans le document" est cochée.

* Sélectionner le texte souhaité et réappliquer la police nouvellement incorporée

Ainsi, le modèle de document .odt généré contiendra les polices voulues.

Créer un récapitulatif de la demande

La variable {{form_details}} contient tous les champs de la demande. Il est possible de l'utiliser dans un modèle de document pour créer un récapitulatif de la demande, vous pouvez au choix

* Utiliserce modèle de documentqui est déjà configuré correctement (vous pouvez ajouter des choses au -dessus ou en dessous de la section form_details mais rien à l'intérieur)
* Fabriquer votre propre modèle

Pour fabriquer votre propre modèle, il faut passer dans LibreOffice par insertion / section, et donner à la section le nomform_detailscomme sur cette capture :

​

* Si du contenu est ajouté à la section, il sera retiré.
* Il y a plusieurs styles à définir (en respectant les noms donnés ici) :Page_Title( qui définit le style d'un champ de type page),Form_Title(qui définit le style d'un champ de type titre),Form_Subtitle(qui définit le style d'un champ de type sous-titre),Field_Label(qui définit le style d'un libellé de champ - pour tous les autres champs),Field_Value(qui définit le style du contenu des champs).
* Si aucun style n'est défini, des styles basiques par défaut sont utilisés.
* Dans le fichier fourni en modèle, les différents styles sont définis, via un exemplaire dans la section. Il peut être nécessaire de procéder ainsi (avoir du texte utilisant les styles dans la section) pour éviter que LibreOffice procède à un nettoyage automatique des styles inutilisés.

Transmettre le document à l'usager

Il y a plusieurs façons de permettre à l'usager d'accéder à un document généré dans Publik, elles peuvent être utilisées concomitamment.

Envoyer par courriel

Il est possible d'envoyer par mail, l'adresse vers le document en utilisant dans le template du mail la variable : {{form_attachments_identifiant-du-document.url}}

Joindre le document à l'historique de la demande

En cochant la case appropriée, le document apparaîtra dans l'historique de la demande quand l'usager consultera sa demande sur le portail citoyen.

Déposer le document dans le porte-document

En utilisant une action webservice, le document généré peut être envoyé dans le porte-document de l'usager. L'action de webservice doit alors être configurée comme suit :

* URL : {{porte_doc_url}}api/documents/push/
* Ne pas cocher la case « Envoyer les données du formulaire »
* Données (POST) envoyées :origin : le nom du service ayant produit le document (ex: Service population)file_b64_content :{{form_attachments_nom-de-la-variable.content}}user_nameid :{{form_user_nameid}}file_name :{{form_attachements_nom de la variable.filename}}

Mettre le document dans une donnée de traitement

Si parmi leschamps de traitementdu workflow existe au moins un champ de type « fichier », vous aurez dans l'action de création de document une case à cocher « Enregistrer le document généré comme donnée de traitement » qui vous permet de choisir parmi les champs de type fichier.

Une fois l'enregistrement effectué, vous pourrez vous référer à cette donnée de traitement pour utiliser le document (par exemple pour l'envoyer ultérieurement en utilisant un webservice).

En savoir plus :voir le tutoriel.

Fabrique de workflows

* Workflow par défaut
* Créer un nouveau workflow
* Gérer un workflow
* Les statuts de workflow
* Les actions de workflow
* Vue graphique du workflow
* Fonctions de workflow
* Variables de workflow
* Actions globales
* Actions en masse
* Niveau de criticité
* Champ « Données de traitement »
* Les tests de workflows

* Studio
* Les tutos

# Guide de l’agent d’accueil

Guide de l’agent d’accueil

Le rôle de l’agent d'accueil est d’aider l'usager dans l'utilisation de son espace de démarches en ligne Publik en répondant à ses questions quant à la navigation dans le portail usagers et quant aux démarches disponibles en ligne (l'agent doit donc connaître la liste des démarches proposées par la collectivité).

Cet accueil peut être réalisé par différents canaux de communication mis à disposition de l'usager :

* le guichet
* le téléphone
* le courrier

Si le portail agents est configuré en ce sens, l'agent d’accueil pourra également informer l’usager sur l'avancement d’une démarche en cours (cf.Chercher une demandeetUtilisation du code de suivi) ou faire lasaisie pour le citoyen, c’est-à-dire saisir, au nom de l'usager, une nouvelle demande dans l'un des formulaires existants sur la plate-forme.

Guide de l’agent d'accueil

* Guichet
* Téléphone
* Courrier
* Saisie pour le citoyen
* Utilisation du code de suivi
* Chercher une demande
* Fiche usager
* Créer un compte pour le citoyen

# Le détail d'un formulaire

Le détail d'un formulaire

Le détail d'un formulaire offre une vue de ses propriétés, de son contenu et de sa structuration.

Le détail d'un formulaire est accessible à l'administrateur fonctionnellorsqu'il clique sur le libellé d'un formulaire depuis laliste des formulaires.

Les propriétés d'un formulaire fixent les principes de fonctionnement de celui-ci. « Par qui ? », « Quand ? » et « Comment ? » un formulaire sera saisi et traité, constituent les éléments que l'administrateur fonctionnel a la possibilité de préciser.

Changer le titre ou l'URL d'un formulaire

Sur la page d'accueil du formulaire, le bouton « Changer le titre » (à côté du titre), permet d'éditer les deux paramètres :

* Titre: permet de spécifier un nouveau titre
* Identifiant dans les URL: permet de changer l'URL. Les formulaires n'ayant encore aucune demande peuvent changer d'URL sans encombre. Pour les autres une alerte s'affiche, si vous ne mesurez pas les enjeux, ne le faites pas sur une démarche utilisée en production.

Informations

* Description:Texte court, à l'attention des usagers et agents, qui contextualise le principe d'une démarche. La description d'un formulaire a pour vocation de préciser le principe de la démarche à laquelle il est associé aux usagers et aux agents. Ce texte doit être court, clair et informatif ; les options de mise en page doivent être utilisées avec parcimonie. La description apparaît sur le portail citoyen (front-office) automatiquement.

* Mots-clés:Série de mots destinés à résumer les traits distinctifs d'une démarche. Les mots-clés d'un formulaire ont pour vocation de relier sémantiquement les formulaires entre eux pour pouvoir filtrer ces derniers en fonction de ces mots-clés. Il faut séparer chaque mot-clé par une virgule.
* Catégorie:Étiquette qui rassemble sous un même thème différents formulaires, aussi bien en back-office qu'en front-office.

Workflow

* Workflow:Permet de sélectionner, dans la liste des workflows existants, celui qu’intégrera le formulaire une fois saisi et validé.
* Options: si des variables sont définies dans le workflow lié au formulaire, leur valeur peut être saisie via cette entrée (qui n'est pas affichée si aucune « variable du workflow » n'est déclarée).
* Destinataire:Permet de sélectionner, dans la liste des rôles existants, celui des agents instructeurs (le rôle des personnes qui vont traiter la demande).
* Fonction(s):Si des fonctions ont été définies dans le cadre du workflow associé au formulaire alors ces dernières apparaissent sous « Destinataire » avec le nom de fonction défini dans le workflow. L'association avec un rôle peut être réalisé pour chacune de ces fonctions.
* Rôle(s) du demandeur:Permet de réserver l'accès au formulaire à certains types d'usagers, en fonction du ou desrôle(s)dont ils auront été doté(s). L'accès peut être réservé aux usagers connectés ou aux détenteurs d'un rôle particulier. Si rien n'est spécifié, le formulaire sera en accès libre pour tous, connectés ou non. Il y a deux options supplémentaires :N’autoriser qu’un seul formulaire par utilisateur (ne fonctionne que si le formulaire n'est pas en accès libre) ;Afficher aux utilisateurs non-connectés (pour que les formulaires en accès restreint soient affichés à tous, même aux personnes à qui ils ne sont pas accessibles).
* Rôle(s) pour la saisie du backoffice:Permet aux agents d'accueil qui ont le rôle qui sera indiqué ici de remplir le formulaire à la place du citoyen.

Options

* Page de confirmation:affiche une page récapitulative reprenant l'intégralité des informations saisies, avant la validation finale. Cette option est surtout utile lorsque le formulaire est long et comporte plusieurs pages.
* Saisie backoffice:cette option n’apparaît que si un rôle est assigné pour la saisie backoffice. Elle permet aussi de configurer le contenu de la barre latérale en saisie backoffice :Le champ « Association d'un usager lors de la saisie » offre trois options pour associer un usager à la demande en cours de saisie en backoffice :N'importe quel usager (optionel) : les agents pourront laisser le champ « Usager associé » vide ou choisir n’importe quel usager ;N'importe quel usager (obligatoire) : les agents devront obligatoirement renseigner le champ « Usager associé » ;Usager avec les rôles adéquats : les agents devront obligatoirement renseigner le champ « Usager associé ». Seuls les usagers qui disposent du rôle défini dans « Rôles du demandeur » remontent dans dans la liste des usagers.

* Traitement: deux options :Contenu de la barre latérale: pour permettre de préciser les informations qui apparaitront dans la barre latérale lors du traitement d’une demande; il est notamment proposé d’y inclure un bouton de téléchargement des fichiers : si plusieurs documents sont joints à la demande,  un bouton sera affiché permettant de télécharger tous les documents dans une archive.Ne pas afficher dans la vue par usager: par défaut tous les formulaires seront affichés dans la fiche d'un usager ; pour des formulaires particulièrement sensibles (formulaires de demande d'aide sociale, par exemple), le réglage « Ne pas afficher » empêchera qu'ils soient affichés dans cet écran.
* Suivi de la demande: Le code de suivi est un code connu uniquement du demandeur (une sorte de mot de passe), qu'il peut utiliser pour retrouver sa demande même s'il n'a pas de compte. Il peut par ailleurs le donner àun agent d'accueil pour autoriser ce dernier à voir le contenu de sa demande. Le code de suivi permet d'accéder aussi bien à une demande finalisée en cours de traitement qu'à un brouillon, non encore validée, alors accessible uniquement par l'usager. Pour renforcer la sécurité de cet accès, il est possible de demander à l’usager la saisie de données présentes dans la demande.

Le nombre maximum ainsi que la durée de vie des brouillons peuvent être configurés via cette entrée « Suivi de la demande ». L'option « Durée de vie des brouillons (en jours) » permet de faire varier cette durée positionnée par défaut à 100 jour. La durée minimale est de 2 jours.

* Gabarits: ces options permettent d'ajouter à une demande sous forme degabarit:un court résumé repris dans la vue globale des demandes (le contenu est intégré dans la première colonne du tableau), dans la liste des demandes en cours d'un usager, et dans la liste des brouillons d'un formulaire en cours de saisie par l'usager.Un texte en barre latérale dans l'écran detraitement de la demande,Un texte en barre latérale dans l'écran desaisie backoffice de la demande.
* Publication:Cette option définit les modalités de publication du formulaire. Par défaut, après création ou import, le formulaire est désactivé. Pour rendre une démarche utilisable, il faut activer la publication de son formulaire en cochant la case prévue à cet effet et avoir prévu son affichage dans le portail citoyen.Si désactivé, rediriger vers cette URL:  lorsque ce champ est renseigné, la démarche est affichée sur le portail citoyen mais en cliquant dessus, l'usager est redirigé vers l'URL indiquée. C'est utile pour pointer une page expliquant par exemple pourquoi la démarche n'est pas encore accessible ou pour rediriger l'usager vers un service distinct de Publik (comme « service-public.fr »).Période de publication :Les champs « Date de publication » et « Date d'expiration » permettent de définir une période de publication. La période de publication ne fonctionne que si l'accès au formulaire est actif, c'est à dire uniquement si « Désactiver l'accès au formulaire » est décoché. Par défaut, la publication commencera à 0h00 du jour choisi mais on peut aussi indiquer une heure sous cette forme : « 25/11/2018 08:00 ».

Champs

Une prévisualisation du formulaire est offerte dans la section « Champs ». Cliquer sur « Éditer » à côté de « Champs » permet d'accéder àLa page d'édition des champs d'un formulaire.

Pour une vue parfaitement réaliste de ce que l'usager verra en ligne lorsqu'il remplira son formulaire, il faut passer par le lien«Voir en ligne»(ou «Aperçu en ligne» si le formulaire est désactivé)dans la barre latérale.

Barre latérale

La barre latéraleoffre plusieurs boutons d'action et de navigation :

* Dupliquer (un formulaire) :la duplication du formulaire entraîne la création d'un formulaire identique qui portera le titre du formulaire d'origine avec en plus la mention « (copie) ».
* Enregistrer une sauvegarde: Toutes les modifications sont enregistrées automatiquement dans l'historique du formulaire. Mais on peut souhaiter donner une visibilité particulière à une version en la sauvegardant explicitement, elle sera alors mise en évidence dans l'historique.
* Écraser (un formulaire) avec un nouvel import: cette action va permettre d'importer un formulaire qui va venir prendre la place du formulaire existant.

Par défaut, lorsqu'on importe un formulaire, même s'il a le même nom qu'un formulaire existant, il ne vient pas l'écraser : il est copié à côté du formulaire existant. La seule façon pour faire en sorte qu'un formulaire importé prenne la place d'un formulaire existant, c'est d'utiliser«Écraser avec un nouvel import», le formulaire importé récupérera alors toutes les demandes de l'ancien formulaire.

L'écrasement avec un nouvel import réinitialise les vues créées pour tout le monde par l'administrateur fonctionnel. Mais l'écrasement n'affecte pas les vues personnalisées créés par les agents (pour eux-même ou pour un rôle).

* Voir en ligne(ou «Aperçu en ligne» si le formulaire est désactivé):permet de visualiser le formulaire tel qu'il sera vu par l'usager en front office.
* Tableau de traitement: accès à laliste des demandespour le formulaire concerné.
* Historique: accès aux différentes versions du formulaires sauvegardées par ordre chronologique. Chaque version peut être restaurée en cliquant sur « Restaurer » et en choisissant «Écraser le contenu actuel». À l'inverse, choisir «Restaurer en tant que nouveau» créera un nouveau formulaire à partir de la version concernée.
* Inspecteur: accès lavue d'inspection d'un formulaire
* Tests: accès aux tests existants pour un formulaire, ils permettent de vérifier son bon fonctionnement au gré des évolutions apportées.

Menu Kebab

En haut à droite de l'écran, les 3 points verticaux donnent accès au menu kebab et aux fonctionnalités suivantes :

* Voir l'URL publique: permet d'afficher l'URL publique du formulaire qui pourra être utilisée sur différents supports de communication même avant la mise en ligne effective du formulaire.
* Afficher le code QR:ouvre une popup qui affiche l'image du code QR d'une démarche et permet de télécharger celle-ci. Le scan de ce code QR depuis un smartphone permet de rediriger son usager vers un formulaire vierge de la démarche sur le portail citoyen. Vous pouvez donc afficher ce QR code en des lieux où vous voulez permettre aux usagers d'initier une démarche avec leur smartphone. Par exemple, on affichera à la médiathèque le QR code pointant vers le formulaire d'inscription à remplir.
* Exporter (un formulaire): génère un fichier xml contenant le formulaire et pouvant être importé sur une autre plate-forme. Le fichier porte le suffixe .wcs.
* Supprimer (un formulaire) :La suppression d'un formulaire a pour conséquence la disparition de la démarche à laquelle il est associé du portail citoyen. Les demandes ne sont plus accessibles via la brique traitement.

Fabrique de formulaires

* Liste des formulaires
* Création d’un formulaire
* Détail d’un formulaire
* Page d’édition des champs
* Ajouter des champs dans un formulaire
* Créer un formulaire conditionnel
* Les champs d’un formulaire
* Les blocs de champs
* Préremplissage des champs
* Paramètres des champs
* Les tests de formulaires et modèles de fiches

* Studio
* Les tutos

# Prise de rendez-vous backoffice

Prise de rendez-vous backoffice

Laprise de rendez-vous backofficepermet à un agent de prendre un rendez-vous directement depuis la vue calendaire de l'agenda.

Configurer la prise de rendez-vous backoffice côté agenda

⚙️ Accès dans le BO :Agendas > 👉 un agenda de type Rendez-vous > Paramétrage > Prise de rendez-vous backoffice

Dans le paramétrage d'un agenda de type Rendez-vous, onglet Prise de rendez-vous backoffice, après avoir coché la case Activer la prise de rendez-vous backoffice, il faut remplir a minima deux champs :

* Identifiant du formulaire de réservation.
* Identifiant du champ créneau : si l’identifiant est « form_var_creneau », la valeur ici doit être « creneau ».

Deux autres champs peuvent être renseignés s'ils existent dans votre formulaire :

* Identifiant du champ type de rendez-vous : si le formulaire permet la sélection du type de rendez-vous et que l’identifiant est « form_var_meeting_type », la valeur ici doit être « meeting_type ».
* Identifiant du champ agenda : si le formulaire permet la sélection de l’agenda et que l’identifiant est « form_var_agenda », la valeur ici doit être « agenda ».

Configurer la prise de rendez-vous backoffice côté studio (w.c.s.)

La pré-réservation d'un rendez-vous est un pré-requis à la prise de rendez-vous en backoffice. La première étape est donc de paramétrer la pré-réservation en suivant le tuto suivant👉:Paramétrage (exemple pour les rendez-vous).Si vos formulaires et workflows permettent déjà la pré-réservation temporaire, il vous faut :

* adapter l'appel de webserviceexistant (dans Studio / Appels de webservices / Nouvel appel webservice) qui utilise la méthode POST (JSON) avec la même URL que le webservice de réservation  dans le workflow. Dans les « Données à envoyer dans le corps de la requête » indiquez « lock_code » comme variable avec le gabarit{% firstof form_submission_context_lock_code session_hash_id %}.
* mettre à jour leworkflowpour permettre la pré-réservation. Dans l'action Webservice de réservation, il faut modifier le paramètre à envoyer dans le corps de la requête :lock_code : {% firstof form_submission_context_lock_code session_hash_id %}

Prendre rendez-vous depuis la vue calendaire

⚙️ Accès dans le BO :Agendas > 👉 un agenda de type Rendez-vous

Dans la vue calendaire d'un agenda de type Rendez-vous (jour ou semaine), l'agent peut déplacer son curseur et cliquer sur un créneau horaire disponible. Cela déclenche l'ouverture d'une pop-up avec le créneau et s'ils sont renseignés dans le paramétrage, le type de rendez-vous et l'agenda. Ces éléments sont préremplis (et reste modifiables).L'agent clique sur le bouton Allez au formulaire de réservation, et si le créneau est toujours disponible, celui-ci est automatiquement pré-réservé, le temps que l'agent remplisse le formulaire habituel en saisie backoffice.

L'agent doit avoir un rôle de saisie backoffice pour accéder au formulaire et prendre des rendez-vous.

Depuis un smartphone, une tablette ou un ordinateur manipulé via un écran tactile, le comportement est différent. La prise de rendez-vous est possible depuis un bouton Ajouter une réservation affiché sur la vue calendaire. En cliquant sur ce bouton, une pop-up s'ouvre avec le premier créneau horaire disponible déjà prérempli.

Les tutos

* Pré-réservation d'un rendez-vous ou d'un évènement
* Paiement
* Prise de rendez-vous backoffice
* Configuration de l’option « Envoi de SMS »
* Configuration des droits pour l’agent d’accueil
* Utiliser l’autocomplétion
* Envoyer une invitation ics par courriel
* Générer un document et l’envoyer par courriel
* Mettre en place une enquête de satisfaction
* Création d’une demande avec préremplissage des données et des pièces justificatives
* Mettre en place un champ « adresse » unique en autocomplétion
* Conditionner la durée du rendez-vous au contenu d’un autre champ
* Créer un référentiel avec un modèle de fiche

* Studio
* Les tutos

# Champ carte

Champ carte

Le champ « Carte » permet de présenter à l'usager une carte géographique dans laquelle il pourra pointer une localisation.

Propriétés spécifiques du champ Carte

Niveau de zoom initial d'une carte

* Zoom initial : Il fixe le zoom appliqué à la carte au moment de son ouverture par un usager depuis le formulaire.
* Niveau de zoom minimal (affichage le plus large) : Il fixe la limite inférieure du zoom de la carte affichée à un usager (i.e. quelle est la vue la plus générale à proposer).
* Niveau de zoom maximal (affichage le plus resserré) : Il fixe la limite supérieure du zoom de la carte affichée à un usager (i.e. quelle est la vue la plus détaillée à proposer).

Position initiale d'une carte : fixe ou mobile

La position initiale de la carte qui sera affichée au demandeur peut être définie une fois pour toute. Dans l'écran d'édition du champ, il suffit de cliquer sur la carte pour définir l'endroit sur lequel elle sera centrée.

Il est également possible de définir la position initiale de la carte en fonction de la position de l'appareil mobile de l'usager (qui sera alors déterminée par GPS, Wifi ou autre), et de centrer la carte sur celle-ci. Pour cela, il suffit de cocher l'option « Position initiale selon la géolocalisation » de l'appareil .

À noter que la carte est dotée d'un bouton permettant à l'usager de demander une nouvelle géolocalisation.

Barre de recherche d'adresse

Préremplir le champ carte

Il est possible de préremplir un champ carte en se basant directement sur des coordonnées géographiques. En sélectionnant « Texte/Gabarit » dans le champs « Préremplir », il est possible de mettre des coordonnées sous la forme 40.2323;38.2345 mais aussi d'utiliser les informations de géolocalisation provenant d'un autre champ qui en contiendrait par exemple {{ form_var_lieu }}.

Utiliser la carte pour préremplir d'autres champs

Le champ carte permet depréremplirdes champs texte ou liste avec les données de géolocalisation suivantes :

* Numéro
* Rue
* Numéro et rue
* Code postal
* Ville
* Région

Si le champ adresse prérempli par la carte est modifié manuellement, le pointeur est automatiquement déplacé sur la carte pour correspondre à l'adresse saisie.

Paramètres génériques des champs

Nom de variable: Permet de réutiliser la valeur d'un champ au sein d'un mail, d'un SMS, d'une condition...

Préremplir: Permet de remplir le champ automatiquement avec une valeur sans intervention de l'usager

Autres paramètres: obligatoire, remarque, afficher dans les listings, classe supplémentaire pour les CSS.

* Studio
* Les tutos

# Tour d’horizon

Tour d’horizon

Publik permet de centraliser toutes les demandes des usagers d'une collectivité, quel que soit le canal de transmission (téléphone, courrier, courriel, etc) de celles-ci.

La collectivité a la maîtrise tant sur la fabrication des formulaires à présenter au citoyen, que sur le design du circuit de traitement qu'intègrent les demandes qui lui sont transmises.

Avoir un compte: Indispensable pour les agents, utile pour les citoyens.

Pour accéder au portail agent, un compte est obligatoire. L'accès au portail citoyen peut, lui, se faire sans compte mais posséder un compte permettra à l'usager de suivre plus facilement ses démarches et de les préremplir.

Le portail citoyen: un tableau de bord personnalisé, dédié aux démarches

Côté usagers, Publik est un portail citoyen/usagerqui recense les démarches proposées par leur collectivité, leur permet de les accomplir à l'aide de formulaires dédiés ; de suivre et d'archiver leurs demandes, de préremplir toutes les demandes avecdes informations de leur profil saisies une seule fois pour toutes.

Le portail agent: des briques logicielles orientées « métier » au service des agents publics

Pour les collectivités,Publikest un portail métier depuis lequel les agents administratifspeuvent accomplir leurs missions de service public : traiter une demande d'usager, concevoir, classer, publier ou encore, mettre à jour une démarche en ligne,gérer les utilisateurs et leurs droits aux fonctionnalités du portail, etc.

Tour d'horizon

* Avoir un compteS’inscrireSe désinscrirePersonnaliser son compteConnexionMot de passe perdu
* Portail citoyen
* Portail agentÉléments de base de l’interface
* Dématérialiser une démarche en 10 minutes

# Mettre en place une vue personnalisée dynamique

Mettre en place une vue personnalisée dynamique

Il est possible de passer une variable issue d'un formulaire lors de l'interrogation d'une vue personnalisée. Ce paramétrage permet de charger dynamiquement une liste dans un formulaire à partir d'un critère de filtrage (réponse à une question précédente dans le formulaire, option du formulaire ou autre).

Attention, quand le champ qui est utilisé pour construire la vue personnalisé dynamique est unechamp liste sourcé par un modèle de fiche, il est nécessaire d'ajouter _raw au nom de variable pour que la vue utilise l'identifiant plutôt que le libellé.Cela ne fonctionnera pas sans le _raw

Petite vidéo explicative

Les tutos

* Paiement

* Studio
* Les tutos

# Liste des logiciels interfacés avec Publik

Liste des logiciels interfacés avec Publik

Des éditeurs de solutions métiers pour les collectivités ont décidé de proposer, de base, une interopérabilité avec Publik. Il peut aussi bien s'agir de logiciels libres que des logiciels exploitant nativement lesAPIs proposés par Publik.

Publik Services

Publik Servicesrassemble les logiciels métiers libres optimisés pour fonctionner parfaitement avec Publik, via des webservices complets.

Brique | Nom | Description | Prestataire | Intégration
------------------------------------------------------
Droit des sols | OpenADS | Gestion des autorisations du droit des sols | atReal | 
Parapheur | I-Parapheurvia Pastell | Outil de gestion et de validation documentaire |  | 
GEC | Maarch courrier | Gestion du courrier | Maarch | 
Gestion des délibérations | iA-Délib | Gestion des séances délibératoires communales | IMIO | 
Démocratie délibérative | Decidim | Prendre des décisions de manière transparente et collective | Open Source Politics | 
Gestion d'identité | Authentic | Fournisseur d'identité multiprotocole et multi-annuaire | Entr'ouvert | 
Gestion de contenu | Combo | CMS simple, particulièrement adapté à Publik | Entr'ouvert | 
Kit de développement | Publik Studio | Pour construire facilement des applications métiers basiques | Entr'ouvert | 

En coursFait

Logiciels implémentant nativement les APIs Publik

Certains éditeurs, pour assurer une compatibilité optimale, ont choisi de développer des APInativement supportées par Publiket implémentant les protocoles et formats standards  (SAML, OPENID Connect, LDAP, CMIS, nominatim, tuiles openlayers, GeoJSON). C'est une garantie concernant la capacité des applications en question à bien communiquer avec Publik.

Liste non exhaustive, tout éditeur de logiciel est en capacité d'inter-opérer avec Publik sans forcément documenter la liaison établie.

Logiciel | Type | Collectivités | Éditeur / Opérateur | Statut
--------------------------------------------------------------
 | Borne d'accès des usagers | Ville de Chambéry | Citinnov. Gestion des accès aux zones de stationnement et de circulation limitées | Production
 | Gestion de dossiers structurés | Métropole européenne de Lille | Esabora | Production
Municipol | Police municipale | Ville de Rouen | Municipol de Logitud, interfaçage réalisé par DSI Ville de Rouen | Production
 | Logement social | Ville de Nanterre | AFI a dévelopé un web-service pour Pelehas permettant d'exposer dans Publik l'avancement des demandes en cours | Production (fév. 2022)
Acropolis | Gestion électronique de courrier | Ville de Chambéry | Odyssée Ingénierie : intégration des courriers stockés dans la GEC dans le moteur de recherche interne de Publik | En test
Application interne | Transport d'enfants avec handicap | CD38 | Application et interface développées par la société Norsys | En test
 | Gestion de rendez-vous | Ville de Chambéry | Intégration des rendez-vous pris dans Synbird dans le moteur de recherche interne de Publik | En test

Liste des connecteurs

Il faut distinguer deux types de connecteurs :

* Les connecteurs qui permettent une authentification unique (SSO) avec tel ou tel portail métier
* Les connecteurs qui permettent d'échanger des informations (en webservices le plus souvent) avec une application métier ; dans ce deuxième cas les échanges peuvent être dans un seul sens (Publik->métier ou Publik<-référentiel) ou en aller-retour (Publik<->métier).

Chargement…

Authentification unique (SSO)

Logiciel/Standard | Type | Collectivités | Éditeur / Opérateur | Statut
-----------------------------------------------------------------------
Agora+ | Enfance | Oullins | Agora + | Production
Alfresco (Standard CMIS) | GED | Tournai | Alfresco software | Production
AXEL Portail Familles | Enfance | Fontenay | Teamnet | Production
Cap Collectif | Démocratie délibérative | CD Meuse | Cap Collectif | Production
Cart@ds | Urbanisme | Clisson | GFI | Production
D-Park | Stationnement | Toulouse Métropole | Dyade | Production
Drupal | CMS | Montpellier Métropole - Villeurbanne | Logiciel libre | Production
Odoo | ERP | Vinci | Logiciel libre | Production
Owncloud | Groupware | Interne | Logiciel libre | Production
Portail des aides | Subventions | CD71, CD31, Saint-Denis, CD40 | MGDIS | Production
Spip | CMS | Meyzieu | Logiciel libre | Production
Kiosque Famille | Enfance | Nancy, Dreux, Meudon... | Technocarte | Production
Typo 3 | CMS | Fontenay-sous-Bois, CD Meuse... | Logiciel libre | Production
Publidata | CMS | Pré Saint-Gervais | Publidata | Production

Remontées d'information (webservices uni-directionnels)

Arcgis | SIG | Strasbourg | ESRI | Production
CityWeb | État-civil | Orléans, ALPI | Digitech | Production
Portail famille | Enfance | Orléans | Arpège | Production
Contact Everyone | Plateforme envoi SMS | Fondettes, ... | Orange | Production
GDC | Déchets | Montpellier Métropole | Montpellier Métropole | Production
GDEMA | Sollicitations | Strasbourg | Mercure Informatique | Production
Genesis | APA, MDPH | CD06 | SIRUS/ATOS | Production
Hebe | SIG | Montpellier Métropole | Montpellier Métropole | Production
Implicit | Action sociale | Interne | Up Cityzen | Production
Kiosque « numérique » | Médiathèque, diffusion de ressources numérique | CD Calvados | CD Calvados | Production
MDEL | Démarches en lignes | Interne | NA | Production
Municipol | Police municipale | Rouen | Logitud (sur base d'un développement effectué par la Ville de Rouen) | Production
Siècle | État-civil | Strasbourg, Nancy | Logitud | Production
SMS Pro | Plateforme envoi SMS | Interne | OVH | Production
API Diffusion Multi Canal | Plateforme envoi SMS | Nanterre, ... | SFR | Production
Kiosque Famille | Enfance | Nancy | Technocarte | Production
Talend | Big Data |  | Logiciel libre | Production

* RGAA

# Créer et gérer une application

Créer et gérer une application

Créer une application

Depuis l'entrée « Système » du menu latéral de gauche, on accède à l'espace des applications grâce à un bouton dédié.

Il est alors possible de créer des applications en leur donnant un nom et en agrégeant les différents éléments qui la composent.

(lien direct vers la vidéo)

Il est possible d'ajouter des formulaires, des modèles de fiches (les données des fiches), des workflows, des pages et des agendas.

Certains éléments peuvent être ajouté pour l'installation uniquement : il

ne sera pas mis à jour s’il existe déjà sur l’instance où l’application est déployée.

Ça peut être très utile dans le cas d'une application déployée sur plusieurs instances et qui utilise des modèles de courriel qui ne seront pas « écrasés » lors d'une mise à jour. Ce qui permet à chaque collectivité de personnaliser le contenu des messages.

Le fichier obtenu après génération de l'application est une archive au format .tar

Renseigner les métadonnées

Au-delà du nom et de la version qui sont obligatoire pour créer une application, il est possible d'ajouter des informations en renseignant les métadonnées.

On pourra en particulier ajouter une icône et un lien vers la documentation de l'application.Il est également possible d'ajouter des auteurs et une licence  (à choisir parmi GPL, AGPL et MIT).

Ajouter des paramètres

Il est possible d'ajouter des paramètres associés à des valeurs. Ces paramètres, dont l'identifiant sera utilement suffixé avec quelque chose permettant de distinguer clairement l'application, vont permettre d'utiliser globalement dans l'application des variables dont la valeur sera facilement changée d'un déploiement à l'autre de l'application.

Installer une application

Pour installer une application, il faut récupérer le fichier .tar de cette dernière et le télécharger sur la plate-forme après avoir cliqué sur « Installer ».

Mettre à jour une application

Pour mettre à jour une application, il suffit de procéder à l'installation du fichier .tar mis à jour. Les différents composant viendront automatiquement prendre la place des anciens.

Certains paramètres sont conservés lors des mises à jour, il s’agit pour les formulaires et modèles de fiche des rôles attribués pour les différentes fonctions, des paramètres de publication, des options spécifiques au workflow, des modifications locales apportées aux titres des formulaires et des modèles de fiche, ainsi qu’aux libellés et au caractère obligatoire ou pas des champs, afin qu’elles ne soient pas écrasées lors de la mise à jour de l’application.Pour les pages il s’agit du paramétrage de la visiblité, de la page en elle-même mais également des cellules qui la composent, et des rôles d’édition.

En plus de cela, pour les formulaires et modèles de fiche, les changements locaux au titre et aux libellés des champs, ainsi qu’au caractère obligatoire ou pas de ceux-ci, sont également conservés.

Comparer deux applications

Dans l'écran de gestion des versions d'une application, chaque version offre un bouton « Comparer » qui va permettre de  choisir la version avec laquelle on veut comparer la version en cours et d'afficher les différences.

Développer des applications métier avec Publik

* Stocker l’information (modèle de fiches)
* Afficher l’information (via les fiches)
* Modifier l’information (modifier les fiches)
* Créer et gérer une application
* Paramétrage avancé des fiches

* Studio
* Les tutos

# Guide de l’agent traitant

Guide de l’agent traitant

L'agent traitant, ou gestionnaire des demandes, a pour mission de traiter les demandes d'usagers, saisies au sein d'un ou plusieurs formulaire(s) en ligne dont il a la charge.

Le traitement des demandes s'effectue en cliquant surtraitementdepuisle menu principalduPortail agent.

Une demande d'usager suit un circuit de traitement, appeléworkflow. Celui-ci formalise les étapes à atteindre, ainsi que les actions à effectuer à chacune d'elle, pour assurer la progression de l'instruction d'une demande.

La mission du gestionnaire est donc de faire évoluer le statut d'une demande réceptionnée, en faisant en sorte que les actions requises par un statut soient réalisées ; et ce jusqu'à ce que la demande soit traitée.

L'ergonomie de Publik est conçue pour le métier du gestionnaire : sélectionner les demandes à traiter en fonction de critères et les instruire. Publik permet aussi d'évaluer l'évolution du volume et du taux de traitement de ces demandes.

Sélectionner une demande à instruire

Les démarches à charge du gestionnaire, et par conséquent, les demandes d'usagers qu'elles induisent, dépendent des permissions que lui aura octroyé l'administrateur fonctionnel.

Le gestionnaire des demandes dispose de deux espaces pour visualiser les demandes d'usagers à sa charge.

[La liste des démarches](https://doc-publik.entrouvert.com/agent-traitant/traitement/liste-des-demarches/)

La liste des démarches permet de visualiser les demandes par démarche à charge du gestionnaire, selon leur volume.

Le

[tableau de bord](https://doc-publik.entrouvert.com/agent-traitant/traitement/tableau-de-bord/)

Le tableau de bord d'une démarche permet de visualiser les demandes associées à une démarche.

Des outils sont mis à disposition du gestionnaire pour lui permettre d'orienter son choix d'instruction vers l'une des demandes en fonction d'indicateurs-clés.

Instruire une demande

Une fois sélectionnée, une demande d'usager est susceptible d'être instruite par le gestionnaire en charge du traitement de celle-ci.

Pour faciliter l'instruction des demandes, Publik met à disposition du gestionnairele détail d'une demande, à partir duquel il peut :

* Situer une demande
* Commenter une demande
* Agir sur une demande

* Écrans de traitementListe des tâches (vue globale)Liste des démarchesVue sur une carteTableau de bordVues personnalisées du tableau de bordDétails d’une demande
* Statistiques internes
* Exports

* Tour d’horizonAvoir un comptePortail citoyenPortail agentDématérialiser une démarche en 10 minutes
* Guide de l’agent d’accueilGuichetTéléphoneCourrierSaisie pour le citoyenUtilisation du code de suiviChercher une demandeFiche usagerCréer un compte pour le citoyen
* Guide de l’agent traitantÉcrans de traitementStatistiques internesExports
* Guide de l’administrateur fonctionnelGestion d’identitésStudioCatégoriesFabrique de formulairesFabrique de workflowsImporter et exporter les démarchesModifier le contenu des portailsAgendas : Évènements et rendez-vousCréer des rapports statistiquesDévelopper des applications métier avec PublikProgressive Web App (PWA)Paramétrage avancéLes tutos
* Guide d’administration systèmeArchitectureInstallationExploitation
* Guide de développementContribuer à PublikInstallation d’un environnement de développement localIntégration graphiqueVue d’ensemble sur les connecteursÉchanges avec un logiciel de demandes «métier»Développement d’un connecteur avec PasserelleRaccordement avec un portail métier (SSO)Développement d’une cellule alimentée par JSONAPI de gestion d’identités et d’accès (authentic)Téléservices (w.c.s.)API AgendasAPI PortailsAPI Agendas (ancienne version)
* Glossaire
* Pour aller plus loinListe des connecteursDématérialiser une démarcheTester une démarcheMises à jourCNIL, RGPD et vie privéeUne GRC n’est pas un logiciel de gestion de courrier (GEC)RGAAUne GRC n’est pas un logiciel de gestion de la relation client (CRM)ÉcoconceptionRéférentiel simplicitéComparatif Publik / demarches-simplifiees.fr
* Notes de mises à jourArchives 2024Archives 2023Archives 2022Archives 2021Archives 2020Archives 2019Archives 2018Archives 2017Archives 2016

# Conformité au RGAA

Conformité au RGAA

Leréférentiel général d’amélioration de l’accessibilité(RGAA) s'applique, en France, aux administrations ; la 4ème version de ce référentiel (4.1 publiée le 18 février 2021) s'appuie sur les standards internationaux d’accessibilité, essentiellement lesrègles pour l’accessibilité des contenus webde la norme WCAG (en anglais : « web content accessibility guidelines »), élaborées par le W3C en 2018.Les personnes morales de droit public doivent satisfaire aux critères de succès de ces règles de niveau simple A (A) et double A (AA).

Les briques constitutives de Publik ont été conçues dans le respect des normes du W3C. De nombreuxcritèresdépendant de l'intégration graphique et de la gestion des contenus effectuée par chaque collectivité, uneévaluationdevrait être réalisée par chaque collectivité.

Sur la base de cette évaluation, sera mesuré un taux de conformité qui devra être communiqué aux usagers dans le cadre d'une déclaration d’accessibilité. Il est considéré :

* une conformité totale, si tous les critères de contrôle du RGAA sont respectés,
* une conformité partielle, si au moins 50 % des critères de contrôle du RGAA sont respectés,
* une non-conformité, si moins de 50 % des critères de contrôle du RGAA sont respectés ou s’il n’existe aucun résultat d’audit en cours de validité.

Sur la base d'un audit réalisé en novembre 2018, un site Publik spécifique a obtenu :

* 80 % de critères respectés sur le niveau AA,
* 50 % de critères respectés sur le niveau AAA.

Sur les aspects génériques des intégrations graphiques, nous réalisons les évolutions nécessaires lorsque les audits relèvent des points d'amélioration ; ce fut notammentle cassuite aux résultats d'évaluations, particulièrement détaillées, effectuées fin 2019 et début 2022.

Il faut noter que Publik met en place tout le balisage d'accessibilité pour permettre aux systèmes d'accessibilité natifs, ou installés au niveau du système, de fonctionner optimalement. Seuls ces systèmes permettent réellement une accessibilité globale, cette accessibilité ne peut pas être assurée par des sites (les "outils de surcouche d’accessibilité web") qui chacun à leur manière ajouteraient des dispositifs particuliers.

Pour respecter le RGAA et le système de design de l'État, il est recommandé d'utiliser un libellé explicite et précis pour indiquer aux utilisateurs l'erreur dans leur saisie. Pour chaque erreur de saisie, le type et le format de données attendu doit être indiqué.Ex. « Veuillez saisir un numéro de téléphone à 10 chiffres, par exemple 06 39 98 89 93 »

L'objectif est d'aider les utilisateurs à comprendre précisément quel est le problème avec leur saisie, afin qu'ils puissent corriger leur erreur et continuer leur démarche. Il est également recommandé d’ajouter un texte d’aide (en utilisant la remarque) sous le libellé afin de faciliter la saisie lorsqu'une validation est utilisée.Ex. « Le numéro de téléphone doit contenir 10 chiffres »

* RGAA

# Éco-conception

Éco-conception

Publik est un logiciel libre. Les quatre principes du logiciel libre permettent une amélioration continue des programmes et une plus grande sécurité.

Il y a concordance d’intérêts avérée entre fabricants de matériel informatique et vendeurs de logiciels propriétaires qui provoque l’obsolescence du matériel : les nouvelles version des logiciels seront souvent obligatoires si on veut bénéficier du support de l’éditeur et refuseront de tourner sur un matériel « ancien ». Le logiciel libre casse cette logique puisqu’il ne peut y avoir d’achat forcé de nouvelles versions et que ces dernières fonctionnent avec le matériel utilisé précédemment.

Publik utilise le moins possible des modules externes, afin d’éviter d’avoir du code non-utilisé : cela permet d’avoir de bons temps de chargement et limite la consommation inutile de ressources.

En ce qui concerne l’impression « papier », Publik est conçu de manière à ne pas avoir besoin d’imprimer des états (listings, demandes…) : des exports au format numériques sont possibles et nous privilégions le traitement dans l’interface Publik ou l'inter-opérabilité avec les logiciels métiers. Une impression papier, c’est non seulement une consommation de papier et d’énergie mais aussi une fuite possible de données, parfois sensibles, cela permet par la même occasion de mieux respecter le RGPD.

Entr’ouvert promeut également les démarches les plus simples possibles et la limitation des transmissions de justificatifs. Par exemple, on privilégiera un champ permettant une vérification de la cohérence du numéro de sécurité sociale plutôt que de transmettre une carte vitale au format numérique. De façon encore plus concrète, si la transmission de documents numériques est réellement nécessaire, Publik prévoit le redimensionnement automatique des photos avant transfert et stockage ainsi que la dé-duplication automatique des fichiers des demandes sur les serveurs.

Une attention particulière est portée sur les performances, le poids des pages et les ressources utilisées. L’ensemble du code est exécuté principalement sur les serveurs, ce qui limite l’exécution répétée sur les périphériques et limiter ainsi la consommation électrique de l'ensemble. Publik intègre une gestion de cache qui permet d’optimiser le temps de chargement et les requêtes au serveur. La limitation des traceurs au strict minimum (authentification et sécurité) permet de réduire encore la consommation intempestive de ressources.

Entr’ouvert encourage la mutualisation des ressources via une infrastructure SaaS ce qui permet de réduire l’achat de matériel. L’ajout de ressources est effectué lorsque cela est vraiment nécessaire au bon fonctionnement des applications. Nos serveurs sont hébergés chez OVH qui a mis en place des normes et un suivi strict pour gérer l'impact environnemental :https://corporate.ovhcloud.com/fr/sustainability/environment/

Enfin, en matière de transparence : le code source est accessible depuis notre forge :https://git.entrouvert.org/, la documentation est librement accessible surhttps://doc-publik.entrouvert.com. La vérification de la qualité du code (revue de code systématique) et l’attention que nous prêtons à la sobriété numérique est exposée de manière transparente et peut être vérifiée facilement sur ces supports.

* RGAA

# Une GR « Citoyen » n'est pas un logiciel de gestion de la relation client (CRM)

Une GR « Citoyen » n'est pas un logiciel de gestion de la relation client (CRM)

Les citoyens ne sont pas des clients. Derrière ce truisme, se cachent des enjeux de société majeurs concernant le contrôle de ses données par le citoyen et plus globalement le respect de sa vie privée.

S'il est commun de « profiler » lesclientset de leur « pusher » des informations ayant pour objectif de les faire consommer, c'est un comportement exclu lorsqu'il s'agit d'interagir avec descitoyens.

Il y a des exigences et des lois (CNIL et maintenant RGPD en France, EIDAS au niveau européen) qui visent à s'assurer que cette vie privée est bien respectée. Le simple fait d'afficher l'intitulé d'une démarche à un agent qui n'a pas à la voir peut-être considéré comme une infraction à ces exigences.

Parmi les exigences que les CRM peinent à appréhender :

* La séparation des téléservices en 10 familles étanches (qui imposent l'utilisation de la fédération d'identité).
* Le recueil du consentement exprès et non équivoque du citoyen avant de lui envoyer des infos ou de partager ses informations avec un service tiers.
* La possibilité pour un citoyen de récupérer et/ou d'effacer l'ensemble de ses données lorsqu'il le souhaite.
* L'anonymisation des demandes 3 mois après le traitement.

Si bien qu'un CRM qui sera articulé autour de la recherche et du stockage des demandes ad vitam est très différent d'un outil de gestion de la relation citoyen qui est, lui, focalisé sur les flux et les échanges. Si vous avez besoin d'un CRM, ne choisissez pas Publik, il y a pléthore d'outils qui feront ce travail mieux que notre solution. En revanche, si vous avez besoin d'une solution de GRC/GRU, ne prenez pas un CRM : même à grand renfort de rustines, ils peinent à appréhender ce qui fait le coeur d'une gestion de la relation citoyen.

* RGAA

# Tester une démarche

Tester une démarche

Avant de publier une démarche dématérialisée pour la rendre accessible aux usagers, il convient d'en tester le fonctionnement. Pour tester correctement une démarche, il faut tester ce que voit chaque intervenant (chaque rôle) à chaque étape.

Tester avec plusieurs comptes

Afin de ne pas avoir à jongler avec l'attribution/désattribution de rôles quand on veut les tester, le plus simple est de créer autant de comptes qu'il y a de rôles à tester, et d'attribuer, à chacun de ces comptes, uniquement le rôle que l'on souhaite tester.

Mais la création de plusieurs comptes nécessite d'utiliser des adresses courriels différentes. Vous pouvez utilisez des services commeyopmailqui vont vous permettre d'utiliser des adresses courriels temporaires sans avoir à les créer.

Vous pouvez créer votre compte dans Publik avec comme courriel n-importe-quoi@yopmail.fr, vous pouvez, sans rien avoir de spécial à faire, consulter les mails reçus sur http://www.yopmail.com?n-importe-quoi.

Bien entendu il ne faut pas utiliser de caractères accentués ou d'espace dans ce que vous allez mettre à la plate de « n-importe-quoi ».

Les messages sont effacés au bout de 8h.

Tester avec plusieurs navigateurs

Utiliser plusieurs comptes différents dans un même navigateur n'est pas chose aisée : on peut avoir des problèmes, de cache, de session, de déconnexion incomplète, etc.. Au final on ne comprend plus rien. C'est pourquoi il est vraiment préférable d'utiliser des navigateurs différents pour jouer avec des rôles différents : un navigateur utilisé pour remplir les formulaires en tant que citoyen, un navigateur utilisé pour jouer le rôle de l'agent, un autre utilisé avec son compte administrateur par exemple. Une autre possibilité est de tester à plusieurs dans une même pièce, chacun jouant un rôle différent.

En dépit du conseil qui précède, vous allez parfois utiliser plusieurs comptes dans le même navigateur ou vous attribuer un rôle supplémentaire en cours de route. Il y a alors une chose importante à savoir : pour optimiser les performances, le menu latéral gauche de Publik (qui est pliable/dépliable) est stocké dans le cache. Même si vous fermez/relancez le navigateur, c'est le menu qui est dans le cache qui apparaît et les éventuelles modifications (liées à votre nouveau compte ou à votre nouveau rôle) n'apparaissent pas.La seule façon pour voir le menu latéral mis à jour est d'ouvrir un des éléments du menu dans un nouvel onglet, le menu sera alors correct avec les briques en plus (ou en moins) que vous attendiez.

Les rôles

Tester les workflows c'est synonyme de jouer avec les rôles. Pour attribuer/enlever un rôle à un utilisateur, on va sur l'interface de gestion des utilisateurshttps://xxxxx/manage/users/, on sélectionne l'utilisateur voulu en cliquant dessus, puis on clique sur le bouton modifier à droite, sous Rôles. On coche/décoche alors les rôles souhaités.

Quand on cherche à tester un rôle il estnettement préférable de s'assurer qu'on ne teste que celui-cicela veut dire qu'on doit tester avec un utilisateur ayant ce rôle uniquement et pas un autre. Pour ce faire, il est très utile de se créer un utilisateur de test (ou plusieurs) à qui on va donner le rôle souhaité (créer un utilisateur se fait icihttps://xxxxxx/manage/users/add/). Il faudra ensuite se logguer avec cet utilisateur pour tester le rôle en question.

Tester l'ensemble des intervenants à chaque étape

Chaque fois que vous testez une action/étape de workflows regardez bien ce qui se passe sur vos différents navigateurs (du côté du citoyen d'une part, du côté de l'agent d'autre part - ou des agents s'il y a plusieurs rôles impliqués dans le traitement). Il est indispensable d'utiliser plusieurs navigateurs pour cela.

Tester les mails

Si vous utilisez un utilisateur de test, vous lui avez sans doute donné votre adresse e-mail, et vous recevrez donc à votre adresse les mails destinés au rôle que vous testez, ils peuvent être divers et source de confusion. Il est donc intéressant d'effacer les mails reçus (ou de les classer à part, une fois qu'on a testé un rôle).

Créer des actions globales

Voir page dédiée :https://doc-publik.entrouvert.com/admin-fonctionnel/fabrique-de-workflows/actions-globales/

Une action globale est une action qui une fois créée, au lieu d'être disponible pour un statut particulier, sera disponible dans tous les statuts. C'est très pratique d'en créer au moins une (réservée à un rôle que les agents traitant n'ont pas, pour ne pas les perturber) pour, par exemple, faire remonter une démarche au premier statut du workflow, quel que soit le statut dans le lequel elle se trouvait.

Créer une action globale, c'est :

* Sélectionner un workflow
* Cliquer sur "ajouter une action globale" et choisir le nom de cette action
* Choisir un "déclencheur" (ce qui va activer l'action). Ici c'est un déclencheur manuel, c'est à dire un bouton pour lequel on indique le rôle qui pourra l'utiliser ("administrateur des démarches")
* Choisir l'action qui sera effectuée. Ici c'est un changement de statut vers la première (ou une autre !) étape de notre workflow.

Utiliser lespages d'inspection

Pour une demande

Lorsque l'on souhaite voir l'ensemble des variables (et leurs valeurs) contenues dans une demande on peut ajouter «  inspect » à la fin de son URL dans le backoffice. Si l'on traite une demande ayant pour URL :

https://demarches-publik.entrouvert.com/backoffice/management/contacter-entr-ouvert/3/

On obtiendra la vue debug en allant sur :

https://demarches-publik.entrouvert.com/backoffice/management/contacter-entr-ouvert/3/inspect

Pour un workflow

De la même façon, il est possible d'utiliser une vue synthétique du workflow pour mieux en saisir le déroulé. Si l'on travaille sur un workflow ayant pour url :

https://demo.dev.entrouvert.org/backoffice/workflows/22/

On obtiendra la vue synthétique en allant sur :

https://demo.dev.entrouvert.org/backoffice/workflows/22/inspect

* RGAA

# Référentiel simplicité

Référentiel simplicité

Avant propos

Il existe nombre de référentiels aux finalités différentes et dont l'utilité n'est pas à discuter (RGAA pour l’accessibilité, RGS pour la sécurité, RGI pour l’interopérabilité, RGPD pour la protection des données personnelles et DSFR pour le Système de Design de l'État).L'objectif n'est pas de surcharger encore en exigences, mais de présenter des bonnes pratiques et des principes de simplicité avec Publik.Comme beaucoup de référentiel, libre à chacun de se l'approprier et de l'appliquer en tout ou partie.Nous illustrons l'approche par deux verbatim :

« Faire simple ne doit pas être compliqué. »« Ce n'est pas parce que beaucoup est permis, qu'il faut faire n'importe quoi. »

Encourager et interpeller

* Préférez une incitation plutôt qu'une injonction. Les libellés des champs des formulaires peuvent être tournés sous forme de questions explicites (hors nom, prénom...). Exemple : « Quelle taille de composteur souhaitez-vous ? » au lieu de « Taille du composteur ».
* Personnalisez l'information à l'utilisateur dans les démarches, courriers, etc. L'information donnée à l'usager peut être personnalisée en fonction du service sollicité et de ses réponses. Il est proposé d'apporter le maximum de détails explicites lorsque cela est possible. Exemple : confirmation d'un rendez-vous avec la date et le lieu plutôt qu'un simple courriel sans précision. D'une manière générale, il n'y a pas d'étude ni de certitude que nommer l'usager dans les échanges améliore la GRU (exemple : Bonjour prénom nom) : libre à chacun de le faire.

Simplifier

* Chassez la surabondance d'informations ou les besoins trop larges. Il est important de bien cadrer la finalité et le service à proposer.
* Simplifiez avec les usagers, impliquez-les dans le cadre d'une amélioration continue. Les remarques et suggestions des citoyens et des agents sont utilisées pour améliorer en continu les démarches.
* Évitez d'utiliser l'italique, le gras, les parenthèses. Ce sont parfois des artifices pour essayer de clarifier une information trop complexe et qui nuisent à l'accessibilité.

Limiter

* Limitez. Comprendre une liste de 50 éléments est plus difficile et chronophage que comprendre une liste de 7 éléments. Dans la mesure du possible, limitez le nombre d'éléments des champs liste, nombre de pages, etc.

Il faut trouver l'équilibre entre présenter l'exhaustivité des choix sans perdre l'usager dans un dédale de choix.

Uniquement l'essentiel à l'instant T

* L'information donnée, comme l'information demandée, doit être proposée au moment opportun pour être percutante et appréciée. (proposez « entrée » puis « plat » puis « dessert » plutôt que « buffet » dès l'entrée dans le formulaire)
* Respectez le principe : l'utilisateur peut saisir uniquement les informations qu'il possède à l'instant T. Exemple : Les informations de qualification et traitement pourront être apportées dans le workflow.
* Dans les formulaires, limitez-vous aux champs strictement nécessaires à la demande et évitez tous les champs facultatifs.

Si un champ est nécessaire, il faut trouver la condition pour laquelle il doit être affiché et le rendre éventuellement obligatoire.Exemple : il n'est pas nécessaire de demander l'adresse postale ou le numéro de téléphone si vous ne les utilisez pas.

Tu ne répéteras pas, Tu ne répéteras pas, Tu ne répéteras pas

* Évitez de dupliquer la même démarche chaque année, et préférez une générique. Exemple : « S'inscrire à la fête de la mirabelle 2022 » « S'inscrire à la fête de la mirabelle 2023 » « S'inscrire à la fête de la mirabelle 2024 » « S'inscrire à la fête de la mirabelle 2038 »... vous pouvez proposer une démarche « S'inscrire à la fête de la mirabelle ».
* Ne répétez pas des champs dans le formulaire : si vous répétez systématiquement un champ pour différentes situations, il vaut mieux en utiliser un seul et améliorer la condition d'affichage.

Sois hOmogènE

* Soyez constant et homogène dans votre approche et votre charte éditoriale. Exemple : Commencez les titres des formulaires par un verbe d'action. Utilisez le même libellé et identifiant pour le même champ sur tous les formulaires (exemple : courriel).
* S'adresser à l'usager de la même manière d'un formulaire à un autre. Exemple : à la première personne « j'ai / Mon » , ou à la 2e personne : « Vous / Votre ».
* Classez et rangez
* Respectez des conventions de nommage.
* Dans le cas de plusieurs rédacteurs de démarches, il pourra être utile de rédiger une charte éditoriale du portail des démarches.

« Merdique ton français ne doit pas être » versus Simplifier le langage administratif

* Faites des phrases à la forme active (contrairement à la forme passive), courtes et positives.
* Utilisez des termes lisibles et compréhensibles. Vous pouvez vous inspirer du lexique administratif ou chercher le bon vocabulaire avec les utilisateurs.
* Utilisez un langage clair : les explications sont sans ambiguïté, les mots utilisés sont accessibles à tous et ne posent pas de problème de compréhension ;
* Quand vous utilisez un sigle ou un acronyme pour la première fois, développez-le pour en donner la signification. Exemple: « Vous avez rendez-vous avec un Référent Entretien d'Orientation (ROP) à la Maison De la Solidarité (MDS)... »  plutôt que « Vous avez rendez-vous avec un ROP à la MDS ».

Rangement et convention de nommages

Cette section décrit les bonnes pratiques du « low code » de l'écosystème Publik.Cela peut paraître anodin, mais ranger et bien nommer les éléments participent à la simplicité, la cohérence et la maintenabilité d'un écosystème.Si vous travaillez seul, c'est de la rigueur ; si vous travaillez à plusieurs, c'est une nécessité : une charte de nommage.

Catégoriser

* Utilisez et rangez dans des catégories. Les catégories sont utiles pour ranger des éléments (formulaire, workflow, agenda, fiche, etc.) en back-office, mais également à donner des accès en front office pour les formulaires.
* Dans l'idéal, les catégories doivent apporter une cohérence entre les catégories de formulaires, de workflow, d'agendas. Exemple: «État-civil » pour les formulaires, les workflows et les agendas

Respecter la CaSsE

* Soyez cohérent sur la casse. Exemple : commencez toujours pas une majuscule, ou jamais.
* Mettez en minuscule systématiquement les identifiants des champs (exemple : commune, id_procedure, date_naissance) et soyez cohérent dans les identifiants composés. Exemple : nom_parent, prenom_parent et pas nomParent, Prenom_parent.

Préfixer

* Généralisez l'utilisation de préfixes pour mieux identifier et ranger. Exemple : État-civil - Responsable,  État-civil - Agent. Les préfixes peuvent être utilisés sur les fiches, workflows, rôles, variables, agendas, modèles de mail.
* Préfixez les agendas par le lieu. Exemple : Mairie centrale - CNI & passeports ; Mairie centrale - dépôts de dossiers ; Mairie annexe - CNI & passeports ; Mairie annexe - dépôts de dossiers.
* Préfixez les sources de données. Exemple : API entreprise - entreprise ; API entreprise - Établissement.
* Préfixez avec la même syntaxe. Exemple toujours : [préfixe] xxx ; ou toujours : Préfixe - xxx.
* Préfixez le rôle par le nom de la commune et le nom du service.

Nommer

Les formulaires

* Un titre de formulaire commence toujours par un verbe d'action, pour être explicite sur la finalité de la démarche et sur l’action attendue par l’usager. Exemple : « Consultation citoyenne » est un titre à vague. Vous pouvez préciser la finalité « Participer à la consultation citoyenne », « Proposer une consultation citoyenne », etc.
* Un formulaire et son workflow associé portent le même nom si le workflow est dédié à ce formulaire.

Les statuts

* Utilisez des noms simples pour les statuts : « Traité » et pas « Dossier Traité ». « Transmis » et pas « Votre demande a été transmise à nos services ».  Les noms de statuts longs sont plus difficiles à lire dans les pages de traitement, filtres, conditions, etc. Mais le statut peut s'accompagner d'un message dans l'historique : « Votre demande a bien été transmise à nos services. »
* Soyez cohérent sur le nom des statuts sur tous les workflows. Exemple : ne pas utiliser « En cours ». ou « En cours de traitement » alternativement.
* Le nom des statuts doit être un qualificatif de la demande et pas un verbe à l'infinitif. Exemple : « Traité » et pas « Traiter ».

Les workfows

* Les libellés de boutons (sauts manuels) commencent par un verbe d'action. Éventuellement ils peuvent commencer par un pictogramme. Exemple : « ✅ Accepter la demande ».
* Les libellés de boutons explicitent la suite du traitement. Évitez « Continuer » ou « Valider ».

Les rôles et les fonctions

* Les noms de fonctions et de rôles peuvent être au pluriel ou au singulier. Faites un choix et appliquez-le.
* Évitez les sigles. Quand vous utilisez un sigle ou un acronyme pour la première fois, développez-le pour en donner la signification. Exemple: « Vous avez rendez-vous avec un Référent entretien d'orientation (ROP) à la Maison de la Solidarité (MDS)...  » plutôt que « Vous avez rendez-vous avec un ROP à la MDS ».

Les blocs de champs

* Les blocs peuvent être au pluriel ou au singulier. Faites un choix et appliquez-le.

Les modèles de fiches

* Les modèles de fiches ont des noms au pluriel ou au singulier. Faites un choix et appliquez la même règle de nommage.  Ecrire les noms des modèles de fiches au pluriel permet de faire la différence avec une fiche et un modèle de fiches : le modèle de fiche "vélos" contient une ou des fiches "vélo".

Les identifiants

* N'utilisez pas les motsformouvardans le nom des identifiants.

Spécificités

L'écosystème Publik propose des fonctionnalités toujours plus nombreuses : formulaires, workflows, agendas, blocs de champs, fiches, etc.L'objectif de ce paragraphe n'est pas de reprendre les conventions de nommage décrites ou convenues préalablement mais de donner des bonnes pratiques sur les fonctionnalités.

Des formulaires

* Le titre des formulaires est affiché à l'usager, il doit être compréhensible par l'usager.
* Le titre doit expliquer la finalité de la démarche.
* La première page du formulaire doit expliquer succinctement mais clairement le contexte de la démarche, parce que le référencement des démarches fait que l'usager peut arriver directement sur la démarche. Éventuellement ce texte de présentation peut être marqué par la classe pk-information.
* Le formulaire doit être clair et permettre à l’usager de se repérer facilement dans les différentes pages à remplir.
* S'il y a plusieurs collectivités, l'émetteur de la démarche doit être indiqué sur la première page du formulaire.
* Le plus souvent possible, activez le code de suivi car il permet de retrouver une démarche sans compte et désactivez la page de confirmation.
* Positionnez les champs toujours dans le même ordre. Exemple : prénom puis nom. Un prénom est, étymologiquement, AVANT un nom.
* Trouvez l'équilibre entre chaque page, évitez les pages trop longues et évitez de démultiplier de nombreuses pages trop courtes.
* Évitez les champs non obligatoires. C'est peut être que le champ n'est pas essentiel. Si un champ est nécessaire, il faut trouver la condition pour laquelle il doit être affiché et le rendre obligatoire.
* Privilégiez les champs « Liste » au champs « Texte » pour le principe de « statistic by design » et « privacy by design ».
* Les champs « Liste » ont des éléments courts, sans condition. Exemple de liste à éviter : « je suis d'accord et souhaite une livraison à domicile », « je suis d'accord et souhaite retirer ma carte à la mairie ».
* Dans un champ de type « Fichier », gérez la taille des fichiers, ou en sélectionnant « Réduire automatiquement la taille des images », ou en indiquant la « Taille maximale du fichier ».
* Si des limitations sont posées, contrôlez-les avec des conditions. Exemple : s'il y a une limite à 60 personnes, vous pouvez ajouter une condition de sortie de page.
* Proposez les pages identifications (prénom, nom) en fin du formulaire, si ces informations ne conditionnent pas la démarche. Les premiers éléments du formulaire doivent être ceux qui expliquent ou mettent le plus en valeur la finalité de la démarche. La page d'identification peut être présentée en début, si elle conditionne la suite du formulaire. Exemple : pour demander un composteur, la première question pourrait porter sur la taille du composteur, la situation du demandeur, plutôt que sur l'identification du demandeur. Dans la logique des sites e-commerce, le produit ou service est mis plus en avant que l'identification de la personne sauf si l'identification de la personne définit le produit/service.
* Préremplissez les champs : quand cela est possible préremplissez les champs, l'utilisateur n'aura qu'à les vérifier.
* Vérifiez les champs : ajoutez systématiquement une règle de validation dès que cela est possible.
* Dans les champs « Liste », ne laissez pas une valeur par défaut. L'utilisateur doit choisir explicitement une valeur. Exemple. indiquer en remarque --- Sélectionnez ---.

Des variables

* Utilisez les variables définissant les URL des briques : {{ passerelle_url }}, {{ agendas_url }}, etc., plutôt que les URL en dur.
* Indiquez systématiquement un identifiant pour chaque champ.

Des rôles et fonctions

* Utilisez toujours les fonctions dans les workflows : n'utiliser pas les rôles sauf dans l’action « liaison fonction-rôle».
* Ne configurez jamais d'adresse électronique personnelle dans les workflows.
* Optimisez la gestion des rôles en utilisant les options avancées et les mécanismes d'héritage : « Contient les permissions des rôles », « Est géré par le(s) rôle(s) ».

Des workflows

* Minimisez le nombre de statuts. 20 statuts c'est déjà beaucoup.
* Utilisez les variables autant que possible de manière à pouvoir mutualiser au maximum les workflows.
* Ne dupliquez pas un statut pour une simple condition avec les mêmes actions, mais préférez un unique statut. Exemple : « Transféré au service A », « Transféré au service B », ...« Transféré au service Z » peut être fait avec un statut « Transféré » et une donnée de traitement. Cela évite les workflows complexes et de reproduire l'organigramme.

Des statuts

* Déterminez le code couleur pour les statuts et utilisez-le systèmatiquement. Exemple : vert = nouveau ; bleu = en cours ; rouge = rejeté ; gris = terminé ; blanc = masqué à l'usager, jaune = affectation, noir = erreur.
* Soyez le plus transparent possible dans vos workflows. Ne cachez à l'usager que les statuts qui ne lui apportent pas d'informations utiles.

Des fiches

* Renseignez un gabarit générique afin que la fiche puisse être utilisée en source de données, même si vous prévoyez des vues personnalisées utilisées comme sources de données.

Des modèles de courriel

* Harmonisez les sujets des courriels en précisant le statut, et le numéro de la demande. Exemple : {{ form_name }} - n° {{form_number}} {{form_status}}.
* Rappelez à l'usager comment retrouver sa demande : lien, code de suivi. Dans les courriels vous pouvez utiliser la syntaxe suivante:

{% if  form_user %}
    Vous pouvez consulter votre demande sur {{ form_url }}.
    {% else %}
    Vous pouvez consulter votre demande sur {{ site_url }} avec le code de suivi {{form_tracking_code}}.
    {% endif %}

* Utilisez les variables autant que possible ({{ form_name }}, {{ form_details }}...) de manière à pouvoir mutualiser au maximum les modèles.
* Harmonisez les signatures des courriels.
* Évitez les images dans les courriels car vous augmentez le risque d'être considéré en SPAM, ce n'est pas accessible, cela charge les courriels inutilement et les lecteurs n'affichent pas les images systématiquement (Adieu les beaux templates de courriel !).

Des conditions

* Rassemblez les champs avec une même condition dans une même page, plutôt que des conditions sur tous les champs.
* Écrivez les conditions en Gabarit (Django) et ne pas utiliser du Python (qui est en cours de dépréciation).

Des agendas

* Dans les agendas de type « évènements », vous pouvez renseigner le « Gabarit d’affichage d’un événement » dans les options, pour éviter de ressaisir à chaque fois un nouveau libellé.
* Ne mettez pas les places disponibles dans ce gabarit d’affichage sinon vous allez enregistrer et afficher dans les demandes d’inscriptions des informations de places qui seront vite obsolètes.
* Dans les agendas de type « Rendez-vous », renseignez le nom du guichet qui pourra être présenté à l'usager. Exemple : Hôtel de Ville - Guichet 1.
* Dans les agendas de type « Rendez-vous », utilisez dans la mesure du possible des durées de rendez-vous, qui sont des multiples entre eux. Cela permet d'éviter les « trous » dans les agendas. Exemple : 15min, 30min, 45min

Du profil utilisateur

* Dans la mesure du possible limitez les champs du profil utilisateur au strict minimum.

Méthodologie

Publik est simple et puissant. Il offre différente façon de faire pour arriver au même résultat, en fonction de l'expérience de chacun. Certaines façons sont meilleures que d'autres, voici quelques règles et bonnes pratiques.

Pour commencer

* Définissez la finalité du dispositif : la finalité est l'expression de la raison d'être du service, éventuellement de la valeur ajoutée offerte pour l'usager ou le public ciblé. Elle doit être précise.
* Commencez par une version simple du formulaire. Il n'y a pas de honte à faire simple.
* Commencez par une version simple du workflow ou processus de traitement. Il n'y a pas de gloire à faire compliqué.
* Définissez les éléments de réponse (courriel, suivi dans l'historique), toujours clairs pour l'usager.
* Testez la version et impliquez les agents, et les usagers si possible, pour faciliter l'appropriation de tous.
* Toujours rester au plus près du besoin. Gérez le 80% des demandes. N'essayez pas de gérer les exceptions, mais notez les (nous y reviendrons).
* Travaillez l'anonymisation et la durée de conservation des démarches et des agendas avec le DPO et l'e-archiviste.

Pour améliorer ses réalisations

Rapidement vous arriverez à une première version : « une pièce à casser ».

* Testez et essayez de casser la « pièce à casser ».
* Améliorez, simplifiez.
* Consultez la documentation et chassez le déprécié.
* Utilisez les fiches.
* Gérez une exception à la fois.
* Essayez de simplifier vos démarches avec des API et données fiables.
* Recommencez à l'action 1.

Pour suivre le cycle de vie d'une réalisation

* Travaillez dans l'environnement de recette.
* Testez.
* Versionnez son travail en recette et en production. Faites une sauvegarde (version) du formulaire et workflow.
* Importez dans l'environnement de production.
* Testez. La pression monte !
* Publiez. Ça marche ? Se féliciter. Ça ne marche pas ? Retournez à l'action n°1.
* Dé-publiez, seulement quand le dispositif n'est plus nécessaire.

Pour éviter la casse

* Ne supprimez jamais des choses en production, sans être certain du risque encouru. Vous pouvez éventuellement masquer des champs avec des conditions.
* Lors des imports (formulaires, workflows, paramètres) assurez-vous qu'il n'y a pas de champs et de données de traitement supprimés par rapport à la version en production.
* Ne supprimez pas les formulaires, sauf les créations ou imports par erreur. Cela supprime définitivement les demandes de façon irréversible. Et il n’y a pas de raison de supprimer un formulaire utilisé. On le dé-publie et on annote éventuellement « Archive » dans son titre.

Pourchasser le déprécié

Des éléments fonctionnent encore, mais nous apportons peu d'attention à leur fonctionnement, il est donc conseillé de les remplacer dès à présent.Chasser le déprécié c'est faire mieux et plus simple.

Conclusion

Publik s'enrichit et évolue : les bonnes pratiques aussi !Des choses compliquées deviennent simple ? C'est bon signe. Proposez les, continuez...

* RGAA

# Mise à jour

Mise à jour

En général (en tout cas, c'est que nous faisons à Entr'ouvert;-), vous disposez d'une plate-forme de production et d'une plate-forme de test, voici quelques règles pour gérer correctement ces deux installations.

En premier lieu, sachez qu'il n'y a pas de magie, il n'est pas possible de copier une partie d'une plate-forme vers l'autre sans intervention humaine, le fonctionnement de base étant une copie complète et écrasement des données pré-existantes.

Il faut distinguer les modes opératoires préalablement à la première mise en production des mises à jour, de la plate-forme de production, ultérieures.

* Première mise en production : il est possible de créer la plate-forme de production par la copie complète de l'installation de test ; pour ce faire, il aura été nécessaire de nettoyer préalablement la plate-forme de test des essais temporaires (qui auront été précisément identifiés au préalable pour pouvoir les supprimer sans hésitation). Nota bene : il pourra être nécessaire d'adapter des liens URL en dur (liens vers des formulaires, liens vers des ressources graphiques sur les portails Combo)
* Mises à jour ultérieures : il s'agit du cas où la plate-forme est déjà ouverte, un certain nombre de démarches en ligne déjà utilisées par les usagers et qu'il est souhaité modifier ces démarches ou en ajouter de nouvelles. Dans ce cas de figure, il n'est plus possible de faire une copie de masse mais uniquement des copies partielles, il est préférable de copier les éléments dans l'ordre suivant : connecteurs vers des logiciels tiers, sources de données, rôles, workflow puis enfin formulaire (vous pourrez vérifier sur la page de détail du formulaire la bonne prise en compte des rôles et variables du workflow.

Première mise en production

* Récupérer les éléments de la charte graphique validés
* Noms de domaine (CNAME vers *.entrouvert.org en mode SaaS)
* Certificats
* Adresse de l'expéditeur de mail
* Configuration du serveur mail pour échapper aux antispam (règle SPF en mode SaaS)

Mises à jour ultérieures de la production

Une fois une démarche (formulaire et workflow) en ligne en production, il est indispensable de conserver celle-ci à l'identique sur la pré-production afin de pouvoir effectuer des tests valables :

* s'il s'agit d'ajustements mineurs, ceux-ci peuvent être réalisés sur le formulaire ou le workflow de test, validés puis reproduits en production (soit par modification en production, soit par export du workflow de test puis ré-import sur la production).
* s'il s'agit de modifications importantes, tels par exemple une modification de workflow en relation avec l'évolution d'un connecteur, il est préférable de réaliser préalablement ses tests sur des copies (clairement identifiées par un suffixe [TEST] ou rangées dans une catégorie"test"), puisqu'il est possible que cette version alternative ne doive pas être gardée. Après validation, il est alors possible d'écraser la version opérationnelle puis la passer en production.

Rôles et utilisateurs

Il est nécessaire de s'assurer que les rôles appelés dans la démarche existent bien sur la plateforme de production et que les utilisateurs ad-hoc les aient d'attribués. Afin de faciliter ce contrôle par une vue globale, il est vivement conseillé de n'utiliser que des fonctions et non pas des rôles directement dans les workflows, l'intégralité des rôles agissant dans le cours du workflow étant alors listés sur la page de détail du formulaire.

Sources de données

Les sources de données (tables csv) doivent être copiés ou mises à jour sur l'installation de production préalablement à la mise en production d'un formulaire qui y ferait appel.

* RGAA

# Une GRU n'est pas un logiciel de gestion de courrier

Une GRU n'est pas un logiciel de gestion de courrier

Une GRU se doit d’être en capacité d’enregistrer des demandes issues de plusieurs sources d’entrée (multicanal) et même de les croiser (cross-canal)

Le courrier postal est un canal parmi d’autres son importance tend à diminuerdans le cadre de la relation avec les usagers. Le volume postal diminue lorsque l’on met en place une GRU de qualité. Il convient donc de s’écarter des visions qui voudraient faire du courrier papier, le cœur d’une GRU dans l’objectif d’appliquer à la dématérialisation des procédures obsolètes, pensées pour les circuits papier.

Une solution de GRU doit être en capacité de gérer les demandes qui arrivent par courrier, le courrier étant un des canaux que gère une GRU multicanal, tout comme l’accueil au guichet ou les appels téléphoniques.

Si la GRU doit pouvoir s’interfacer avec différents logiciels de GEC (gestion électronique du courrier papier), elle ne peut être considérée comme un logiciel de GEC à part entière.

Les GEC voulant se faire GRU

Constatant que le volume de plis papier est en perte de vitesse, certaines GEC tentent de se transformer en solution de Gestion de la Relation Usager.

Il y a pourtant une différence fondamentale qui les empêchera toujours de mener à bien et parfaitement cette reconversion, sauf à juxtaposer deux outils réellement différents.

Une GEC, comme une GED, est en effet basée sur le stockage, le document, la conservation, la recherche.

La GRU, au contraire, est basée sur l’échange, le flux et sur l’anonymisation(elle se prête donc bien mal à la conservation et à la recherche, respect de la vie privée oblige).

Avec une GEC devenue GRU, on souhaitera logiquement donner une place centrale au logiciel de gestion de courrier (auquel on intègre, une GED, un parapheur, la gestion des mails, etc.). Alors que d’unpoint de vue GRU, le courrier n’est qu’un canal entrant et/ou sortant.

Que peut faire une GRU avec les courriers ?

La GRU doit permettre d’associer des courriers et des demandes citoyennes : chaque fois qu’un courrier comprend une ou plusieurs demandes citoyennes, la GRU permet de faire l’association entre le courrier en question et des démarches en ligne existantes, via un écran spécifique.

Essayons de récapituler ce qui se passe dans les deux solutions (une GEC et la GRU) lorsqu’un courrier arrive dans une collectivité :

* Il y a uncircuit de gestion du courrier(assuré par la GEC) qui n’est pas lecircuit de traitement de la demande citoyenne(ce dernier est assuré par la GRU).
* Un agent du service courrier numérise le courrier. Soit il s’agit d’un courrier qui ne concerne pas une démarche citoyenne (facture, certificat médical, pub, etc.) et la GRU n’est pas concernée, soit il concerne une démarche citoyenne et il rejoint un dossier « demandes citoyennes » visible par la solution de GRU.
* Il peut rejoindre en même temps d’autres bannettes de la GEC, parce ’que plusieurs services doivent le voir pour information/conservation/stockage.
* Mais c’est exclusivement dans la GRU que se fait l’association entre ce courrier et une démarche d’une part, le traitement de la demande d’autre part. Le courrier restera visible dans la GRU pendant tout le temps du traitement.
* En fin de traitement, la GRU alerte la GEC pour lui signifier que la demande est traitée et que le courrier de réponse peut être envoyé, signé, etc.

Que ne peut pas faire une GRU avec les courriers ?

Une GRU est dans l’incapacité :

* De traiter les courriers qui ne sont pas des demandes citoyennes (les factures, les colis, les arrêts de travail, les échanges inter-administrations, les publicités, etc.). C’est souvent la plus grosse partie du courrier.
* D’intégrer l’ensemble de l’organigramme de la collectivité pour gérer la distribution du courrier en interne : c’est le travail d’une GEC, la GRU ne fait circuler que les demandes (auxquelles un courrier est parfois associé).
* De stocker les courriers. Ces derniers doivent (obligation légale) disparaître de la GRU trois mois après le traitement de la demande, au moment de l’anonymisation.

* RGAA

# Argumentaire Publik vs démarches simplifiées

Argumentaire Publik vs démarches simplifiées

* Publik est une offre complète incluant hébergement et assistance fournis par Entr'ouvert
* demarches-simplifiees.fr proposé par l'Etat : hébergement offert mais pas d'assurance quant à l'assistance en cas de montée en charge.

 | Publik | demarches-simplifiees.fr
------------------------------------
Fonctionnel : Portail citoyen | Oui | Non
Fonctionnel : Démarches sans authentification | Oui | Non
Fonctionnel : Fourniture d'un code de suivi | Oui | Non
Fonctionnel : Démarches internes | Oui | Non
Fonctionnel : Démarches réservées à certains profils connus (parents, association, entreprises…) | Oui | Non
Fonctionnel : Gestion du multi-canal (téléphone, courrier, guichet, email…) | Oui | Non
Fonctionnel : Génération de document (ex : arrêté) | Oui | Non
Fonctionnel : Prise de Rendez-vous | Oui | Non
Fonctionnel : Notification SMS aux usagers | Oui | Non
Fonctionnel : Notification mail aux usagers | Oui | Oui
Fonctionnel : Notification sur tableau de bord | Oui | Oui
Fonctionnel : Notification sur bureau | Non | Oui
Fonctionnel : Réservation de salles et d'évènements | Oui | Non
Fonctionnel : Porte-document usager | Oui | Non
Fonctionnel : Mise à disposition de document | Oui | Oui
Fonctionnel : Gestion automatique de l'anonymisation | Oui | Non
Fonctionnel : Statistiques sur mesure | Oui | Non
Fonctionnel : Base de connaissance | Oui | Non
Fonctionnel : Paiement en ligne | Oui | Non
Fonctionnel : Différents rôles / niveaux d'instructeurs | Oui | Non
Fonctionnel : Construction de circuit de traitement sur mesure par démarche | Oui | Non
Fonctionnel : Connexion aux applications Métiers | Oui | Non
Critique : Support professionnel réactif | Oui | Non
Divers : Personnalisation graphique à la charte graphique de la collectivité | Oui | Non
Divers : Personnalisation graphique avancée similaire au site de la collectivité | Oui | Non
Divers : Partage des formulaires entre collectivités | Oui | Oui
Divers : Partage des workflows entre collectivités | Oui | Non
Divers : Entièrement sous licence libre | Oui | Oui
Divers : Réversibilité possible | Oui | Non
Technique : Hébergé chez OVH | Oui | Oui
Technique : Nom de domaine personnalisé à la collectivité | Oui | Non
Technique : Définir l'administration comme émettrice des emails qui sont envoyés | Oui | Non
Technique : Export par API des données des formulaires | Oui | Oui
Technique : Fonctionnement en progressive Web App | Oui | Non
Technique : Possibilité de l’installer en cloud privé ou hébergement sur site | Oui | Non
Technique : Utilisation FranceConnect | Oui | Oui
Technique : Fédération d'identité ou SSO avec d'autres applications | Oui | Non
Technique : Utilisation des API data.gouv.fr | Oui | Oui
Technique : Utilisation de la BAN et API Geo | Oui | Oui
Technique : Utilisation du SIG choisi par la collectivité | Oui | Non

* RGAA

# Mémo d'aide à la dématérialisation

Mémo d'aide à la dématérialisation

Cette page est un guide visant à vous aider dans la définition d'une nouvelle téléprocédure pour votre plateforme de téléservices. La mise en place des téléprocédures est, pour une bonne part, liée à l'existant et sans aucun rapport avec des outils. Elle nécessite avant tout de mettre en œuvre votre esprit d'analyse et de synthèse.

La définition d'une téléprocédure telle que nous l'envisageons ici est en revanche fortement liée à notre plateforme de GRC, elle repose sur nos ateliers de conception de formulaires et de workflows ; si cette définition reste avant tout une transposition complète ou partielle de l'existant, elle est aussi, en procédant de la sorte, directement corrélée au paramétrage et aux fonctionnalités de l'application.

La procédure

Procédure pré-existante ou nouvelle

Lorsque la procédure à mettre en ligne est entièrement nouvelle, nous avons à la fois plus de latitude (nous ne sommes pas liés à un existant) dans sa définition, et moins de certitudes (les informations à récolter et le circuit de traitement à mettre en place ne sont pas éprouvés), ce qui implique une vigilance accrue.

Mais dans la plupart des cas, la dématérialisation concerne des procédures pré-existantes et nous nous focalisons sur ce cas de figure. Pour ces dernières, le moment de la dématérialisation peut être celui où l'on s'interroge sur leur adéquation, leur conformité au besoin et leur éventuelle modernisation.

Le formulaire papier

Le formulaire papier permet de savoir avec précision quelles sont les informations demandées à l'usager mais aussi parfois de nous renseigner sur certaines étapes de traitement (cadre « réservé à l'administration »).

Il n'est donc pas nécessaire de procéder à une quelconque formalisation supplémentaire le concernant, avant de se confronter à l'outil de fabrique des téléprocédures.

Le circuit de traitement de la procédure

La création informatique d'un processus de traitement nécessite de connaître le traitement pré-existant. Définir le processus de traitement dans l'application permet d'assurer le respect des circuits qu'une démarche peut emprunter.

Mais il faut avoir en tête que ce processus de traitement permettra également à l'usager de suivre l'état d'avancement de sa démarche.

Les étapes actuelles de traitement

La première chose à faire est d'inventorier et de nommer les différentes étapes par lesquelles une demande est susceptible de passer. Il est fondamental d'envisager ici tous les cas de figure. Pour cela, il faut étudier concrètement un échantillon représentatif des démarches en cours, et noter les différentes étapes par lesquelles elles passent.

Les actions des agents

À chaque étape, certaines personnes ont la possibilité de faire évoluer la demande (accepter, refuser, soumettre à validation, demander des informations complémentaires, etc.). Il faut faire l'inventaire de ces actions possibles, étape par étape.

Le rôle des agents en charge du traitement

À ce stade il est important de lister les différents intervenants et leur rôle. Les notions de validation hiérarchique, de passage en commission, conseil… devront apparaître dans le circuit de validation.

La téléprocédure

L'existant doit-il être conservé à l'identique ?

La mise en ligne d'une démarche est rarement une simple transposition du papier vers l'écran, l'ergonomie des deux médias étant différente.

Refonte du formulaire papier

La dématérialisation est parfois le bon moment pour réfléchir sur l'existant. Les formulaires papiers devront-ils être saisis dans l'outil par les agents ? Dans ce cas une adéquation dans le séquençage des champs du formulaire papier et du formulaire électronique peut être utile ; cette adéquation facilitera la saisie par les agents.

Modification/structuration des procédures de traitement

Parfois les procédures de traitement reposent sur des organisations de personnes. Ce n'est pas un problème en soi et ce comportement peut être reproduit dans l'application. Néanmoins cela peut être problématique lorsque ce fonctionnement engendre des dysfonctionnements ou qu'il est remis en question (lors de l'absence d'un agent par exemple).

Dans l'étape précédente vous avez formalisé la procédure et vous avez peut-être mis à jour des imperfections. Le moment est opportun pour s'interroger sur la possibilité d'y remédier.

Composition du formulaire

Techniquement, le formulaire papier peut être reproduit à l'identique dans l'application.

Toutefois, il est nécessaire de vérifier que toutes les données collectées sont rigoureusement indispensables au traitement de la demande : la dématérialisation de la demande la soumet en effet aux contraintes de la CNIL qui interdit de stocker de manière informatique des données qui ne seraient pas indispensables au traitement de la demande en cours.

On réfléchira également à l'éventualité d'enrichir le formulaire avec des informations supplémentaires (aides à la complétion ou à la compréhension de la démarche).

On définira le caractère obligatoire ou facultatif des différents champs.

On appliquera d'éventuels contrôles concernant la conformité des informations saisies par l'usager.

On veillera enfin à préremplir le formulaire avec toutes les informations dont la collectivité dispose déjà.

Circuit de traitement de la demande

Informatiser entièrement un circuit de traitement est contraignant et vous oblige à une certaine exhaustivité : oublier une étape gênera les agents de terrain dans leur travail. Heureusement, l'outil vous permet de compléter un workflow si jamais une étape était oubliée ou si tout simplement la procédure venait à évoluer.

Schéma du workflow

Les différentes étapes identifiées pendant la phase d'analyse sont créées comme autant de statuts dans l'application.

La première chose à faire ensuite est d'établir les relations entre ces statuts : comment passe-t-on d'un statut à l'autre ? Les actions « changement de statut » doivent être configurées pour chaque étape ce qui permet dès lors de disposer d'une représentation graphique du circuit de traitement. Il faut éventuellement modifier les statuts et ces actions jusqu'à ce que cette représentation graphique soit cohérente.

Mise en place des rôles

Tous les rôles apparaissant dans le workflow doivent être créés dans l'application avant de s'intéresser aux actions pouvant être menées.

L'association entre ces rôles et des utilisateurs réels peut se faire ultérieurement. Au moment de cette association, il faut choisir entre le fait d'adresser les courriels à une adresse spécifique au dit rôle ou aux adresses de tous les utilisateurs possédant ce rôle.

Les envois de mails et messages

À chaque étape, des mails, des SMS ou des messages apparaissant sur la plate-forme peuvent être envoyés aux différents intervenants.

Il faut définir le modèle (squelette) de ces messages une fois que l'architecture du workflow est cohérente. Ces modèles comprennent des variables du type [nom] qui seront remplacées par la valeur adéquate dans le message envoyé à l'usager ou à l'agent traitant.

Les interactions

C'est la partie la plus sensible de la mise en place des workflows et elle comprend :

* La mise en place des différentes actions disponibles pour l'agent traitant
* La connexion avec des applications tierces par webservices
* Des changements concernant l'agent traitant ou l'usager demandeur.

Fiche d'élaboration d'une démarche

Le document bureautique téléchargeable ci-dessous peut vous servir pour construire votre démarche, ou télé-service, composée d'un formulaire et de son workflow de traitement. Tout particulièrement dans le cas du formulaire, avec un peu de pratique, il est aussi rapide d'élaborer directement celui-ci dans Publik plutôt que de passer par le tableau du document bureautique. Nous ne conseillons d’utiliser cette partie « Formulaire » qu’à des personnes n’ayant pas accès à la fabrique de formulaire.

Pour la partie workflow, la construction "sur papier" des statuts et actions associées peut être profitable. Quant à la rédaction des texte des courriels envoyés dans le cadre du workflow, c'est tout à fait pertinent puisqu'il s'agit là d'éléments de communication externe, bien souvent validés par la Direction de la Communication de la collectivité.

Fiche d'élaboration, sur papier, d'une démarche

* RGAA

# Conformité aux réglementations pour la protection des données (RGPD).

Conformité aux réglementations pour la protection des données (RGPD).

Les applications développées par Entr'ouvert sont conçues pour préserver la vie privée des utilisateurs (« privacy by design »), et respectent les obligations du RGPD.

Le RGPD ne fait pas intervenir de nouveautés conceptuelles majeures contrairement à ce qui se dit souvent. Les grands principes visant à préserver la vie privée des citoyens sont en place depuis 40 ans (loi de 1978). Même le renforcement du consentement, souvent mis en avant pour pointer les nouveautés du RGPD, est largement présent dans les législations précédentes auxquelles étaient soumises les démarches en ligne.Ce qui change véritablement ce sont les modalités du contrôle (on passe d’un contrôle a priori à un contrôle a posteriori) et surtout l’importance des sanctions (revues très largement à la hausse). Le RGPD a également le mérite de clarifier la situation et de déclencher une prise de conscience sur le sujet du respect de la vie privée.

Privacy by designPublik est développé pour préserver la vie privée des utilisateurs (« privacy by design »), et respecter les obligations du RGPD. Nous avons souvent devancé les exigences de la CNIL dans ce domaine, implémentant par exemple la fédération d’identité (rendue nécessaire par la CNIL en 2013 pour gérer convenablement les 10 familles de téléservices) dès 2008.

Nous avons fait le nécessaire pour pouvoir affirmer sans équivoque que nous sommes en conformité avec le RGPD. Quelques éléments saillants qu’il faut avoir à l’esprit :

* dans le cadre du principe d'autodétermination informationnelle introduit par le RGPD, notre fournisseur et gestionnaire d'identités Authentic2 met à disposition des utilisateurs une interface de gestion complète de leurs données personnelles, lesquels sont en capacité de consulter, modifier ou supprimer leurs informations d'identité ; le droit à l’oubli et le droit de rectification sont respectés,
* le droit de portabilité est également respecté, grâce à une fonctionnalité directe d'export des données de compte et des demandes, en différents formats standards.
* Respect du droit d'accès aux données et informations relatives aux traitements associés : des codes de suivi envoyés à chaque utilisateur leur permettent de vérifier en temps-réel l'état de leurs demandes et de connaître la nature des traitements effectués.
* nous excluons de nos applications toute décision automatisée et toute forme de profilage quelles qu'elles soient,
* notre module de statistiques pour la business intelligence ne fournit que des métriques anonymisées et ne permet en aucun cas de remonter aux données sources utilisées,
* notre environnement Publik et notre fournisseur d’identité Authentic sont conçus et paramétrés par défaut pour un dialogue avec les usagers (via l'interface Web et par courriel notamment) afin que ceux-ci comprennent ce qui advient de leurs informations d'identités ; et plus généralement nous faisons notre possible pour respecter les principes de Privacy-by-Design/Privacy-by-Default de la législation européenne,
* tous nos déploiements sont strictement en HTTPS,
* en tant que sous-traitant fournisseur de SaaS (Software as a Service) aux collectivités territoriales françaises, nous nous efforçons de veiller à la sécurité de nos serveurs, lesquels se situent physiquement en Union Européenne comme l'impose le RGPD (ils sont en France),
* nos applications fournissent des logs pertinents sur la façon dont sont traitées les données personnelles des usagers, et elles implémentent un système de rôles conditionnant l'accès aux données utilisateurs (Role-Based Access Control), permettant de n'accorder à un agent que les accès dont il a besoin.

Nous avons nommé un DPO (Data Protection Officer) chargé de la conformité au RGPD chez Entr'ouvert.Nous avons également révisé le modèle de nos clauses contractuelles avec les collectivités, pour expliciter davantage le principe de coresponsabilité introduit par le RGPD. Les collectivités utilisatrices de Publik peuvent demander à consulter notre Étude d’Impacts sur la Vie Privée (EIVP) réalisée pour les activités d’édition logicielle et d’hébergement SaaS de la solution Publik par Entr’ouvert.

Pour davantage de détails techniques concernant la sécurité et le respect du RGPD, vous pouvez consulter lapage dédiée dans le guide de l'administrateur système.

* RGAA

# Utiliser les balises de gabarit

Utiliser les balises de gabarit

make_public_url

Génère une URL publique permettant d’accéder à un contenu spécifique, en ajoutant une signature qui autorise l’accès. La signature est liée à la session de l'utilisateur qui n'a pas besoin d'être connecté.

Exemple d'utilisation :

{% make_public_url url=form_var_document_url %}

En pratique :

Cette balise est utile pour partager des fichiers ou des ressources d’une fiche depuis une page combo, sans nécessiter une authentification.

temporary_access_url

Génère une adresse d’accès temporaire (URL), sans authentification, à une demande.

Paramètre :

* days,hours,minutes,seconds(facultatif): Permettent de définir la durée de validité du lien. La durée par défaut est de 30 minutes.
* bypass_checks(facultatif): Permet de s’affranchir des validations supplémentaires qui sont parfois demandées pour les codes de suivi.

{% temporary_access_url minutes=15 bypass_checks=True %}--> génère une URL temporaire valide pendant 15 minutes, permettant d'accéder à une demande sans effectuer les validations habituellement requises lors d'un accès avec un code de suivi.

Cette balise est particulièrement utile pour créer un lien à durée limitée qui peut remplacer un code de suivi pour des accès de courte durée.

token_alphanum

Génère un code aléatoire qui combine des chiffres et des lettres. Par défaut, la balise retourne un code à 4 chiffres et/ou lettres.

Pour éviter toute confusion, les chiffres 0 et 1, ainsi que les lettres O et I, ne sont pas utilisés lors de la génération de ce code.

* length(facultatif): Permet de spécifier la longueur du code généré.

{% token_alphanum length=7 %}--> génère un code à 7 chiffres et/ou lettres, par exemple : E2RA3XT

Cette balise est utile pour générer des codes aléatoires dans des contextes nécessitant une identification temporaire (ex. : OTP, codes de validation).

Il est ensuite possible d’utiliser le filtre|token_checkdans une condition pour vérifier si le token saisi par l’usager correspond à celui qui a été envoyé, sans tenir compte des espaces en début et en fin de chaîne.Exemple :form_workflow_form_DT_TOKEN_SAISI|token_check:form_var_DT_TOKEN_RECU

token_decimal

Génère un code aléatoire composé de chiffres. Par défaut, la balise retourne un code à 6 chiffres.

{% token_decimal length=10 %}--> génère un code à 10 chiffres, par exemple : 1234567890

zip

Crée un fichierZIP contenant un ou plusieurs fichiers. Elle est utile pour regrouper des documents à télécharger ou à transmettre dans un seul fichier compressé.

Syntaxe :

{% zip nom_du_fichier_zip[chemin=fichier_contenu]* %}

* nom_du_fichier_zip : spécifie le nom du fichier ZIP à générer (ex. :"archive.zip"ou une variable contenant ce nom).
* fichier_contenu : définit un fichier ou une liste de fichiers à inclure dans le ZIP. La liste de fichiers peut provenir d'un bloc de champ, la syntaxe sera alors :form_var_BLOC_DE_CHAMP|getlist:"fichier".
* chemin(facultatif): indique où et comment nommer les fichiers dans le ZIP :lorsqu'un nom de fichier est spécifié (ex. :"dossier/rapport.pdf"), il sera utilisé.pour une liste de fichiers, un suffixe numéroté est ajouté (ex. :rapport-1.pdf,rapport-2.pdf, etc.).lorqu'aucun nom de fichier n'est précisé ou que le chemin se termine par/, les noms d'origine des fichiers sont conservés.

Exemples d'utilisation :

{% zip "archive.zip" demande.pdf=form_var_export_demande piece-jointes/piece.pdf=form_var_bloc|getlist:"fichier"%}--> créé un fichier zip nommé "archive.zip" contenant un fichier "demande.pdf" à sa racine et des fichiers "piece-1.pdf" (puis -2, -3, etc...) dans un sous-répertoire piece-jointes

{% zip form_var_archive_name =form_var_export_demande|rename_file:form_var_export_demande_name %}--> si form_var_export_demande_name est pré-rempli avec le gabarit "DEMANDE-{{ form_user_display_name|slugify|upper }}.pdf" et form_var_archive_name avec "DEMANDE-{{ form_number }}.pdf", donnera un fichier .zip nommé "DEMANDE-7-1234.zip" contenant le fichier DEMANDE-JOHN-DOE.pdf

Et aussi :

L'extension des fichiers est adaptée à leur contenu réel (ex. : un fichier nomméimage.pdfcontenant une image JPEG sera renomméimage.jpgdans le ZIP).Utilisez le filtrerename_filepour personnaliser dynamiquement les noms des fichiers.

* Studio
* Les tutos

# Utiliser les filtres de requêtes

Utiliser les filtres de requêtes

Les filtres de requêtes se distinguent desautres filtrespar leur capacité à interroger et remonter des données comme on pourrait le faire avec un langage de base de donnée de type SQL.

Chercher dans les demandes ou les fiches

Ils permettent de faire des requêtes sur les demandes et les fiches, en utilisant respectivement :

* forms|objects:"slug-du-formulaire" pour les demandes
* cards|objects:"slug-du-modele-de-fiche" pour les fiches.

forms|objects:"slug-du-formulaire"|filter_by:"nom"|filter_value:"entrouvert"

permet de chercher, dans un formulaire dont leslugest « slug-du-formulaire », si lavaleur« entrouvert » est déjà présente dans un champ dont l'identifiantest « nom ».

Ou, pour tester une valeur d'un champ :

forms|objects:"slug-du-formulaire"|filter_by:"nom"|filter_value:form_var_nom
forms|objects:"slug-du-formulaire"|filter_by:"nom"|filter_value:form_var_autre_chose

À noter : pour tester la valeur d'un champ liste, il faut passer lavaleuret non le libellé, soit :

forms|objects:"slug-du-formulaire"|filter_by:"liste"|filter_value:form_var_liste_raw
forms|objects:"slug-du-formulaire"|filter_by:"liste"|filter_value:form_var_autre_liste_raw
forms|objects:"slug-du-formulaire"|filter_by:"liste"|filter_value:2

Pour désigner le formulaire en cours, on peut remplacer

forms|objects:"slug-du-formulaire"simplement parform_objects

Récupérer la valeur d'un champ

Appliqués à une fiche cette fois, ces filtres peuvent permettre de faire remonter la valeur d'un champ particulier pour une fiche donnée :

cards|objects:"slug-modele-fiche"|filter_by:"nom"|filter_value:"entrouvert"|first|get:"form_var_telephone"

permet de récupérer le contenu du champ dont l'identifiantest « telephone », dans un modèle de fiche dont leslugest « slug-modele-fiche », pour la première fiche contenant lavaleur« entrouvert » dans le champ dont l'identifiantest « nom ».

Pour récupérer l'identifiant interne, on utilise "form_internal_id" :

cards|objects:"slug-modele-fiche"|filter_by:"nom"|filter_value:"entrouvert"|first|get:"form_internal_id"

Récupérer une liste

|getlist va permettre de récupérer un objet liste plutôt qu'une seule valeur. Pour un modèle fiche « enfant » on pourra récupérer la liste des noms en faisant :

cards|objects:"enfant"|getlist:"nom"

Il est possible d'afficher la liste des nom séparés par des virgules en faisant

cards|objects:"enfant"|getlist:"nom"|join:","

Filtres de comparaison

Les filtres vus jusque ici ne permettent que de vérifier la correspondance stricte à une valeur : « donne-moi toutes les fiches dans lesquelles le nom est "Dupont" ». Les filtres de comparaison permettent de demander des choses plus complexes comme : « donne moi toutes les fiches dont le prix est supérieur à 100 ». Ces filtres sont  :

* |equal|filter_value:"xxx": renvoie les demandes/fiches pour lesquelles le champ testé correspond exactement à la valeurxxx
* |i_equal|filter_value:"xxx": renvoie les demandes/fiches pour lesquelles le champ testé correspond à la valeurxxx, en ignorant les éventuelles différences de casse.
* |not_equal|filter_value:"xxx": renvoie les demandes/fiches pour lesquelles le champ testé est différent de la valeurxxx
* |less_than|filter_value:"xxx": renvoie les demandes/fiches pour lesquelles le champ testé est inférieur à la valeurxxx
* |greater_than|filter_value:"xxx": renvoie les demandes/fiches pour lesquelles le champ testé est supérieur à la valeurxxx
* |less_than_or_equal|filter_value:"xxx": renvoie les demandes/fiches pour lesquelles le champ testé est inférieur ou égal à la valeurxxx
* |greater_than_or_equal|filter_value:"xxx": renvoie les demandes/fiches pour lesquelles le champ testé est supérieur ou égal à la valeurxxx
* |in|filter_value:"xxx|yyy": renvoie les demandes/fiches pour lesquelles le champ testé correspond à la valeurxxxou à la valeuryyy
* |not_in|filter_value:"xxx|yyy": renvoie les demandes/fiches pour lesquelles le champ testé ne correspond ni à la valeurxxxni à la valeuryyy
* |icontains|filter_value:"xxx": renvoie les demandes/fiches pour lesquelles la valeur du champ testé contient xxx, en ignorant les éventuelles différences de casse. À la différence de |i_equal, ce filtre retournera les demandes dont une sous-chaine correspond, ex : si "xxx" est "Rue", les champs "ruedes Cerisiers", "ruedes Lilas", "avenue deRueil-Malmaison", mais pas "avenue de Chatou".
* |absent: renvoie les demandes/fiches pour lesquelles le champ testé n'est pas rempli
* |existing: renvoie les demandes/fiches pour lesquelles le champ testé est rempli
* |between|filter_value:"1|5": renvoie les demandes/fiches pour lesquelles le champ testé est supérieur ou égal à 1 et inférieur à 5

Cette expression va renvoyer l'ensemble des demandes pour lesquelles le revenu est inférieur à 2000 :

{{forms|objects:"test"|filter_by:"revenu"|less_than|filter_value:"2000"}}

Filtres supplémentaires

* |countretourne le nombre de résultats de la requête
* |donepermet d'obtenir les demandes terminées uniquement. C'est à dire les demandes qui sont dans un statut final.
* |exclude_value:"..."permet d'exclure des résultats la valeur spécifiée en paramètre.
* |exclude_selfpermet d'exclure la demande de départ des résultats (fonctionne uniquement avecform_objects).
* |filter_by_distance:xxxpermet de filtrer les demandes/fiches selon leur distance à un point (de la demande/fiche à l'origine de la requête siform_objectsest utilisé, d’un point arbitraire si renseigné par la filtre|set_geo_center). La distance doit être exprimée en mètres. C’est équivalent à|filter_by:"distance"|filter_value:xxx.
* |filter_by_internal_id:xxxpermet de filtrer sur l’identifiant interne d'une demande/fiche (à la différence de |filter_by_number). Pour reprendre l'exemple de la ligne précédente, l'identifiant interne sera 35. C'est équivalent à|filter_by:"internal_id"|filter_value:xxx.
* |filter_by_status:"Libellé du statut"permet de filtrer les résultats sur le statut donné; c’est équivalent à|filter_by:"status"|filter_value:"Libellé du statut".
* |filter_by_number:xxxpermet de filtrer les résultats 
sur le numéro complet d'une demande/fiche. Le numéro complet se présente
 sous une forme 2-35; c’est équivalent à|filter_by:"number"|filter_value:xxx.
* |filter_by_user:form_userpermet de limiter les résultats aux fiches et demandes liées à un usager précis; c’est équivalent à|filter_by:"user"|filter_value:form_user. En complément, le filtre accepte également l’adresse électronique de l’usager ainsi que l’identifiant unique qui lui est associé (uuid).
* |is_emptypermet de vérifier que le contenu d'une requête est vide.
* |order_by:"..."permet de trier les résultats sur le champ dont l'identifiant est passé en paramètre. Par exemple xxx|order_by:"nom" pour trier sur le champ dont l'identifiant est "nom".
* |pendingpermet d'inclure uniquement les demandes ouvertes dans une requête sur des demandes.
* |same_userpermet de limiter les résultats aux demandes posées par le même utilisateur que la demande de départ.
* |set_geo_center:xxxpermet de définir le centre à utiliser pour le filtre géographique appliqué à une requête (|filter_by_distance); le paramètre attendu est une demande/fiche dont le géocodage sera donc utilisé comme référence.
* |with_custom_view:"..."permet d'appliquer les critères de la vue en question.

Exemple d'utilisation du filtre|count:
{{form_objects|filter_by:"nom"|filter_value:"entrouvert"|count}} --> retourne un entier

Une condition s'écrirait ainsi :

{% if form_objects|filter_by:"nom"|filter_value:"entrouvert"|count == 0 %}Aucune demande{% endif %}

* Studio
* Les tutos

# Paramétrage avancé

Les outils

Vous êtes capables de réciter dans l'ordre et sans vous tromper les différentstypes de champsou les différentesactions de wokflow. Vous êtes frustrés par le côté rudimentaire des explications fournies pour créer unformulaire conditionnel... Alors cette section est faite pour vous.

Vous découvrirez la diversité desvariables utilisables, l'écriture deconditions complexes, la mécanique desgabarits Djangoou l'utilisation defiltres standardset defiltres de requête.

Et quand vous maîtriserez tout cela, il sera temps de vous esquinter les yeux sur lespages d'inspectionpour chercher à comprendre ce qui ne fonctionne pas.

C'est compliqué de faire simple

Parce que les utilisateurs de Publik sont travailleurs et créatifs, on a parfois des workflows à 120 étapes ou des formulaires à 800 champs... On peut louer l'inventivité et la bravoure mais elles interrogent quand à l'objectif premier d'une GRU : la simplification. Accessoirement, il est important de comprendre que ces complexités tendent à obérer les performances, raison pour laquelle nous avons décider de les encadrer.

Nous avons mis en place des limitations pour éviter à l'avenir les constructions trop abracadabrantesques. Voici les nombres limites utilisables pour différents éléments :

 | Message d'alerte | Blocage
-----------------------------
Champs dans les formulaires | 200 | 400
Champs dans les modèles de fiche | 200 | 400
Champs dans les blocs de champs | 30 | 60
Champs dans une page de formulaire | à venir | à venir
Conditions dans une page | à venir | à venir
Appels webservices dans une page | à venir | à venir
Statuts de workflow | à venir | à venir
Champs dans les formulaires de workflow | 40 | 80
Variables de workflow | 40 | 80
Données de traitement | 40 | 80

* Studio
* Les tutos

# Modifier le contenu des portails

Le portail usager et le portail agent peuvent tous deux être adaptés par l'ajout de pages supplémentaires et l'agencement de « cellules » au sein de ces pages.

Pour en savoir plus sur la mise en place d'un portail Agents, consultez

[cette page](https://doc-publik.entrouvert.com/admin-fonctionnel/modifier-le-contenu-des-portails/mettre-en-place-portail-agents/)

.

Édition de la structure du portail

Vous pouvez ajouter de nouvelles pages au portail en cliquant sur « Nouvelle » en haut à droite : une fois la page ajoutée, il est possible d'en choisir l'ordre (en la faisant glisser vers le haut ou vers le bas à l'aide de la « poignée » sur la gauche de l'élément page) et d'en modifier la hiérarchie (inclusion dans une autre page en la faisant glisser vers la droite). Il est également possible de dupliquer une page ou de créer une sous-page : dans ce cas la page s'ajoute à la suite de la page dupliquée ou parent.

La page d'accueil du portail est défini par son identifiant (slug) : « index »

Paramètres d'un portail

Les différents paramètres du portail sont exposés sur la page d'accueil de l'édition, dans la barre latérale droite.

Ressources

Les ressources sont un endroit où l'on va stocker des fichiers et des images utilisables dans combo mais aussi dans les autres briques de Publik (les formulaires par exemple).

Après avoir transféré (uploadé) des fichiers, vous pourrez gérer ceux-ci depuis cette interface : remplacement ou suppression d'un fichier, recherche d'un fichier en particulier.

Exporter le site

Cela permet d'obtenir un export de l'ensemble des pages.

Sur l'écran « Historique » d'une page de portail, des liens permettent d’exporter une version donnée.

Importer un site

Cela permet d'importer un ensemble de pages ou une page unique, selon le fichier d'import. C'est le slug de la page figurant dans le fichier import qui sert à déterminer si une page existante correspond. Les pages correspondantes seront mises à jour lors de l'import, les autres seront créées.

Paiement en ligne

Vous y trouverez un onglet « Transactions » qui est une liste de tous les paiements effectués (classement chronologique) comportant les informations suivantes : identifiant de paiement interne à Publik, identifiant de transaction (l'identifiant bancaire, si retourné par le teminal de paiement), date, usager, montant, éléments inclus avec la facture (peut être le numéro de celle-ci).

L'onglet « Régies » qui permet de paramétrer celles-ci. Pour plus d'informations sur le paramétrage du paiement en ligne, se référer au tutoriel «Paiement».

Cartographie

Ce menu permet de créer des « couches cartographiques » qui vous seront ensuite proposées dans les cellules de type « Carte » pour y être affichée, ou pas (réglage possible au niveau de chaque cellule). Une couche cartographique est défini par : un libellé, une URL GeoJSON (cette URL peut être servie depuis une source externe de type OpenData ou interne, tels que démarches et statistiques - cf. infra) et des éléments de mise en forme (choix de l’icône et couleur de celle-ci, couleur de fond du marqueur ou de la surface).

Pour renseigner convenablement une couche cartographique concernant une démarche particulière, on utilisera les URL suivantes :

Pour l'ensemble des demandes, toutes démarches confondues :

{{eservices_url}}api/forms/geojson

Pour une démarche particulière :

{{eservices_url}}api/forms/url-de-la-demarche/geojson?filter=all

Pour un indicateur statistique préalablement construit :

{{statistiques_url}}visualization/numero-de-l-indicateur/geojson

Il est possible d'afficher les points de la carte aux utilisateurs non connectés en décochant « Inclure l'identification de l'utilisateur dans la requête » et en ajoutant à l'URL l'email d'un utilisateur ayant les accès nécessaires, sous la forme &email=utilisateur@entrouvert.com.

Il est également possible de définir des couches de tuiles supplémentaires, pour par exemple superposer une information « qualité de l’air » à une carte.

Le Geojson d'un couche cartographique va permettre d'afficher des points, des lignes ou des surfaces. Pour avoir plusieurs couleurs, il faut cliquer sur «Variable» et indiquer le nom de la propriété dans le GeoJSON permettant de récupérer la couleur souhaitée. Dans l'exemple ci-dessous il s'agit de la propriété "couleur" :

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
         "name": "Foo",
         "couleur": "#0a0a0a" 
      }
    },
    {
         "name": "Bar",
         "couleur": "#aa0000" 
      }
    },

Édition d'une page

Un clic sur une page permet de l'éditer. Les modifications sont automatiquement enregistrées et l'historique des différentes versions est accessible grâce au bouton « Historique » présent en haut de chaque page.

L'écran d'édition d'une page permet de définir certains paramètres généraux de la page et permet également de modifier le contenu des différentes zones (barre latérale, colonne 1 ou 2, pied de page)  en y ajoutant une ou plusieurs cellules.

Lors du travail initial de création du portail citoyen, une feuille de style est généralement créée pour reproduire l'allure du site web de la collectivité et le header construit sur-mesure, celui-ci contient en général :

* une icône avec un lien ramenant vers l'accueil du portail citoyen ou l'accueil du site web,
* le titre du portail,
* le cartouche de connexion.

Paramètres d'une page

Titre:le titre de la page.

Slug :permet d'identifier précisément une page et de choisir la terminaison de l'URL de celle-ci.

Modèle de page :choix de la structuration de la page parmi 4 modèles possibles (1 ou 2 colonnes combinées avec barre latérale ou pas) .

Visibilité :une page peut être « Publique » i.e. visible par tous les internautes ou visible seulement des usagers connectés (en fonction de leur rôle).

Exclure de la navigation: si une page est exclue de la navigation, elle n'apparaîtra pas dans les menus de navigation du portail Publik mais reste accessible via son URL (donc indexable par les moteurs de recherche si n'est pas restreinte à des utilisateurs connectés).

URL de redirection :pour permettre de re-router l'internaute vers une autre page. La re-direction va également permettre d'afficher au sein du portail une page existant dans une autre brique (par exemple le module d'authentification Authentic) :

* re-direction vers {{authentic_url}}accounts pour afficher les données et la gestion du compte (qui est une page construite intégralement dans Authentic, non paramétrable).

Dans ce cas, il ne faut pas insérer de cellule dans le contenu afin que la page extérieure puisse correctement s'afficher.

Ces pages construites depuis d'autres modules vont utiliser le template (modèle de page) de la page racine du portail (page d'accueil). Si vous souhaitez utiliser un template spécifique, il vous faut créer une page ayant l'URL de cette page cible, le template défini pour celle-ci sera alors utilisé plutôt que le template par défaut de la page racine. Il faut par ailleurs penser à exclure ces pages « techniques » de la navigation.

Pour intégrer au mieux un lien interne à Publik et éviter des liens en durs qui ne seraient plus valables après passage d'une installation de recette à une installation en production, il est possible d'utiliser une variable de substitution pour l'url, du type {{eservices_url}}, {{portal_url}}.

Image: Il est possible d'associer des images aux différentes pages. L'utilisation qui sera faite des images en question dépend de la façon dont elle sont gérées dans le thème mais l'on pourra, par exemple, choisir ici d'associer la page à une image de bandeau qui s'affichera en haut de la page.

Navigation: à cet endroit s'affichent des liens vers l'édition de la page parent, de la page précédente (peut être la page parent) et de la page suivante.

Rôle d'édition: système de permission par rôle pour l'édition d'une page (en incluant éventuellement les sous-pages) dans les portails. Cela permet de ne donner accès en modification qu'à certaines parties du portail.

Créer un modèle de page

Il est possible de créer un modèle de page qui pourra ensuite s'appliquer aux nouvelles pages créées (le modèle ne pourra pas s'appliquer aux pages existantes).

Pour permettre cela, il faut créer une page "Modèles" avec pour slug "modeles". Cette page peut rester vide. Créez ensuite une sous-page, par exemple "Modèle Fiche base de connaissances". Choisissez un modèle de page existant, puis ajoutez des cellules dans les zones pré-définies (cellules de texte, menu...).

Ce modèle apparaît dans la liste des modèles de pages à la création d'une nouvelle page.

Dans les modèles de page desportails usagers uniquementdes sections de page optionnelles (Haut du contenu, Bas du contenu, Pied de page) permettent d'afficher des cellules supplémentaires au-dessus ou en-dessous du contenu principal. Cela peut par exemple être utile pour configurer un modèle de page pour les démarches avec des informations sur le respect de la vie privée apparaissant sous toutes les démarches et au-dessus du pied de page.

Paramètres avancés d'une page

Le menu burger en haut à droite de chaque page, permet d'accéder au paramétrage avancé.

Historique :

permet de voir les différentes versions enregistrées, une version est enregistrée à chaque modification

Exporter :

permet d'exporter au format JSON la page concernée

Modifier les variables de page :

permet de donner un nom (qui est aussi leur identifiant) et une valeur à des variables pour les réutiliser dans les cellules qui supportent Django (Cellules Fiche(s), Lien et comme filtres des cellules Graphes).

Lier à un modèle de fiche :

cf.

[page dédiée](https://doc-publik.entrouvert.com/admin-fonctionnel/developper-des-applications-simples-avec/parametrage-avance-des-fiches/#lier-un-modele-de-fiche-a-une-page)

.

Ajouter une sous-page :

crée une page fille de la page en cours.

Gestion des rôles d'édition :

permet de définir les rôles

autorisés à modifier la page et ses sous-pages.

Dupliquer :

duplique la page.

Enregistrer une sauvegarde :

permet de distinguer une sauvegarde particulière.

Supprimer :

supprime la page.

Mettre en place une page de bienvenue et/ou de première connexion

L'entrée « Paramètres du site » dans le menu burger permet de paramétrer une page de bienvenue où rediriger l’usager qui vient pour la première fois sur le site, usuellement pour l’inviter à se connecter, et une page de première connexion, pour l’usager qui se connecte une première fois.

Cela permet d'afficher à l'usager une page avec des informations qui ne lui sont demandées qu'une seule fois comme l'abonnement à des newsletters ou la liaison avec différents services.

Les URLs peuvent contenir des gabarits pour plus de souplesse.

* Studio
* Les tutos

# Utiliser les gabarits (templates)

Utiliser les gabarits (templates)

Les gabarits permettent de construire des modèles à l'aide d'instructions entourées des symboles {% .... %}.

Dans ces gabarits, des variables entre accolades {{ }} vont être remplacées par des valeurs, comme pour un publipostage. Exemple d'un courriel :

Bienvenue {{session_user_display_name}},

Toute l'équipe de {{site_name}} vous remercie de votre
inscription et vous souhaite une agréable visite.

Lors de l'envoi, les variables proposées entre accolades seront remplacées par des valeurs, pour donner un résultat du type :

BienvenueLætitia,

Toute l'équipe de Portail citoyen de Connecteville vous remercie de votre

Le même principe est à l'oeuvre partout où l'on utilise des gabarits (templates) : envoi de SMS, création de document, messages dans l'historique, alertes, notifications...

Lesvariables utilisablesdans ces gabarits sont très diverses.

Gabarit conditionnels

Il est également possible d'afficher du contenu de manière conditionnelle, en utilisant une de ces syntaxes :

* {% if variable %}...{% endif %}
* {% if variable %}...{% else %}...{% endif %}
* {% if variable %}...{% elif variable2 %}...{% endif %}

Tester la présence d'une variable

Pour vérifier qu'unevariable existe (qu'elle contient quelque chose), on procèdera comme suit :

Pour rappel, voici les renseignements que vous nous avez fournis :

{% if form_var_regime_alimentaire %}
 - Régime alimentaire : {{form_var_regime_alimentaire}}
{% else %}
 - Aucun régime alimentaire précisé.
{% endif %}

Tester la valeur d'une variable

Pour tester non pas la présence d'une valeur mais le contenu de celle-ci, la syntaxe est

{% if variable == valeur %}...{% endif %}, avec également la possibilité d'un{% else %}.

Pour toute information complémentaire, n'hésitez pas à nous contacter au numéro
{% if form_var_pays == "France" %}0800123456{% else %}+33112345678{% endif %}.

Choisir la première variable existante

Il peut souvent s'avérer utile d'afficher la première variable existante parmi une liste de variables. Cela se fera en utilisant cette syntaxe :

{% firstof form_var_nom_autre_professionnel form_var_professionnel_referent %}

Si form_var_nom_autre_professionnel existe, sa valeur sera affichée. Sinon c'est la valeur de  form_var_professionnel_referent qui sera affichée (et si aucune des deux variables n'existe rien ne sera affiché).

Pour plus d'informations la syntaxe utilisée est celle des gabarits Django, il en existe unedocumentation détailléeen ligne.

Précemment un autre langage de description des gabarits était utilisé (EZT), caractérisé par l'utilisation de crochets (ex:[form_var_email]), il est toujours disponible mais désormais déconseillé ; pour mémoire saréférence détaillée(en anglais) est toujours en ligne.

* Studio
* Les tutos

# Configuration de Matomo

Configuration de Matomo

Matomoest un outil de fourniture de statistiques de fréquentation.

Depuis la brique « Système » il est possible d'aller dans le menu burger sur « Mesure d'audience », puis de choisir la « configuration manuelle » pour indiquer une instance de Matomo. Les instances de Publik qui sont sur notre SaaS disposent en plus d'un bouton « Configuration automatique » qui leur permet d'être raccordées par un simple clic à l'instance de Matomo utilisée par Entr'ouvert. Vous pourrez ensuite accéder aux statistiques de fréquentation en cliquant sur « Ouvrir le tableau de bord de la mesure d'audience ».

Pour faire un lien vers le tableau de bord à partir du portail Agents, utilisez le gabarit {{matomo_logme_url}}

À noter que tant que le site n'a pas reçu de visite, Matomo voit sa base vide et pense (à tort) qu'il n'est pas encore bien configuré, et affiche une page d'erreur expliquant la configuration à mettre en place. Il ne faut rien faire d'autre que d'aller sur le site afin de déclencher le compteur de visites.

Exemple d'utilisation

Matomo permet par exemple de connaître le nombre de fois où un formulaire a été ouvert dans Publik sur une période donnée. Via le menu de gauche de matomo :

Comportement >> Titres des pages

Pour les tests,

* Penser à désactiver l'éventuel bloqueur de publicité installé sur votre navigateur avant d'accéder à des pages du portail utilisateur de publik.
* En dehors des visites en temps réel affichées sur le tableau de bord, les données ne sont mises à jours que toutes les 15 minutes.
* Penser à sélectionner la date du jour via le calendrier situé en dessous du bandeau, qui est sinon positionnée par défaut à la date d'hier.

Accès aux statistiques sur une instance multi-collectivités

La configuration automatique attribue un compte Matomo à chaque collectivité. Ce compte expose uniquement les statistiques de la collectivité.

Dans la suite nous allons créer un compte qui pourra accéder aux statistique de toutes les collectivités.

Note : cette manipulation n'est possible que par les adminstrateurs de l'instance Matomo.

Créer un nouveau compte Matomo

Cliquer sur «Administration» (Engrenage en haut à droite)Système > Utilisateur > Ajouter un nouvel utilisateur

* Username: clapotis-ville-et-agglo
* Password: xxxxxx
* Email: noreply+matomo-clapotis-ville-et-agglo@entrouvert.org
* First website permission: clapotis-agglo.fr

Puis cliquer sur Permissions et choisir «Vue» pour toutes les instances ciblées :

* clapotis-agglo.fr : Vue
* clapotis-ville.fr : Vue

Et répondre « Oui » à la question « Êtes-vous sûr(e) de vouloir changer le rôle de clopotis-ville-et-agglo de clapotis-agglo.fr à Vue ? »

Ajouter une variable hobo sur les instances de la ville et de l'agglo

Générer la somme de hashage MD5 du mot de passe (remplacer xxxxxx par le mot de passe du compté créé) :

$ echo -n xxxxxx | md5sum
5fd6dcb9ca2cb66a69a7a3fa94167450

Créer une variableall_matomo_logme_urlcontenant cette valeur :

https://matomo.entrouvert.org/index.php?module=Login&action=logme&login=clapotis-ville-et-agglo&password=5fd6dcb9ca2cb66a69a7a3fa94167450

À noter : l'URL utilise le MD5 du mot de passe, et non pas le jeton donné par l'IHM.

Ajouter un lien sur le portail agent

Ajouter une nouvelle cellule de type « lien » :

* Titre: Statistiques de fréquentation ville + agglo
* URL: {{all_matomo_logme_url}}

Permettre aux visiteurs de refuser d’être suivis

Vous pouvez ajouter un moyen pour vos visiteurs de « refuser » d'être suivis par le serveur Matomo hébergé (Opt-out). En pratique, il s'agit sur une page du portail Publik d'insérer dans une cellule texte :

<iframe
style="border: 0; height: 200px; width: 100%" 
src="https://matomo.entrouvert.org/index.php?module=CoreAdminHome&action=optOut&language=fr" 
></iframe>

* Studio
* Les tutos

# Sources de données

Plutôt que de définir manuellement les éléments d'un champ à saisir de typeliste,liste à choix multiple, ouTexte (ligne), l'administrateur fonctionnel peut sélectionner un référentiel distant, une source de données, composée des éléments susceptibles d'être choisis par un usager lors de la saisie d'un formulaire.

Lorsque la source de donnée est créée et que « Source de données » est coché pour un champ particulier, le nom de la source apparaît dans la liste déroulante dédiée.

Par exemple, pour construire une source de données« Liste des établissements scolaires publics de la collectivité » permettra de configurer un champ « Liste » intitulé « Établissement scolaire actuel de votre enfant » pour qu'il affiche l'ensemble des établissements scolaires.

Création manuelle d'une source de données

Source de donnée classique

Depuis l'écran d'accueil des sources de données, on peut en créer une nouvelle en cliquant sur « Nouvelle source de données ».

Il sera alors possible d'indiquer l'URL de la source à utiliser pour trois formats différents :

* JSON (le plus courant)
* JSONP (Obsolète)
* GEOJSON (pour construire des sources de données qui seront utilisées dans des champs de type liste avec le mode d'affichage « Carte » sélectionné).

Pour les sources de données volumineuses, afin de ne pas altérer les performances, on ajoutera un paramétrage spécifique dans l'onglet avancé :

* Paramètre de requête : mettreq
* Paramètre d’identifiant : mettreid

Lorsqu'on connait l'identifiant d'une source de donnée (visible dans le XML), on peut l'utiliser pour vérifier qu'elle n'est pas vide (sans avoir besoin de construire un webservice pour ça). La conditiondata_source.MA_SOURCEsera vraie si la source de donnée ayant pour identifiant « MA_SOURCE » n’est pas vide.

De manière plus générale, data_source.MA_SOURCE donne accès aux éléments de la source de données, il est ainsi possible d’itérer dessus, par exemple le gabarit suivant :

{% for item in data_source.MA_SOURCE %}{{ item.text }}{% if not forloop.last %}, {% endif %}{% endfor %}

pourrait être utilisé pour afficher toutes les valeurs de la source de données en question.

Source de données « Utilisateurs »

Depuis l'écran d'accueil des sources de données, on peut en créer une nouvelle en cliquant sur « Nouvelle source de données Utilisateurs ».

Il est alors possible de créer une source contenant l'ensemble des utilisateurs disposant d'un ou plusieurs rôle(s) particulier(s) ou dépourvus d'un rôle.

Une option permet d'i

nclure ou non dans la source, les utilisateurs désactivés.

Source de données créées automatiquement

Modèles de fiches

Le moyen le plus simple de mettre en place une source de donnée, est de créer un modèle de fiche en oubliant pas de remplir l'option « Gabarit du résumé » qui permet de générer automatiquement la source de donnée correspondant au modèle de fiche. Ce qui sera affiché dans le champ liste utilisant cette source de donnée est ce que vous aurez mis dans « Gabarit du résumé ».

Lorsque un champ liste form_var_LISTE utilise une fiche comme source de donnée, les autres champs de la fiche sont disponibles dans form_var_LISTE_CHAMP.

Lesvues personnaliséessont utilisables comme source de données si on les enregistre comme telles au moment de leur création. Elles vont permettre de poser des tris et des filtres sur le contenu que la source de données va afficher. Elles vont aussi permettre de définir un « résumé » (gabarit d’affichage) particulier qui se substituera au résumé par défaut du modèle de fiche. Cela permet de déplacer le focus de la source de donnée d'un champ vers un autre, comme on le faisait auparavant avec les « projections » pour les fichiers CSV.

Agendas

Outre les sources de données créés via les modèles de fiche, on va pouvoir disposer automatiquement d'une source de données lorsqu'un agenda est créé. Cette source de donnée sera disponible dans un champ liste uniquement lorsque « Horaires » aura été choisi comme mode d'affichage pour le champ en question.

* Studio
* Les tutos

# Stockage de données JSON (obsolète)

Stockage de données JSON (obsolète)

Attention: l'utilisation d'un « JSON Datastore » est déprécié dans Publik, au profit de l'utilisation desfiches. Aussi, si vous devez créer maintenant une source de données, prévoyez directement une gestion de votre source de données à base de fiches.

Une gestion de la relation usagers n'est pas focalisée sur le stockage durable de données, CNIL et RGPD obligent.

Cependant, il peut arriver, pour les assocations par exemple, que l'on ait besoin de stocker des informations ailleurs que dans la demande. Nous utilisons pour cela ce que nous appelons un « JSON Datastore ». Nous expliquons ici comment enregistrer et réutiliser des données au format JSON, dans ce store.

Création du store

La première chose à faire, pour utiliser cet espace de stockage, et d'aller dans la brique « Services web » (Passerelle) pour créer un nouveau connecteur en cliquant sur « Ajouter un connecteur ».

Dans « Sources des données », vous choisirez « Stockage de données JSON ». En plus du titre et de la description,  vous devrez indiquer une valeur qui sera utilisée comme identifiant unique de chaque enregistrement dans la base. Il faut choisir une des variables qui sera systématiquement envoyée lors de la création d'un enregistrement et lui appliquer lefiltre|safe ou |slugify pour être sûr que son nom sera informatiquement correct.

Par exemple :{{nom|safe}}

Enregistrement d'informations dans le store

Pour stocker des informations dans le store vous allez utiliser l'action de workflowwebserviceet la configurer comme suit :

* URL :{{passerelle_url}}jsondatastore/IDENTIFIANT-DU-CONNECTEUR/data/create
* Méthode : POST
* Données à envoyer dans le corps de la requête : sur chaque ligne, un couple attribut / valeur (par exemplenom_association / {{form_var_nom_association}}.

Attention, lorsque vous souhaitezdéposer un fichiersur le store, il faut procéder un peu différemment des autres champs. Si votre champ a pour identifiant « fichier » nous n'allez pas juste indiquer {{ form_var_fichier }} comme valeur mais{{ form_var_fichier_url }}: c'est l'URL de ce fichier que vous devez stocker dans le store et non le fichier lui-même (ce qui est impossible).

Pour lier l'enregistrement à l'utilisateur (connecté) qui a fait la demande, vous pouvez transmettre dans « Données à envoyer en paramètres de l'URL » un paramètre name_id et lui donner pour valeur {{form_user_name_identifier_0}}

Récupération d'informations depuis le store

Dans un formulaire

Pour afficher dans un champ liste, tous les enregistrements correspondant à un utilisateur (lorsque l'on a fait le choix d'associer l'identifiant des utilisateurs aux enregistrement), on pourra configurer la source de données de ce champ liste en indiquant pour « URL du JSON » :

{{passerelle_url}}jsondatastore/IDENTIFIANT-DU-STORE/data/?name_id={% firstof session_user_name_identifier_0 "nc" %}

Après sélection par le demandeur d'un enregistrement dans la liste et après qu'il ait changé de page, tous les attributs de l'enregistrement peuvent être récupérés en utilisant :

form_var_IDENTIFIANT-DE-LA-LISTE_content_NOM-DE-L-ATTRIBUT

Si par exemple mon champ liste a pour identifiant association et que les enregistrements dans le store ont un attribut creation, je peux récupérer ce dernier dans la variable.

form_var_association_content_creation

Via le workflow

On pourra configurer une action de webservice pour récupérer les enregistrements en fonction de leur identifiant

* URL :{{passerelle_url}}jsondatastore/IDENTIFIANT-DU-CONNECTEUR/data/IDENTIFIANT-ENREGISTREMENT/
* Méthode : GET

Utiliser un attribut

Dans le formulaire ou le workflow, on peut récupérer un enregistrement en interrogeant le store concernant la valeur d'un attribut particulier. Pour un store dont l'identifiant est « test » je peux récupérer les enregistrements dont la valeur pour l'attribut nom est « Strummer », en utilisant  l'URL :

{{ passerelle_url }}/jsondatastore/test/data/by/nom/?value=Strummer

Modifier les informations dans le store

Avec l'action webservice on aura le choix entre remplacer, mettre à jour ou supprimer les informations existantes.

Remplacer (enregistrement original effacé)

Mettre à jour (enregistrement original modifié)

* Méthode : PATCH

Supprimer

* URL :{{passerelle_url}}jsondatastore/IDENTIFIANT-DU-CONNECTEUR/data/IDENTIFIANT-ENREGISTREMENT/delete

Détails techniques

Si vous ne comprenez pas les informations contenues dans cette partie, c'est que vous n'en avez pas besoin.

Ajout d'informations¶

Un POST d'un objet JSON sur l'adresse…/data/create/du connecteur stocke l'objet et fournit en retour l'identifiant qui lui a été attribué, exemple :

$ curl -X POST \
       -d '{"nom": "Foo Bar 2000", "numero": "123456789"}' \
       https:/passerelle.example.net/jsondatastore/associations/data/create
{"text": "Foo Bar 2000 (123456789)",
 "id": "a53cdd0b99ed43a4bf7ddc102f919948",
 "err": 0}

Dans le paramétrage du connecteur, il est possible de paramétrer le modèle à appliquer pour la valeur de la clé "text", dans cet exemple on aura ainsi mis{{nom}} ({{numero}}).

Récupération de données¶

Un appel à l'adresse…/data/<identifiant>/retourne l'objet enregistré :

$ curl https:/passerelle.example.net/jsondatastore/associations/data/a53cdd0b99ed43a4bf7ddc102f919948/
{
 "content": {
   "nom": "Foo Bar 2000",
   "numero": "123456789" 
 },
 "text": "Foo Bar 2000 (123456789)",
 "err": 0
}

Récupération de l'ensemble des données¶

L'adresse…/data/seule permet de récupérer toutes les données :

$ curl https:/passerelle.example.net/jsondatastore/associations/data/
{
 "data": [
  {
   "content": {
     "nom": "Foo Bar 2000",
     "numero": "123456789" 
   },
   "text": "Foo Bar 2000 (123456789)",
   "id": "a53cdd0b99ed43a4bf7ddc102f919948" 
  },
  {
     "nom": "Bzze",
     "numero": "0234" 
   },
   "text": "Bzze (0234)",
   "id": "1ad86d329ec54ea6b37c9b22473e1395" 
  }
 ],
 "err": 0
}

Modification de données¶

Un POST à la même adresse,…/data/<identifiant>/, permet d'actualiser les données :

       -d '{"nom": "Foo Bar 2001", "numero": "123456789"}' \
       https:/passerelle.example.net/jsondatastore/associations/data/a53cdd0b99ed43a4bf7ddc102f919948/
{
   "nom": "Foo Bar 2001",
 },
 "text": "Foo Bar 2001 (123456789)",
 "err": 0
}

Suppression de données¶

Un POST à l'adresse…/data/<identifiant>/deletepermet de supprimer un objet :

       https:/passerelle.example.net/jsondatastore/associations/data/a53cdd0b99ed43a4bf7ddc102f919948/delete
{"err": 0}

Possibilité de lier les données à un compte¶

Les différents appels acceptent un paramètrename_idqui permet d'associer aux requêtes l'identifiant du « propriétaire » de l'objet JSON.

# enregistrement
       https:/passerelle.example.net/jsondatastore/associations/data/create?name_id=AZERTY
 "err": 0}

# liste
$ curl https:/passerelle.example.net/jsondatastore/associations/data/?name_id=AZERTY
{
 "data": [
  {
   },
  }
 ],
 "err": 0
}

# liste pour un autre identifiant
$ curl https:/passerelle.example.net/jsondatastore/associations/data/?name_id=QSDFGH
{
 "data": [],
 "err": 0
}

# récupération
$ curl https:/passerelle.example.net/jsondatastore/associations/data/a53cdd0b99ed43a4bf7ddc102f919948/?name_id=AZERTY
{
 },
 "err": 0
}

# récupération avec un autre identifiant
$ curl https:/passerelle.example.net/jsondatastore/associations/data/a53cdd0b99ed43a4bf7ddc102f919948/?name_id=QSDFGH
{
 "err_class": "passerelle.apps.jsondatastore.models.DoesNotExist",
 "err_desc": "JsonData matching query does not exist.",
 "data": null,
 "err": 1
}

* Studio
* Les tutos

# Importer et exporter les démarches

Importer et exporter les démarches

Exporter une démarche

Les formulaires et les workflows sont des fichiers XML, on peut les récupérer (exporter) depuis la plate-forme. L'export se faitdepuis la page d'accueil du formulaire/workflow, grâce à un lien « Export » dans la colonne de droite.

Les formulaires et workflows sont des fichiers xml dont l'extension est .wcs

Importer une nouvelle démarche

Une fois récupéré (par exemple sur une plate-forme de test), le fichier .wcs peut être importé sur une autre plate-forme (par exemple une plate-forme de production).

L'import se faitdepuis la liste des formulaires/workflows, grâce à un lien « Import » dans la colonne de droite.

Quand on utilise une plate-forme de test et une plate-forme de production, il faut réellement prendre garde à ne pas faire des modifications indifféremment des deux côtés car on se retrouve rapidement perdu. La discipline à favoriser consiste, même pour les modifications mineures, à les faire d'abord sur la plate-forme de test avant d'exporter/importer le formulaire/workflow depuis la plate-forme de test vers la plate-forme de production.

Bonnes pratiques

Afin de faire les choses dans le bon ordre, il convient de respecter quelques règles quand on importe une démarche :

* Si on souhaite pouvoir utiliser les rôles qui sont présents dans le workflow ou le formulaire, il faut, avant l'import de ces derniers, s'assurer que les rôles en question sont présents sur la plate-forme de destination, les recréer sinon.
* Quand on souhaite importer une démarche complète (formulaire + workflow), il est préférable de commencer par le workflow. Si on commence par le formulaire, ce dernier ne sera pas associé au bon workflow lors de son import, il faudra refaire l'association manuellement après import du workflow.
* Par défaut, le formulaire est désactivé lors de son import, il faut penser à l'activer
* Si des « sources de données » sont mentionnées dans le formulaire / workflow et ne sont pas présentes sur la plate-forme de destination, l'import échouera. Il faut alors, au choix, supprimer ces sources de données en éditant le fichier .wcs, ou recréer les sources de données sur la plate-forme de destination.

Remplacer une démarche existante

Souvent, on souhaite utiliser l'import pour remplacer une démarche existante. Or ça ne va pas fonctionner. Si on se contente d'importer un nouveau formulaire, identique à celui existant sur une plate-forme,il sera créé à côté du formulaire existant mais ne viendra pas prendre sa place.

Pour remplacer le formulaire existant, il faut utiliser (dans la colonne de droite depuis la page d'accueil du formulaire en backoffice) le lien «Écraser avec un nouvel import». Le nouveau formulaire viendra bien alors prendre la place de l'ancien, et sera associé aux données déjà existantes.

Attention, si vous avez supprimé des champs dans le nouveau formulaire avec lequel vous écrasez l'ancien, le contenu de ces champs n'apparaîtra plus dans le listing des demandes.

Catalogue des démarches

Pour mutualiser les démarches entre collectivités,le cataloguepermet de tester des formulaires et des workflows mais aussi de récupérer une URL permettant de les importer sur sa propre plate-forme.

Il est possible, très simplement, de copier l'URL d'un formulaire/workflow sur le catalogue - en cliquant sur « Télécharger »  pour les formulaires - et de la coller dans la zone prévue à cet effet quand on a cliqué sur « Import » dans l'outil de formulaires/workflows. L'import est immédiatement effectif et vous pouvez ensuite personnaliser le formulaire/workflow importé.

De la même façon, vous pouvezalimenter le cataloguepour y partager les formulaires/workflows que vous avez réalisés.

* Studio
* Les tutos

# Gestion d’identités

Gestion d’identités

La brique « Gestion d’identités » permet de déclarer et gérer des utilisateurs et des rôles sur son instance. En fonction des droits accordés, il est également possible de déclarer des fournisseurs de services OIDC et paramétrer des moyens d'authentification.

La brique de gestion d’identités est accessible depuisle menu principalduportail agentauxagents ayant le rôle interne« Administrateur des utilisateurs » et/ou « Administrateur des rôles » et/ou « Administrateur des moyens d’authentification » et/ou « Administrateur des services » (ceux-ci étant classiquement attribués à l'administrateur fonctionnel).

La brique « Gestion d’identités » affiche, notamment, des entrées pour :

* Gérer les utilisateurs
* Gérer les rôles
* Gérer les collectivités
* Déclarer des services OIDC

* Studio
* Les tutos

# Fabrique de workflows

Le workflow d'une démarche formalise le circuit de traitement que les demandes d'usagers relatives à cette démarche sont vouées à emprunter.

Il indique les étapes (statuts) de traitement qu'elles doivent atteindre pour assurer leur progression, ainsi que les opérations qui doivent être réalisées à chacune d'elles, pour aboutir à la clôture des demandes.

Le workflow assure ainsi la gestion électronique d'un processus métier. Leworkflow par défautpropose un cricuit de traitement basique pouvant servir de base à des processus plus élaborés.

La page d'accueil permet decréer un nouveau workflow ex nihilo ou d'en importer un.

On peut ajouter dans chaquestatut de workflowdesactionspermettant de faire progresser le traitement de la demande.

* Studio
* Les tutos

# Utiliser les variables

Utiliser les variables

Si j'attribue l'identifiant «telephone» à un champ de formulaire, je pourrai récupérer la valeur de ce champ dans la variable «form_var_telephone». Les noms de variables sont soumis à des règles, ils peuvent contenir des chiffres ou des lettres, mais pas de caractères spéciaux à l'exception du caractère underscore (on remplace généralement les espaces par le caractère underscore : "_").

Une fois que l'on a attribué un identifiant à un champ, son nom de variable apparaît entre doubles accolades dans le listing des champs, à côté de son libellé et de son type :{{form_var_telephone}}

Différents types de variables

Mais outre ces variables liées à des champs de formulaire, il existe beaucoup d'autres types de variables utilisables :

* les variables concernant le workflow,
* les variables concernant le formulaire et les demandes,
* les variables concernant l'usager,
* les variables concernant le canal de saisie,
* les variables système,
* les variables de session dont {{ session_user_display_name }} pour récupérer le nom de la personne connectée, utile pour afficher le nom de l'agent qui vient de traiter une demande par exemple..

Ces variables sont utilisables dans un modèle decourriel, dans un modèle dedocument, dans l'affichage d'unmessageou dans la définition d'une logique de traitement d'un formulaire (workflow).

Lors du traitement, le mail, le message ou le document généré contiendra la valeur de la variable. Si par exemple, j'écris dans mon modèle d'envoi de mail  « Bonjour {{form_var_prenom}} », l'email envoyé à un usager, ayant saisi Arnold dans le champ prénom, contiendra « Bonjour Arnold ».

Pour trouver la valeur d'une variable quelle qu'elle soit, il est souvent très utile de consulter lespages d'inspection.

Variables concernant le workflow

Comme dans les formulaires, on peut définir un certain nombre de variables dans les workflows.

form_option_xxx | On peut définir des options ouvariables de workflowet leur donner un « nom », leur contenu sera alors disponible dans {{form_option_nom}}
-----------------------------------------------------------------------------------------------------------------------------------------------------------
form_status | Le statut actuel de la demande
form_previous_status | Le statut précédent de la demande considérée
form_status_changed | Un booléen précisant que la demande vient de changer de statut
form_evolution | Informations sur le dernier statut (pour les modèles de courriels)
form_role_receiver_name | Le nom du rôle en charge du traitement
form_role_receiver_details | La description du rôle (champ « Détails du rôle, affichés en front-office »)
form_role_receiver_emails | Les adresses électroniques associées au rôle en charge du traitement
form_criticality_level | Le niveau de criticité, 0 pour le niveau le plus bas, 101, 102, 103, etc. pour les suivants.

Variables concernant le formulaire

form_name | Le nom du formulaire
--------------------------------
form_receipt_date | La date de réception de la demande
form_receipt_datetime | La date et l'heure de réception de la demande
form_receipt_time | L'heure de réception de la demande
form_number | Le numéro attribué à la demande
form_url | L'adresse vers la vue (front-office) du formulaire
form_url_backoffice | L'adresse vers le formulaire dans le backoffice
form_tracking_code | Le code de suivi de la demande, s'il existe
form_details | L'ensemble des champs de la demande et valeurs saisies par l'usager
form_short_url | URL « raccourcie » pour les demandes. Cela peut s’avérer utile en particulier pour l’envoi de SMS.

Variables concernant l'usager (le demandeur)

Les données contiennent aussi des informations sur l'utilisateur ayant complété le formulaire. Et en particulier les informations de son profil (le nom des variables du profil est paramétrable, nous affichons ici le nom par défaut).

form_user_display_name | Le nom + prénom de l'utilisateur
---------------------------------------------------------
form_user_var_title | Civilité (Monsieur, Madame).
form_user_var_first_name | Prénom
form_user_var_last_name | Nom
form_user_var_email | Adresse électronique
form_user_var_address | Adresse
form_user_var_zipcode | Code postal
form_user_var_city | Commune
form_user_var_phone | Téléphone fixe
form_user_var_mobile | Téléphone mobile
form_user_nameid | Identifiant SAML de l'utilisateur (NameID), pour le fournisseur d'identités

Si un champ utilisateur personnalisé dispose d'un identifiant, alors la valeur de ce champ est accessible sous la formeform_user_var_variableduchamp, par exempleform_user_var_prenom.

Variables sur le canal de saisie

Les données contiennent aussi des informations sur le contexte de saisie de la demande. Elles sont utilisables uniquementaprès que la demande a été saisie, dans le workflow donc.

form_submission_backoffice | Vrai si la saisie a eu lieu depuis le backoffice
-----------------------------------------------------------------------------
form_submission_channel | Identifiant du canal de saisie (ex : mail)
form_submission_channel_label | Libellé du canal de saisie (ex : Courrier)

Variables système

Ces variables sont accessibles à tout endroit du site. Pour intégrer au mieux un lien interne à Publik et éviter des liens en durs qui ne seraient plus valables après passage d'une installation de recette à une installation en production, il est possible d'utiliser ces variables de substitution pour l'url, du type {{eservices_url}},{{portal_url}}...

site_name | Le titre du site
----------------------------
site_theme | L'identifiant du thème en cours
portal_url | L'adresse du portail usager
portal_agent_url | L'adresse du portail agent
eservices_url | L'adresse du site de démarches
site_url_backoffice | L'adresse vers le backoffice du site des démarches
idp_url | L'adresse du fournisseur d'identités
agendas_url | L'adresse du service d'agenda
porte_doc_url | L'adresse du service de porte-documents
passerelle_url | L'adresse du service de gestion des connecteurs
statistics_url | L'adresse du service de statistiques
lingo_url | L’adresse du service de gestion de facturation et de tarification, lorsque déployé
site_lang | Le code de la langue utilisée par le site
today | La date du jour
now | La date et l'heure du jour
is_in_backoffice | Vrai si la page actuelle est consultée dans le backoffice. Permet, par exemple, de créer des pages conditionnelles uniquement accessibles en saisie backoffice. Pour obtenir l'effet inverse, on peut utiliser not is_in_backoffice.

À l'intérieur d'une catégorie, les variables suivantes sont également définies :

category_name | L'intitulé de la catégorie
------------------------------------------
category_description | La description de la catégorie
category_id | L'identifiant de la catégorie

Il est possible de faire transiter une variable à l'intérieur d'une URL en utilisant

[request.GET](https://doc-publik.entrouvert.com/admin-fonctionnel/parametrage-avance/envoyer-un-parametre-a-un-formulaire-gra/)

Variables supplémentaires

Des variables supplémentaires peuvent également être définies par l'administrateur système, via des variables d'environnement ou la configuration de l'instance de w.c.s. Il est ainsi souvent créée une variable {{ collectivite }} utilisée pour récupérer le nom de la collectivité utilisatrice d'une instance particulière de Publik.

Certaines variables peuvent avoir un comportement spécifique suivant le slug attribué :

global_title | Intitulé de l'instance, qui peut être utilisé dans le thème graphique
------------------------------------------------------------------------------------
environment_label | Utilisé pour préciser si l'instance est une instance de test
logo_link_url | Lien associé au logo présent dans le header
include_authors_in_form_history | À positionner à "False" pour ne pas afficher le nom des agents dans l'historique de traitement en front-office

* Studio
* Les tutos

# Pages d’inspection, debug et audit

Pages d’inspection, debug et audit

Les pages d'inspection sont des pages spécifiques pour aider à comprendre et à débugguer les demandes, les formulaires et les workflows.

Journal des erreurs

Chaque fois qu’une erreur est générée, la trace apparaît dans le backoffice (sur la page du workflow et sur la page du formulaire concernés, ainsi que sur la page d’accueil « studio »). Le journal contient un lien vers la page d'inspection de la demande.

Formulaires

La page d'inspection d'un formulaire est accessible en cliquant sur le lien « Inspecteur » à droite depuis la page d'accueil du formulaire.

Elle reprend les principales rubriques de la page d'accueil (Informations, Workflow, Options) mais elle offre surtout, dans le dernier onglet, une vue technique sur l'ensemble du paramétrage des champs. Elle permet également d'afficher des statistiques sur les brouillons des usagers sur le formulaire.

Récupération/suppression d'un formulaire cassé

En cas d'erreur irrémédiable sur un formulaire, il est possible que l'on accède plus à la page d'accueil permettant son paramétrage ou son inspection. Il reste possible de l'exporter en suffixant l'URL avec /export :

https://URL-DES-DEMARCHES/backoffice/forms/NUMERO-DU-FORMULAIRE/export

ou de le supprimer avec

https://URL-DES-DEMARCHES/backoffice/forms/NUMERO-DU-FORMULAIRE/delete

Blocs de champs

La page d'inspection d'un bloc de champs est accessible en cliquant sur le lien « Inspecteur » à droite depuis la page d'accueil du bloc. L'onglet « Champs  » offre une vue technique sur l'ensemble du paramétrage des champs.

Demandes / Fiches

Cette page n'est accessible que lorsqu'une demande ou une fiche a été remplie pour le formulaire concerné, il faut donc s'assurer au préalable qu'il y a bien une demande/fiche existante pour le formulaire ou le modèle de fiche concernée.

Pour chaque demande/fiche, la page d'inspection de celle-ci est accessible en cliquant sur le lien « Inspection des données » en marge droite.

Il existe une alerte visuelle lorsqu'une valeur contient une succession d'espaces, ce qui permet de détectuer plus facilement les incohérences dans les recherches, l'utilisation de filtres de requête ou l'écriture de conditions.

Outil de test

Cet outil va vous permettre de tester le résultat de conditions et de gabarit utilisant différentes syntaxes :

* Condition (Django)
* Condition (Python)
* Gabarit / Expression (Django)
* Gabarit HTML (WYSIWYG)

Cela facilite grandement la compréhension du fonctionnement des conditions.

Onglet « Variables »

Sous l'outil de test, on trouvera :

* Dans la première colonne : l'ensemble des variables utilisées pour cette demande
* Dans la deuxième colonne : la valeur de ces variables au moment où on regarde cet écran (et parfois leur type entre parenthèses).

Cet écran permet donc de vérifier la valeur d'une variable à un instant t du traitement et facilite ainsi la recherche et l'identification des problèmes.

Onglet « Fonctions »

Cette partie liste l'ensemble des fonctions qui interviennent dans le workflow avec en face le rôle dépositaire de la fonction.

Onglet « Suivi des actions »

Cette partie liste les différentes actions qui ont été appliquées à la demande, ou à la fiche, observée avec un lien vers l'action concernée dans le workflow. Les actions sont horodatées.

Workflows

La page d'inspection d'un formulaire est accessible en cliquant sur le lien « Inspecteur» à droite depuis la page d'accueil du workflow.

Portail - Outil de test de gabarit

Permet de tester un gabarit Django et d'ajouter une URL récupérant les variables de la page.

Journal d'audit (liste des accès à une demande ou à une fiche)

Sur la page d'accueil de Studio, un bouton « Journal d'audit » donne accès à une page permettant de tracer les accès à une demande ou à une fiche. La page permet de filtrer :

* Par date
* Par utilisateur
* Par formulaire / demande
* Par type d'accès

* Studio
* Les tutos

# Connecteur avec un fichier tableur (CSV ou ODS)¶

Connecteur avec un fichier tableur (CSV ou ODS)¶

Attention: l'utilisation d'un fichier tableur comme source de données est déprécié, au profit de l'utilisation desfiches. Aussi, si vous devez créer maintenant une source de données, prévoyez directement une gestion de votre source de données à base de fiches.

Dans un formulaire on peut avoir besoin d'une liste d'éléments provenant d'une source extérieure (ça permet de réutiliser ladite liste dans plusieurs formulaires, et facilite sa maintenance).

La façon la plus simple de mettre en place une telle liste, est de faire un fichier tableur (au format CSV ou ODS) qui servira de base à la mise enplace d'un connecteur dans Passerelle.

Cela se fait en plusieurs étapes :

* préparation du fichier tableur
* création d'un connecteur qui va diffuser le contenu du fichier sous la forme d'une ressource Web;
* ajout d'une source de données dans la fabrique de formulaires, afin de rendre les élements de ce connecteur plus facilement utilisables dans tous les formulaires.

Préparation du fichier tableur¶

Le fichier tableur doit avoir au moins deux colonnes :

* une première colonne contenant un identifiant unique pour chaque ligne (valeur numérique ou texte, peu importe)
* une seconde colonne contenant les éléments que l'on souhaite faire apparaître dans la liste du formulaire.

Le fichier peut comporter d'autres colonnes, comprenant des informations qui seront elles aussi exploitables dans le formulaire.

Si vous souhaitez gérer des éléments désactivés (qui n'apparaîtront pas dans la liste du formulaire), vous devez prévoir une colonne « disabled » qui sera vide pour les éléments à afficher et complétée d'une valeur, quelconque, pour les éléments désactivés.

Prenons l'exemple d'un fichier dans lequel chaque arrondissement est représenté par son numéro :

Identifiant | Arrondissement | Population
-----------------------------------------
1 | 1er arrondissement | 25000
2 | 2nd arrondissement | 35000
3 | 3ème arrondissement | 45000

Attention, les fichiers doivent être encodés en UTF-8.

Création d'un connecteur CSV¶

Pour transformer ce fichier en connecteur :

* se rendre dans le menu «Services web»
* cliquer sur «Ajouter un connecteur» (en haut à droite)
* dans la ligne «Sources des données», cliquer sur «Fichier tableur»
* compléter les champs nécessaires :Titre : donner un nom à votre source de données.Description : rappeler son objectif.Fichier tableur : joignez ici votre fichier CSV ou ODS.Noms des clés pour les colonnes : ici il faut donner un nom (sans accents ni espace) à chaque colonne du fichier. Les noms sont séparés par des virgules. Pour notre fichier exemple on aura :id(nom obligatoire, qui désigne la colonne de l'identifiant)text(nom obligatoire, qui désigne la colonne devant apparaître dans la liste)population (nom libre choisi pour désigner la troisième colonne)Passer la première ligne : si la première ligne de votre fichier contient le nom des colonnes (comme dans l'exemple donné) alors il faut cocher cette case pour que la première ligne ne soit pas considérée comme faisant partie des données.Nom de la feuille : à renseigner quand vous utilisez le format ODS, pour indiquer la feuille à utiliser, par exemple : «Feuil1».
* Cliquer sur «Enregistrer».

La page de présentation du connecteur s'affiche alors, indiquant lesPoints d'accèsdu connecteur (ce qu'on appelle aussi lesendpointsde l'API, c'est-à-dire les adresses par lesquelles les données sont accessibles.)

Il faut alors régler lasécuritédu connecteur, car par défaut celui-ci est inaccessible. Pour cela, en dessous du tableau «Sécurité», cliquer sur «Ajouter» et ajouter l'utilisateur Passerelle de votre choix. En général un utilisateur «Public» est disponible qui autorise un accès public au connecteur.

Votre connecteur CSV est maintenant créé. Vous devez noter son adresse, qui doit être du type :

* {{passerelle_url}}csvdatasource/nom-de-la-source/

Lepoint d'accès aux donnéesest le suivant :

* {{passerelle_url}}csvdatasource/nom-de-la-source/data

Si vous obtenez une erreur 403 en essayant d'accéder à votre connecteur c'est certainement parce que vous n'avez pas l'autorisation d'accéder à l'API. Cette autorisation se règle sur la partie inférieure de l'écran d'accueil : « Sécurité » et sur l'url {{passerelle_url}}manage/access/

Création de la source de données associée¶

Votre connecteur nouvellement créé est déjà utilisable dans un formulaire. Mais si vous envisagez de l'utiliser dans plusieurs formulaires, faîtes-vous une faveur : créez une source de donnée liée à ce connecteur. Elle va vous permettre de réutiliser la liste beaucoup plus simplement et sans risque d'erreur. Pour créer cette source, vous devez vous rendre dans la fabrique de formulaires et utiliser le lien «Sources de données» en haut à droite.

Cliquez sur «Nouvelle source de données», toujours dans la colonne droite.

* Indiquer un nom et une description, généralement les mêmes que ceux choisis lors de la configuration du connecteur CSV.
* Au niveau de «Source de données», choisir le type «URL du JSON».
* Indiquer ensuite l'URL du point d'accès aux données, voir ci-dessus. Il s'agit de l'adresse URL du connecteur suivie de /data.

Votre liste est maintenant disponible dans «Source de données» (dans les paramètres avancés) lorsque vous éditez un champ de type liste dans un formulaire.

Si un champ liste (identifiant « liste ») est lié à un fichier tableur comprenant les colonnes « nom » et « prenom », on récupèrera le contenu de ces colonnes dans les variables

{{ form_var_liste_nom }}

et

{{ form_var_liste_prenom }}

. Dans notre exemple

{{ form_var_liste_population }}

contiendra « 25000 » si form_var_liste contient « 1er arrondissement ».

Il est possible de construire desrequêtespour aller plus loin dans l'utilisation des données contenues dans un fichier CSV ou ODS.

* Studio
* Les tutos

# Catégories

Catégories

Les catégories servent à ranger les items (formulaires, workflows, fiches, blocs de champs) par thème, à la fois dans le portail agent et dans le portail citoyen.

Elles sont accessibles en cliquant sur le bouton « Catégorie » en haut de l'écran concerné. L'ordre des catégories dans la liste détermine l'ordre d'affichage sur le portail agent, il peut être modifié par glisser déplacer

Dans le portail citoyen, l'ordre d'affichage des catégories est entièrement personnalisable, ainsi que l'ordre des formulaires au sein d'une catégorie. Il faut pour celaéditer le portail citoyen.

S'agissant des formulaires, le texte de description des catégories va pouvoir être utilisé pour affichage en dessous du nom de la catégorie sur le portail citoyen. Pour ajouter une image illustrant la catégorie, il faut d'abord utiliser la catégorie dans le portail citoyen (par exemple en ajoutant une cellule « démarche d'une catégorie »). Une ressource image vide va apparaître dans les ressources du portail, permettant de la remplacer par une image ou une photo.

Droits d'accès

Lorsqu'une catégorie est utilisée (et pas tant qu'elle est vide), il est possible de définir des droits d'accès la concernant. On va sélectionner, en éditant chaque catégorie, les rôles dont on souhaite qu'ils soient capacité d'éditer les formulaires, fiches ou workflow de la catégorie.

Pour les formulaires il est même possible de donner séparément un accès pour les exports de données et un accès aux statistiques pour les formulaires de la catégorie en question.

* Studio
* Les tutos

# Studio

Studio

Studio permet de construire desformulaires(pour développer des services publics numériques) et desapplications métiers100% adaptés à vos besoins, sans avoir besoin d'utiliser un langage informatique (no-code ou low-code).La page d'accueil du Studio est composé de différents éléments :

Recherche

Une interface de recherche permet de trouver rapidement un formulaire, un modèle de fiche, un workflow, etc. Inclut les libellés des statuts et des actions globales des workflows, ainsi que les paramètres des appels webservice.L’interface est accessible en cliquant sur la loupe en haut à droite.

Les formulaires sont utilisés pour recueillir les demandes des usagers.

Modèles de fiche

Les fiches sont utilisées pour gérer des données structurées.

Workflows

Les workflows sont utilisés pour définir les comportements et les actions associés aux démarches et aux fiches.

Modèles de courriel

Modèles de message

Appels de webservice

Multilinguisme

Journal d’audit

Modifications récentes

Erreurs récentes

Rapport sur les dépréciations

Corbeille, suppressions récentes

Permet de restaurer les formulaires, modèles de fiche et workflows (pas les demandes) après une suppression.

* Documenter dans Studio
* Multilinguisme
* Protection dite « pot de miel »

* Studio
* Les tutos

# Progressive Web App (PWA)

Progressive Web App (PWA)

La Progressive Web App désigne une application mobile qui se différencie des applications dites « natives » par le fait qu'elle n'est pas présente dans les stores d'Apple et Google. Il s'agit d'une fonctionnalité native de Publik, pensée pour permettre un usage mobile optimisé. Elle nécessite que le thème graphique utilisé soit compatible avec cet usage mobile et il est même préférable que ce thème ait été créé dans une logique « mobile first ». Les principales caractéristiques de la PWA :

* Aucun code spécifique à maintenir/développer alors que les applications natives nécessitent le développement et la maintenance d'une version différente pour chaque store
* l'ajout d’une icône sur l’écran d’accueil du smartphone, à la première consultation
* la présentation d’un écran de lancement lorsque la PWA est lancée
* un look and feel « appli like », notamment avec suppression de la barre de navigation
* l‘affichage d’un menu mobile
* les notifications sur mobile (nécessite que l'usager les active explicitement)
* l’utilisation du GPS et de l'appareil photo du mobile

La PWA peut avoir des fonctionnalités ou des comportements un peu différents en fonction des smartphones utilisés. Google, Microsoft, Apple, et autres ont une intégration variable dans le temps des fonctionnalités PWA.

Activation du mode PWA de Publik

L’activation du mode PWA doit être faite par un administrateur technique.La vérification de l’activation de la PWA se fait par la présence de «  Application Mobile (PWA) » dans le menu burger du portail usager.

Pour que le mode PWA soit actif, le premier paramétrage à faire est d’ajouter l’icône de l’application.

Menu de navigation

La PWA peut intégrer un menu dédié. La configuration du menu est faite en ajoutant, dans l'écran de configuration,  des entrées à la navigation. Chaque entrée doit définir : un libellé, un lien interne ou url externe, une icône (de l'ordre de 20 pixels de haut dans le cas des intégrations natives) et éventuellement des options graphiques :

* « Afficher le nombre de notifications » : si une des entrée pointe vers une page contenant une «Cellule Notification», lorsque desnotifications sont envoyées au demandeur, un indicateur du nombre de notifications apparaît sur l’entrée concernée.
* « Utiliser le nom de l’usager comme libellé » : lorsque l’usager est connecté, le libellé de l’entrée sera remplacé par le nom de l’usager

Notifications « WebPush »

Les notifications « WebPush » sont des notifications que l'usager va recevoir sur son téléphone même s'il n'a pas lancé l'application. C'est un moyen très intéressant d'informer l'usager : la notification est gratuite comme les courriels et presque aussi visible qu'un SMS. Elle est soumise à deux impératifs pour fonctionner correctement :

* Dans l'écran de configuration de la PWA, l'administrateur fonctionnel doit cocher la case « Activer la possibilité de s’abonner à des notifications « Push » ».
* L'usager doit explicitement autoriser les notificationsdans l'application via un bouton dédié, c'est différent de ce que propose les applications natives. Il est donc nécessaire de l'informer qu'il doit activer ces notifications s'il souhaite en recevoir.

Les notifications sont supportées par tous les navigateurs sauf, provisoirement, Safari (MacOS et iOS). Apple a rejoint tardivement le reste des troupes et permettra l'utilisation des notifications début 2023 :

[https://pushalert.co/blog/safari-web-push-api-support-browser-notifications/](https://pushalert.co/blog/safari-web-push-api-support-browser-notifications/)

).

Les notifications « WebPush » sont envoyées avec une simpleaction de notificationdans les workflows : dès que la fonctionnalité est activée, l'action de notification envoie à la fois une notification sur le tableau de bord de l'usager et une notification « WebPush ».

Paramétrage

Les paramètres de la PWA permettent de:

* choisir le nom de l’application ou nom de l’icône sur l’écran d’accueil
* définir l’icône. L'icône doit être carrée et faire au moins 512x512 pixels. « Icône Adaptative » permet d'activer et visualiser (cercle en pointillé sur l'icône) la zone centrale importante qui sera utilisée par certains navigateurs.
* définir le texte d’information si non-connecté
* définir un menu mobile flottant
* d’inclure un bouton pour ressayer la connexion
* d’activer la possibilité de s’abonner à des notifications « push »

Ajout de l'icône sur le bureau IOS

IOS ne propose pas encore l'ajout automatique de l'icône de la PWA sur le bureau d'accueil. L'opération doit être faite manuellement par:

* Touchezen bas de l’écran.
* Appuyez « Sur l’écran d’accueil ». Il est possible que vous deviez balayer vers la gauche pour trouver le bouton « Sur l’écran d’accueil ». L'icône apparaît sur l'écran d'accueil, comme une application mobile.

* Studio
* Les tutos

# Agendas : événements et rendez-vous

Agendas : événements et rendez-vous

La gestion d'agendas est utilisée pour gérer :

* laprise de rendez-vous;
* l'inscription à des événements;
* lesagendas virtuels.

Le paramétrage des agendas est accessible depuis l'entrée de 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é »), pour des rendez-vous (par exemple « Rencontre avec Madame la Maire ») ou encore d'un agenda virtuel (agrégeant plusieurs agendas rendez-vous), ainsi que les rôles d'édition et de visualisation de l'agenda.

Une fois qu'ils sont créés, les agendas (rendez-vous ou événements) deviennent disponibles comme sources de données utilisables dans les champs listes. Toutefois, il y a un temps de propagation (jusqu'à 1 heure) avant que ces sources de données apparaissent quand on configure un champ liste. Pour les voir sans délais, vous pouvez « forcer » cette propagation en allant dans l'écran des sources de données (via le bouton en haut de la page d'accueil des formulaires par exemple) et en cliquant sur « Actualiser les agendas ».

Permissions des agendas

Il est possible de configurer les rôles d'accès aux agendas de type Rendez-vous et Évènements. Il en existe trois :

* Rôle d’administration
* Rôle d’édition
* Rôle de visualisation

Les rôles d'administration et d'édition ont accès au paramétrage des agendas avec un niveau de permissions qui diffèrent.

Pour les agendas de type Rendez-vous :

Permissions | Rôle d'édition | Rôle d'administration
----------------------------------------------------
Types de rendez-vous | ❌ | ✅
Plages horaires | ✅ | ✅
Ressources | ❌ | ✅
Paramètres d'affichage | ❌ | ✅
Prise de rendez-vous backoffice | ❌ | ✅
Rappels de réservation | ✅ | ✅
Délais de réservation | ✅ | ✅
Permissions | ❌ | ✅
Autres options accessibles depuis le menu kebab | ❌ | ✅

Pour les agendas de type Évènements :

Évènements | ✅ | ✅
Exceptions aux récurrences | ✅ | ✅
Paramètres du pointage | ❌ | ✅
Notifications d'administration | ✅ | ✅
Rappels de réservation | ❌ | ✅

Agendas

* Évènements
* Rendez-vous
* Agendas virtuels
* Enregistrer, modifier, annuler dans un agenda
* Paramétrage avancé des workflows pour les agendas

* Studio
* Les tutos

# Développer des applications métier avec Publik Studio

Développer des applications métier avec Publik Studio

Publik permet de développer des applications et de les échanger librement dans unmagasin applicatif.

Publik Studio utilise les éléments phares de Publik (fabrique de démarches, sources de données, gestionnaire de contenus - CMS, etc.) pour permettre de construire rapidement une interface de gestion de données structurées. Il permet de développer des applications métiers sans avoir besoin d'utiliser un langage informatique (no-code ou low-code). Ces applications disposent, nativement, d'un portail web : votre instance de Publik.

La page d’accueil de Publik Studio est  le centre de pilotage de l'activité pour l'administrateur fonctionnel Publik, attention elle pourrait devenir votre page préférée. Elle agrège des accès :

* aux formulaires, fiches, workflows
* aux sources de données, blocs de champs, modèles de courriel, appels webservices
* aux modifications
* aux erreurs enregistrées.

Une page d’information sur les dépréciations est accessible depuis la page d’accueil de Publik Studio, elle liste les

[utilisations dépréciées](https://doc-publik.entrouvert.com/admin-fonctionnel/elements-deprecies/)

comme la syntaxe EZT, l’utilisation de JSONP ou les expressions Python.

Publik Studio est aujourd'hui utilisé pour construire des applications aussi complexes qu'une application famille / enfance mais il peut aussi être utilisé pour construire, très rapidement, une interface simple de saisie / modification / affichage d'un jeu de données particulier. Si certaines applications métiers offrent des webservices satisfaisants permettant l'interconnexion avec Publik, d'autres, dépassées technologiquement, ne le permettent pas. Pour ces dernières, il pourra être plus rapide et surtout plus robuste de re-créer les référentiels et les interfaces de traitement dans Publik plutôt que de chercher à faire un connecteur asynchrone.

* Studio
* Les tutos

# Fabrique de formulaires

La brique Fabrique de formulaires permet de dématérialiser le formulaire d'une démarche.

La brique Fabrique de formulaires est accessible depuisle menu principalduportail agentauxagents habilités à dématérialiser une démarche.

La brique Fabrique de formulaires se compose de trois niveaux de visualisation d'un formulaire :

* La liste des formulaires: La Liste des formulaires offre une vue globale et structurée des formulaires existants.
* Le détail d'un formulaire: La page de détail d'un formulaire offre une vue des propriétés, du contenu et de la structuration d'un formulaire.
* La page d'édition des champs d'un formulaire: La page d'édition des champs d'un formulaire offre une vue linéaire des champs qui assure le contenu et la structuration d'un formulaire ainsi que la possibilité de les paramétrer, d'en ajouter ou d'en supprimer.

* Studio
* Les tutos

Les tutos

Dans cette rubrique retrouvez des exemples de paramétrages sur des thématiques spécifiques.

Pour certains vous pouvez récupérer en bas de page les fichiers d'exemple que vous pourrez importer sur votre plateforme Publik.

* Paiement

Les tutos

* Paiement

* Studio
* Les tutos

# Envoyer un paramètre à un formulaire grâce à une URL avec request.GET

Envoyer un paramètre à un formulaire grâce à une URL avec request.GET

Il peut être utile de préremplir un ou plusieurs champs d'un formulaire grâce à l'URL utilisée pour accéder à ce dernier.

C'est possible en utilisant une URL de la forme :

https:/mon-site/mon-formulaire/?parametre=la-valeur-a-transmettre

la-valeur-a-transmettre peut être une variable du type {{ form_var_value }}.

Il est préférable que la valeur à transmettre soit encodée. Pour cela, vous pouvez utiliser le filtre {{ form_var_value|urlencode }}

Il suffira ensuite, pour récupérer la-valeur-a-transmettre, de préremplir le champ concerné dans le formulaire avec le gabarit suivant :

{{request.GET.parametre|default:""}}

Quelques limites à connaître : le paramètre n'est utilisable que sur latoute première pagedu formulaire et il ne peut être utilisé que pour dupréremplissage. Pour cette raison il est conseillé de n'utiliser request.GET que dans des champs de typedonnée calculée.

* Studio
* Les tutos

# Créer des indicateurs statistiques

Créer des indicateurs statistiques

Attention cette page sera progressivement dépréciée au profit de l'utilisation de

[cellules graphes](https://doc-publik.entrouvert.com/admin-fonctionnel/modifier-le-contenu-des-portails/les-cellules/cellules-visualisation-des-donnees/#graphe)

pour construire des indicateurs statistiques, au fur et à mesure que la cellule graphe va s'étoffer pour permettre de faire la même chose que la brique décrite ici.

La brique « Statistiques » permet de fabriquer des indicateurs statistiques pour une démarche particulière ou pour toutes les démarches existantes. Si plusieurs sites de démarches existent alors chacun d'entre eux est analysé.

La page d'accueil des statistiques affiche la liste des sites de démarches pour lesquels des tableaux sont disponibles, s'il n'y a qu'un seul site de démarches dans l'instance de Publik alors l'utilisateur est automatiquement redirigé sur la page listant les formulaires disponibles.

Lors de la construction d'un indicateur, il est possible de choisir une représentation sous forme de tableau ou de graphique. Les graphiques peuvent bien entendu se révéler illisibles si les données sont trop complexes, les libellés trop longs, etc. Il faudra alors privilégier la représentation sous forme de tableau.

Indicateurs pour une démarche en particulier

Il est possible,  pour une démarche donnée, de choisir la donnée statistique à mesurer parmi :

* le nombre de demandes,
* le temps moyen de résolution d'une demande (temps écoulé entre l'entrée dans le workflow i.e. 1er statut et le 1er statut qualifié de final),
* le temps maximum de résolution d'une demande,
* le temps minimum de résolution d'une demande,
* le pourcentage de demande (à n'utiliser qu'avec un regroupement)

Les demandes peuvent être regroupées selon différents critères:

* l'année,
* le mois,
* le jour de la semaine,
* l'heure,
* le premier agent traitant,
* les valeurs de n'importe quelle liste à choix fermés (champs du formulaire et champs de traitement),
* le statut en cours.

Les demandes peuvent également être filtrées par:

* leur date de soumission ;
* leur canal d'arrivé ;
* leur statut simplifié : nouveau (les demandes positionnées dans le 1er statut du workfow), en cours (les demandes dans des statuts non tagués en tant que final) ou terminé (les demandes dans les statuts tagués en tant que final) ;
* leur premier agent traitant ;
* leur statut.

Plusieurs critères de regroupement ou de filtrage sont utilisables en même temps.

Une fois ces critères déterminés il est possible :

* d'obtenir une URL qui pourra être transmise à une tierce personne disposant d'accès à la brique statistiques de Publik pour obtenir exactement la même visualisation,
* d'obtenir une URL signée qui pourra être intégrée dans n'importe quelle page web en utilisant une iframe et présentera la même visualisation sans nécessité d'authentification,
* de donner un nom et de sauvegarder ce paramétrage, la visualisation ainsi sauvegardée est affichée en page d'accueil des statistiques.

Indicateurs sur l'ensemble des démarches de l'instance

Les mêmes indicateurs peuvent être construits sur l'ensemble des démarches à l'exception bien sûr des critères dépendant d'une démarche en particulier :

* pas de regroupements sur des valeurs de listes à choix fermés,
* pas de regroupement ou filtre sur le statut mais bien uniquement sur les statuts simplifiés (statuts communs à toutes les démarches).

Il est à noter qu'il est possible de construire une visualisation sur quelques démarches seulement (sélection multiple possible dans le filtre « Formulaire ») et d'effectuer des regroupements si l'identifiant de la liste à choix fermés utilisée dans les divers formulaires est identique.

Agréger les indicateurs dans des rapports statistiques

Une fois qu'une visualisation est enregistrée, elle est alors disponible pour être ajoutée dans le portail agent. Il suffit pour cela d'éditer ce dernier, d'ajouter une cellule de type « Visualisation de données » puis « Graphe » ; en éditant la cellule, vous y verrez exposé toutes les visualisations prélablement enregistrées.

Créer des rapports statistiques

* Studio
* Les tutos

# Gérer les rôles

Gérer les rôles

Les rôles sont au coeur de Publik. Ils permettent d'attribuer les droits des agents traitant les demandes, les droits des concepteurs de démarches et les droits d'administration de l'ensemble.

Il existe deux catégories de rôles, les rôles d'administration ou rôles "techniques" et les rôles fonctionnels ou rôles "métiers".

Un rôle peut se voir associer plusieurs permissions ou ne servir qu'à grouper des utilisateurs ou d'autres rôles.

Publik gère l'héritage entre rôles.

Afin de débuter dans les meilleures conditions, nous vous conseillons la page surles principes.

Cette partie de la documentation ne concerne que l'administration au travers des interfaces graphiques. Pour l'utilisation des API, se référer à la documentation surle développement.

* Studio
* Les tutos

# Gérer les utilisateurs

Gérer les utilisateurs

La brique Utilisateurs permet de gérer les comptes des agents et des usagers.

La brique Utilisateurs est accessible depuisle menu principalduportail agentauxagents habilités à gérer les comptes des agents et des usagers.

La brique Utilisateurs se compose de deux niveaux de visualisation d'un utilisateur :

* La liste des utilisateurs: Il s'agit de la page d'accueil de gestion des utilisateurs qui permet la recherche et l'ajout des utilisateurs.
* La fiche d'un utilisateur: La fiche d'un utilisateur permet la visualisation du profil de l'utilisateur et donne accès à toutes les opérations d'administration sur l'utilisateur.

* Studio
* Les tutos

# Dématérialiser une démarche en 10 minutes

Dématérialiser une démarche en 10 minutes

Le travail le plus long dans la mise en ligne d'une démarche concerne la définition et la création de son circuit de traitement (workflow). Mais lorsque ce circuit de traitement existe déjà (on le récupère depuis une démarche proche ou on utilise le workflow par défaut), on peut aller très vite.

En s'appuyant sur unworkflow existant donc, l'administrateur fonctionnel « n'a plus qu'à » fabriquer un formulaire et à le publier pour que la nouvelle démarche soit opérationnelle.

Voici les étapes à suivre pour dématérialiser une démarche en 10 minutes à partir d'un workflow existant:

Étape 1:Créer le formulaire

En validant trois champs (titre, workflow, catégorie), le formulaire est créé.

Le formulaire nouvellement créé apparaît désormais au sein de laliste des formulaires, dans la catégorie qui lui aura été attribuée.

Depuis ledétail du formulairel'administrateur fonctionnel pourra définir le contenu du formulaire et le publier.

Si aucun workflow existant ne convient à la démarche à dématérialiser, Publik offre la possibilité dedematérialiser un workflow.

Étape 2 :Ajouter des champs

Une fois le formulaire dématérialisé crée, l'administrateur fonctionnel doit y ajouter les différents champs qui existent sur le formulaire papier. C'est l'occasion de vérifier qu'ils sont réellement indispensables et de supprimer ceux qui ne le sont pas : la dématérialisation doit être l'occasion d'une simplification.

Étape 3 : Paramétrerles champs

Une fois les champs ajoutés, l'administrateur fonctionnel dispose d'une variété deparamètres génériquespour personnaliser le comportement d'un champ de formulaire. Les champs peuvent en particulier êtrepréremplis.

Étape 4 : Définir qui fait quoi

Dans le bloc « Workflow » dudétail du formulaire, on positionne les rôles adéquats en face des fonctions « destinataires » (pour dire qui va traiter les demandes reçues) et « Rôle de l'utilisateur » (pour dire qui va pouvoir faire des demandes).

Étape 5 : Mettre en production

Il ne reste plus qu'à activer le formulaire pour le rendre accessible.

La publication d'une démarche s'effectue depuis la pagedétail du formulaire, en éditant la propriété  « Option / Publication » et en décochant « Désactiver l'accès au formulaire ».

Avant de publier une démarche, il est fortement conseillé de latester.

# Données de traitement (action)

Données de traitement (action)

Cette action n'est disponible que lorsque l'on a, au préalable, configuré au moins un champ de traitement comme c'est expliqué dans lapage « Données de traitement (champ) ».

L'action permet d'associer une valeur à une ou plusieurs données de traitement. Il est possible d'utiliser desexpressions élaboréespour calculer cette valeur.

Pour un champ de type fichier, il suffit d'indiquer le nom de la variable, qu'il s'agisse d'un fichier du formulaire ou d'un fichier d'un formulaire de workflow {{ form_var_fichier }}. Il est également possible de créer un fichier à partir d'une structure de données de type dictionnaire, contenant une cléfilenameet au choix une clécontent(pour du contenu direct) ou une cléb64_content(pour du contenu encodé en base64).

Pour un champ de type « Liste à choix multiple », il est possible d'utiliser du texte en séparant les valeurs avec des |, par exemple :

choix1|choix2

choix1 et choix2 étant les identifiants des valeurs possibles.

Il est également possible d'utiliser un « Gabarit » et d'y mettre le nom de variable d'une liste à choix multiple issue du formulaire avec le suffixe _raw (pour récupérer les identifiants et non les libellés) :

{{ form_var_MA-LISTE-A-CHOIX-MULTIPLE_raw }}

Le libellé et la valeur de la donnée de traitement sont affichés dans l'écran de traitement de la demande, au-dessus de l'historique.

Une case à cocher peut être alimentée avec le texte « True » ou « False », cela affichera un « Oui » ou un « Non » dans l'interface de traitement de la demande en face du nom de la donnée de traitement.

* Studio
* Les tutos

# Les blocs de champs

⚙️ Accès dans le BO :Studio > Formulaires > Blocs de champs

Lesblocs de champspermettent d'insérer un ensemble de champs dans un ou plusieurs formulaires.Toute modification d'un bloc de champs est automatiquement répercutée sur les formulaires qui l'utilisent.Toute suppression d'un champ d'un bloc de champ supprime les valeurs de ce champ enregistrées dans les demandes qui l'utilisaient.

🔑 Fonctionnalités clés

Les blocs de champs sont principalement utilisés dans deux situations clés :

* Comme modèle réutilisable: lorsque vous avez un ensemble de champs que vous souhaitez réutiliser dans plusieurs formulaires.Par exemple, un bloc « Identité » contenant des champs Prénom, Nom, Adresse qui sera utilisé dans plusieurs formulaires. Vous modifiez le bloc de champs, la modification est appliquée dans tous les formulaires qui l'utilisent.
* Pour créer plusieurs occurrences: quand on souhaite permettre à l'usager d'ajouter plusieurs fois un même ensemble de champs.Par exemple, si l'usager doit envoyer plusieurs fichiers sans savoir combien à l'avance, ou ajouter plusieurs enfants. Un bloc de champs « Enfant » avec les champs Prénom, Nom et Date de naissance s'affiche une fois dans le formulaire, et l'usager peut le dupliquer autant de fois que nécessaire, en fonction du nombre d'enfants.

Créer un bloc de champs

<p>Proc&eacute;dure :</p>

<ul>
	<li>aller dans Studio/Formulaires</li>
	<li>cliquer sur &quot;Blocs de champs&quot;/&quot;Nouveau bloc de champs&quot;</li>
	<li>donner un nom au bloc de champ : attention ce nom ne peut pas &ecirc;tre chang&eacute; par la suite</li>
	<li>cr&eacute;er et param&eacute;trer les champs : on ne peut pas importer les champs depuis un formulaire existant</li>
	<li>on ne peut pas dupliquer un bloc de champs pour en cr&eacute;er un autre &agrave; partir d&#39;un bloc d&#39;exemple.</li>
</ul>

La gestion des blocs de champs est accessible en barre latérale droite, section “Navigation”, depuis la page backoffice de gestion des formulaires. Un bloc de champs a un nom, un identifiant (qui permettra d'accéder au bloc avec les variables), et un gabarit de résumé.

L'ajout, la modification et la réorganisation des champs est identique à la construction d'un formulaire. Il est possible d'ajouter à peu près tous les types de champs habituels, sauf une page, un tableau (tableau simple, tableau de liste et tableau de longueur libre) et les éléments classés.

L'ajout d'un identifiant aux champs du bloc permet d'accéder à la valeur d'un champ, mais contrairement à un champ de formulaire, l'identifiant ne sera pasform_var_identifiantmais sera noté..._identifiant. Les ... seront remplacés par l'identifiant du bloc de champs dans le formulaire, comme on va le voir juste après.

L'identifiant du bloc va permettre d'accéder aux valeurs des champs du bloc. Ainsi pour un bloc ayant pour identifiant

bloc_enfant

, les champs Prénom et Nom du bloc auront pour identifiant

bloc_enfant_prenom

,

bloc_enfant_nom

...

Insérer un bloc de champs dans un formulaire

Une fois un bloc de champs défini, il apparaît automatiquement dans la liste des types de champs, après les champs de mise en forme.

Une fois le bloc ajouté, il convient de le paramétrer en indiquant les paramètres habituels d'un champ (obligatoire ou facultatif, l'affichage, les classes de styles, les conditions d'affichage...). Il y a trois paramètres spécifiques au bloc :

* le nombre maximal d'éléments : le nombre de blocs que l'usager pourra ajouter ; vide ou zéro correspond à aucun : l'usager ne pourra pas ajouter de bloc ;
* le libellé du bouton « Ajouter » : si vide, le bouton permettant d'ajouter un bloc aura le libellé par défaut "Ajouter un autre" ;
* Le fait d'afficher un bouton permettant la suppression d'un bloc.

Attention quand vous affichez le bouton permettant la suppression, il faut lui laisser la place d'apparaître. Si vous avez deux champs qui utilisent des grid-1-2 sur la même ligne, l'icône de suppression empiétera sur le deuxième champ. Préférez l'utilisation de grid-5-12 pour ces deux champs.

Accéder aux valeurs

Les valeurs de chaque bloc sont accessibles avec un indice incrémentiel.

Ainsi, sur notre exemple ci-dessus, les prénoms des enfants seront accessibles (pour un champ de formulaire ayant pour identifiantenfant_scolarise, par exemple) avec

{{ form_var_enfant_scolarise_0_prenom }}
{{ form_var_enfant_scolarise_1_prenom }}
{{ form_var_enfant_scolarise_2_prenom }}

Pour lister les valeurs d'un champ donné quand on ne sait pas combien de blocs ont été ajoutés, on peut utiliser une boucle :

{% for enfant in form_var_enfant_scolarise%}{{ enfant.prenom }} {%endfor %}

Il est également possible de récupérer la liste de toutes les données saisies pour un champ particulier du bloc avec le filtre |getlist :

{{ form_var_enfant_scolarise|getlist:"prenom" }}

Nombre d'occurrences

Il est possible de connaître le nombre d'occurences du bloc de champs dans le formulaire avec |count

{{ form_var_enfant_scolarise|count }}

Faire un total

Il existe un filtre qui permet d'additionner les valeurs d'un champ du bloc : |sum. Pour additionner toutes les valeurs du champs dont l'identifiant est « montant », on écrira ;

form_var_enfant_scolarise|getlist:"montant"|sum

Afficher les valeurs

Afin d'afficher les différentes valeurs du bloc au sein d'une colonne dans les tableaux de traitement ou encore dans la variable {{ form_details }}, il faut définir un « Gabarit du résumé » dans les « Paramètres » du bloc.

Ainsi, sur notre exemple ci-dessus, les noms complets des enfants seront affichés si le gabarit de résumé du bloc est configuré avec {{block_var_prenom}} {{block_var_nom }} et apparaîtront ainsi dans la colonne : Zoé Durand, Marius Martin. Cette valeur sera accessible avecform_var_enfant_scolarise.

La classe csspk-blocks-zebrapermet d'alterner les couleurs de fond d'une occurrence à l'autre.

Afficher (ou pas) le titre du bloc de champs dans un formulaire

Une option « Affichage du libellé » sur les blocs de champs contenu dans les formulaires permet d’afficher le libellé normalement ou sous forme de sous-titre, ou encore de ne pas l’afficher du tout.

Afficher le numéro d'une ligne (occurrence)

Il est possible d'afficher le numéro de l'occurrence d'un bloc mais uniquement dans les champs de type titre, sous-titre et commentaire. Il faut pour cela utiliser la variable block_counter.index.

Par exemple écrire « Enfant {{ block_counter.index}} » dans un champ titre permettra d'afficher dans un formulaire avec deux enfants renseignés :

Enfant 1[...]Enfant 2[...]

Utiliser une condition dans un bloc de champ

Il est possible de masquer/afficher un champ du bloc en fonction d'une réponse à un autre champ du bloc. Il faut utiliser le préfixeblock_var_.

block_var_IDENTIFIANT permettra de désigner un champ du bloc sur lequel on va vouloir faire porter une condition. Ce même préfixe, qui n'est utilisable que dans le contexte du bloc, est à privilégier dans la définition du gabarit du résumé du bloc de champ.

Utiliser une condition de sortie de bloc de champ

De la même façon qu'il est possible d'utiliser une condition de sortie de page, il est possible d'utiliser une condition de sortie de bloc. La condition s'écrit dans lesparamètresdu bloc et s'applique à chaque occurrence du bloc dans une demande.

Pour un bloc de champ qui contient un champ "Date de naissance" avec l'identifiant est date_naissance, si on souhaite limiter la saisie à un âge maximal de 10 ans, la condition qui doit être satisfaite s'écritblock_var_date_naissance|age_in_years < 10.

Remplir un bloc de champ

Il est possible de remplir facilement un bloc de champ (typiquement dans une donnée de traitement ou une fiche) grâce au contenu d'un bloc de champ identique (provenant typiquement d'un formulaire), il suffira d'indiquer pour cela au niveau du préremplissage le nom de variable du bloc concerné.

{{ form_var_IDENTIFIANT-DU-BLOC-DANS-LE-FORMULAIRE }}

Mais il est également possible d'assigner à un bloc de champs une valeur construite adhoc grâce à l'utilisation de la balise {% block_value ... %} pour lui assigner une ou plusieurs lignes.

Remplir le bloc avec une seule ligne

{% block_value responsable=form_var_quelquechose relation=form_var_autre_chose %}

Cette expression va préremplir les deux champs du bloc ayant pour identifiant « responsable » et « relation » avec respectivement les valeurs de form_var_quelquechose et form_var_autre_chose.

Cette façon de procéder effacera tout contenu préexistant du bloc. Si, à la place, on souhaite ajouter une occurrence supplémentaire (une « ligne ») au bloc, il faudra ajouter dans la balise :

append=True

Remplir le bloc avec plusieurs lignes

Pour remplir un bloc de champ avec plusieurs ligne il faut utiliser la formule suivante :

{% block_value init=True as MON-BLOC %}
{% for ITEM in LISTE.ITEM %}
{% block_value MON-CHAMP-DU-BLOC=ITEM append=MON-BLOC as MON-BLOC %}
{% endfor %}
{% block_value output=MON-BLOC %}

Le init et le output servent respectivement à initier le bloc et à renvoyer la valeur finale agrégeant les différentes lignes.

Attention quand on veut préremplir un bloc, cette expression doit être saisie sur une seule ligne et sans espaces.

Utiliser des filtres de requêtes

Pour pouvoir utiliser les filtres de requête dans un bloc il faut utiliser une expression de la forme :

IDENTIFIANT-BLOC_IDENTIFIANT-CHAMP

Pour un bloc de champs « enfant » comprenant un champ « nom », on pourra utiliser

{{ form_objects|filter_by:"enfant_nom"|filter_value:"martin" }}

Dynamisme dans le bloc de champ

Voici quelques exemples d'utilisation :

* dans un champ de type commentaire, vous pouvez afficher dynamiquement la valeur d'un champ du bloc avec un gabarit comme {{ block_var_IDENTIFIANT }}.
* filtrer les éléments d'une liste en fonction de la sélection d'une première liste, en créant une source de données dynamique personnalisée. La valeur personnalisée à utiliser comme critère sera {{ block_var_IDENTIFIANT_raw }}.
* préremplissage d'un champ avec une valeur d'un autre champ du bloc, pour procéder à des calculs {{ block_var_IDENTIFIANTA|add:block_var_IDENTIFIANTB }}

* Studio
* Les tutos

# Introduction aux API

Introduction aux API

Cette section de la documentation s’adresse aux développeurs
d’applications tierces désirant interfacer celles-ci avec w.c.s.

Aspects techniques

L’API Web Services est constituée d’appels REST, qui sont idéalement effectués
en HTTPS, pour assurer la sécurité et la confidentialité des échanges. Le
format d’échange des données est JSON. Ces deux propriétés la rendent
accessible facilement à tous les langages et environnements de programmation
modernes.

Cette documentation se veut facile à lire, avec beaucoup de notes et
d’exemples.  Les différentes pages détaillent les points d’accès à
utiliser pour réaliser les différentes opérations.

* ParamétragePermissions d’administrationVariables d’environnementSurveillance et suivi applicatif
* API Web ServicesAccès aux listes et schémas de donnéesAccès à des référentiels externeAuthentificationComplétion et modification d’un formulaireRécupération des données d’un formulaireRécupération des données d’un utilisateurTraitement d’un formulaireGestion des fiches
* Dépréciation des conditions et expressions Python

Guide de l'intégration graphique personnalisée

L’intégration graphique personnalisée permet, en soignant les parcours d’un site à l’autre, de rendre l’expérience usager particulièrement fluide. Entr'ouvert intègre une charte graphique que la collectivité fournie.

La création graphique doit se conformer aux contraintes de Publik. Si la collectivité fait le choix de réaliser soi-même la charte graphique des portails, il est nécessaire, avant tout travail de conception graphique de se coordonner avec Entr’ouvert pour s’assurer de la faisabilité de ce qui sera proposé.En effet Publik permet un très haut niveau de personnalisation graphique, mais pour autant il s’agit d’un logiciel métier qui impose certaines contraintes pour pouvoir fonctionner correctement.

Entr'ouvert met à disposition un guide de l’intégration graphique dans Publik qui permet de comprendre les possibilités offertes par l’outil et précise le cadre méthodologique à suivre par les équipes de communication et les éventuels prestataires.Il s’agit d’adapter les styles du portail pour retrouver l'univers graphique de la collectivité sans pour autant déstructurer les templates existants dans Publik.Le guide de l’intégration graphique précise les différents livrables qui sont nécessaires à Entr’ouvert pour assurer l’intégration graphique sur Publik. L’intégration technique est donc réalisée par Entr’ouvert. Les maquettes ne sont pas intégrées au pixel près, soit parce que cela peut demander trop de sophistication, soit pour ne pas altérer la feuille de style générique de l'instance.

Exemple d'intégration graphique personnalisée

Simpl'ici Grand ChambéryAffichage desktop / affichage mobile

# Contribuer à Publik¶

* Contenu
* Contribuer à PublikPour démarrerPérimètre de contributionObtenir de l'aideCode de conduiteOù démarrerPublik en localDécouvrir PublikUne première contributionModifier le codeProduire un patchAttacher un patch à un ticketAttendreÉchangerRessources / pour aller plus loin

Contribuer à Publik¶

Pour démarrer¶

Publik est composé de différents modules, par ordre alphabétique :

* Authentic, application de gestion d'identité
* BiJoe, bibliothèque de simplification de requêtes et création de tableaux de bord BI
* Chrono, module de gestion de rendez-vous et évènements
* Combo, application de gestion de contenu
* Fargo, module de porte-documents
* Hobo, module de déploiement et d'orchestration des différentes applications, fournit la gestion du multitenants (via la bibliothèque django-tenant-schemas), assure le partage du paramétrage, etc.
* Passerelle, module d'accès aux multiples sources de données et services
* w.c.s., last but not least, application de conception et de paramétrage de formulaires en ligne.

À côté de ces modules applicatifs, d'autres modules participent à l'ensemble :

* django-mellon amène les fonctionnalités de SSO compatible SAMLv2 aux différentes applications;
* eopayment implémente une couche d'abstraction vers différents systèmes bancaires;
* gadjo fournit le style des interfaces de backoffice;
* publik-base-theme reprend le code, partagé et spécifique, des intégrations graphiques.

Tout cela peut fonctionner en s'appuyant sur ces projets majeurs que sont Python et Django, et bien sûr différents autres modules, ponctuellement utiles, sur des besoins particuliers.

Ce survol rapide des briques étant réalisé, avant de contribuer à l'un ou l'autre module, il est important de noter qu'une des forces de Publik est dans sa capacité d'interactions avec des applications tierces; ainsi, le développement de celles-ci, pour leur ajouter la prise en charge du protocole OpenID Connect pour le SSO, ou leur ajouter des API, contribue également de manière importante à Publik.

Pour explorer plus avant cet aspect:

* la documentation du protocole OIDC :https://openid.net/connect/
* API REST dans les grandes lignes :https://restfulapi.net/

Cela posé, ce document se concentre sur la contribution aux modules de Publik.

Pour faciliter le développement local de ces modules, le projet "publik-devinst" existe.

Périmètre de contribution¶

La contribution ne s'arrête pas au code de Publik et des modules satellites. Vous pouvez également contribuer au développement de connecteurs pour les logiciels métier ou à la rédaction de la documentation. La relecture de correctifs existants est également une contribution très utile.

Obtenir de l'aide¶

Le développement et le support autour de Publik est centralisé via l'outil redmine,https://dev.entrouvert.org, l'inscription est libre, la création d'un compte se fait à l'adressehttps://dev.entrouvert.org/account/registeret bien sûr jamais l'adresse électronique mentionnée ne sera utilisée à d'autres fins.

Code de conduite¶

Dans tous les échanges, une bienséance élémentaire est attendue, soyez poli·e, n'insultez personne.

Où démarrer¶

Publik en local¶

Le meilleur endroit pour développer Publik est son propre ordinateur ; un projet et une documentation dédiée à l'installation d'un environnement de développpement localexiste.

Découvrir Publik¶

Équipé d'une installation locale et du guide de l'administrateur fonctionnel, découvrir ce que Publik peut déjà faire, c'est important parce que beaucoup de choses existent déjà et que les connaitre permet d'ajouter une idée au meilleur endroit, et que cet ajout cadre au mieux avec son environnement.

Une première contribution¶

Important, scratch your own itch. (même si la réalité des contextes sera souvent différente, c'est important à rappeler).

S'il s'agit d'une nouvelle fonctionnalité, il est utile de commencer par ouvrir un ticket, pour qu'elle puisse être validée, guidée, etc.

Ensuite,

Modifier le code¶

* ici les considérations de style et de maintenabilité
 * la présence de tests (et le fait qu'on utilise py.test), etc.

Produire un patch¶

* produire un patch
 ** le relire soi-même

La première ligne du message d'un commit doit être de la forme :petite description du patch (#XXXXX)où XXXX est le numéro de ticket où le développement est suivi (on notera aussi l'absence d'une majuscule sur la première lettre).

Des indications supplémentaires sont possibles dans le message de commit sans formalisme particulier, laisser cependant une ligne vide entre la première ligne formelle et la suite du message.

Attacher un patch à un ticket¶

(et avant ça trouver/créer le ticket ?)

* relire une nouvelle fois le patch
* exécuter une nouvelle fois les tests
* attacher le patch / proposer une branche

Attendre¶

On essaie de regarder rapidement mais pour autant on peut être occupés sur d'autres projets

Échanger¶

Une fois une contribution proposée vient le temps de la relecture.

Il n'y a pas de règles définissant précisément comment les relectures de code doivent se faire, la seule règle est qu'elles doivent se faire : une modification doit être validée par au moins une personne avant de pouvoir être intégrée.

Les relectures ont deux rôles importants :

* le partage de connaissances : le relecteur peut partager les siennes, fournir davantage de contexte sur le module ou le changement attendu, et assurer qu'il n'y ait pas d'effets de bord inconnus de l'auteur. Par ailleurs, les relectures encouragent tout le monde à lire et comprendre le code, pour éviter les parts de code connues ou comprises par une seule personne.

* l'amélioration du code : l'objectif évident de la relecture est d'éviter les bugs mais elles peuvent aussi être un espace de discussion sur les décisions d'architecture; en effet du code qui fonctionne n'est pas nécessairement du code qui pourra évoluer ou être facile à maintenir.

Ressources / pour aller plus loin¶

* Domaines particuliers,Développement d'un connecteurDéveloppement d'une cellule JSON
* Python
* Django

# API pour la gestion des ressources

API pour la gestion des ressources

Les portails permettent d’héberger des fichiers sous forme de ressources, pour des documents, images, à rendre disponibles aux usagers.

Une API est disponible pour définir ces ressources.

Sur/api/assets/set/IDENTFIANT-DE-RESSOURCE,via la méthodeHTTP POST; l’identifiant de la ressource est libre, il est commun d’utiliser un système à préfixe, par exemple "description-poste:345". Si l’identifiant n’est pas connu une nouvelle ressource sera créée, s’il est connu le fichier associé sera remplacé par le nouveau contenu.

Paramètre JSON, corps de la requête

Nom | Description | Obligatoire
-------------------------------
asset | Fichier à poser sur cette ressource; ce paramètre contient des sous-clés :content(contenu du fichier encodé en base64,content_type(type MIME du fichier, optionnel),filename(nom du fichier, optionnel). | Oui

Format de retour

Une réponse JSON est retournée dont les entrées sont les suivantes

Nom | Description | Exemple
---------------------------
err | Succès de l’opération | 0 si ok, 1 en cas d’erreur
url | En cas de succès, l’adresse de la ressource publiée | 

API Portails

* Gestion des ressources
* Paiement en ligne

# Raccordement avec un portail métier (SSO)¶

* Contenu
* Raccordement avec un portail métier (SSO)Authentification uniquePré-requisDescription technique non-exhaustive de l'authentification uniqueDescription technique non-exhaustive de la déconnexion uniqueSLO initié par Publik (Frontchannel Logout)SLO inité par le portail métier (RP initiated Logout)Remontée d'informationPré-requisAffichage de demandes en cours dans le portail-métierAffichage des factures en cours venant du portail-métierRemontée d'autres informations1Dépôt d'une demande

Raccordement avec un portail métier (SSO)¶

Objectif de cette note : rappeler à l'éditeur d'un portail métier les standards SSO et plus précisément les impératifs pour se raccorder à un portail Publik. Ce texte pourra être inclus avec profit par les collectivités directement dans leur CCTP afin qu'il s'impose à l'éditeur métier.Entr'ouvert ne fournit pas de base d'assistance à l'intégration ou à la spécification fonctionnelle d'un SSO. Si souhaité, cette assistance nécessitera un contrat de prestation auprès de la collectivité ou de l'éditeur/intégrateur du portail de l'éditeur métier.

Les fonctionnalités prévus lors d'un raccordement métier seront :

* authentification et déconnexion unique (SSO/SLO)
* appairage de comptes métiers avec les comptes du portail Publik via mise en place d'un pseudonyme
* remontée d'informations par des web-services porté par le portail métier interrogeable via le pseudonyme (uniquement si le SSO est en place)demandes en coursfacturesautres (profil, inscriptions, etc...)

Authentification unique¶

Publik propose un seul mode de raccordement via le protocole OpenID Connect (OIDC), les spécifications à respecter sont :

* http://openid.net/specs/openid-connect-core-1_0.html(pour SSO), avec utilisation du flot "authorization code"
* https://openid.net/specs/openid-connect-rpinitiated-1_0.htmluniquement pour la déconnexion (SLO) initiée depuis le portail métier
* http://openid.net/specs/openid-connect-frontchannel-1_0.htmlpour la déconnexion (SLO) initiée depuis Publik

Les spécifications désignées DOIVENT être respectées à la lettre, le nommage des attributs ("claim") et des scopes peut, par contre, être adapté.

Des implémentations de référence du protocole OpenID Connect pour différents langages et cadriciels sont disponibles surhttps://openid.net/developers/libraries/

Le portail métier et ses éventuels web-services DOIVENT absolument être diffusés via le protocoleHTTPS://.

Une authentification réussie fournit au portail un pseudonyme opaque appelé "sub" dans le jargon OpenID Connect, c'est une chaîne UTF-8 qui devra être conservé dans le schéma de donnée du portail et lié au compte du portail métier. La relation entre ce pseudonyme et les comptes du portail métier pourra être :

* 1-1 (1 compte publik pour 1 compte portail métier),
* 1-n (1 compte Publik vers plusieurs comptes portail métier),
* n-1 (plusieurs comptes Publik pour 1 compte portail métier)
* ou n-n (plusieurs comptes Publik pour plusieurs comptes portail métier).

Ce choix dépendra des usages et de la possibilité pour l'éditeur du portail de gérer les parcours de connexion nécessaire avec par exemple :

* une page de sélection du compte cible à la connexion après SSO,
* ou la possibilité pour les sessions applicatives du portail métier de donner accès à plusieurs comptes en même temps.

Le processus de raccordement

à des comptes existants (nommé aussi appairage), ou de création d'un nouveau compte suite à une authentification unique (SSO) réussie, relève de la seule responsabilité du portail métier mais on notera les cas suivants :

* Portail métier où les comptes sont purement déclaratifs (pur service en ligne) :l'éditeur métier aura la possibilité de raccorder automatiquement le compte Publik à des comptes existant via l'adresse électronique ou de créer le compte automatiquement via les attributs servis au SSO, il sera de son ressort et de la collectivité de déterminer si c'est juridiquement valable, ou si cela nécessite l'envoi d'un courriel de validation.
* Portail métier avec des comptes métiers créés par ailleurs (compte famille, compte association par exemples). Le portail métier devra prévoir un moyen de lier un compte existant dans Publik à un comptes existant sur le portail métier, par exemples (liste non exhaustive) :ajout sur toutes les factures de l'usager d'un identifiant et d'un mot de passe, qui seront demandés lors de l'appairage,envoi d'un code ou d'un lien par SMS ou mail si un canal de communication validé existe déjà avec l'usager via son téléphone mobile ou son email,modération par des agents,raccordement basé sur l'adresse électronique validée sur Publik et sur le portail métier (si jugé suffisant juridiquement et sécuritairement).

Pré-requis¶

L'intégrateur du portail métier devra fournir à un administrateur de la plateforme Publik les informations suivantes :

* la liste des URLs de redirection après SSO :redirect_uris
* la liste des URLs de redirection après SLO initié par le portail métier :post_logout_redirect_uris
* l'URL unique de réception des SLO initié par la plateforme Publik :frontchannel_logout_uri

Attention: si les URLs de redirection ont des domaines différents et l'UUID n'est pas utilisé comme identifiant, penser à définir une URL de secteur.

L'administrateur de la plateforme Publik transmettra à l'intégrateur du portail métier :

* l'identifiant OIDC du portail :client_id
* le secret partagé pour authentification des appels web-service du portail à Publik :client_secret
* l'URL d'autorisation :authorization_endpoint_url(en généralIDP_URL/idp/oidc/authorize/)
* l'URL du web-service de token :token_endpoint_url(en généralIDP_URL/idp/oidc/token/)
* l'URL du web-service du profil utilisateur :userinfo_endpoint_url(en généralIDP_URL/idp/oidc/user_info/)Une page explicitant cette configuration est disponible en ligne, en généralIDP_URL/.well-known/openid-configuration)

Toutes les opérations de connexion ou déconnexion se font via des appels au fournisseur d'identité de la plateforme Publik de la collectivité, on désignera son URL parIDP_URL.

Description technique non-exhaustive de l'authentification unique¶

Une authentification unique débutera comme suit :1. déclenchement de l'authentification sur le portail (appui sur un bouton, appel à une URL particulière, protection de toutes les pages du portail, c'est un point d'implémentation qui relève de l'éditeur du portail métier)

2. redirection du navigateur de l'utilisateur sur l'URL d'autorisation OpenID Connect du fournisseur d'identité de la plateforme Publik:

IDP_URL/idp/oidc/authorize/?client_id=...&...&redirect_uri=...&state=...&...

* le détail de l'appel se trouve dans les spécifications, on notera simplement ici les paramètres importants suivant:client_id: identifie le portail métier auprès du fournisseur d'identité, la valeur de ce champ sera fournit par l'administrateur de la plateforme Publikredirect_uri: URL sur laquelle l'usager sera re-dirigé après authentification, elle devra être déclarée auprès de l'administrateur de la plateforme Publik (plusieurs sont possibles, mais pas de wildcard)state: paramètre opaque retourné au retour sur le portail métier si le SSO échoue ou réussi, il permet au portail de maintenir un état entre la requête de SSO et sa réponse (par exemple URL de retour précise sur le portail, sachant que l'URL de retour au SSO ne peut pas varier énormément)

3. le fournisseur d'identité de la plateforme Publik procède à l'authentification de l'usager, s'il n'est pas déjà authentifié, puis s'il n'a pas encore donné son autorisation lui présente un formulaire lui demandant de confirmer sa volonté de s'authentifier auprès du portail en fournissant un certain nombre d'attributs.

4. le fournisseur d'identité Publik redirige le navigateur de l'utilisateur sur l'URL de retour (ou de callback) déclaré par le portail métier par exemple,

https://portail-metier.collectivite.fr/oidc/callback/?code=xxx&state=yyy

5. le portail métier à la réception de cette requête doit :5.1. éventuellementutiliser le paramètrestatepour retrouver un état conservé (URL de retour sur le portail, identifiant métier de la personne demandé préalablement, jeton transmis par mail ou SMS permettant l'appairage, etc...) en session5.2.appeler le web-servicetoken(IDP_URL/ipd/oidc/token/) du fournisseur d'identité en s'authentifiant avec sonclient_idet sonclient_secret(fourni lui aussi par l'administrateur de la plateforme Publik) permettant d'échangercodecontre unaccess_token; l'access token est un jeton qui permettra d'appeler le web-service fournissant les informations sur l'utilisateur. Le web-servicetokenfournit aussi lesubou identifiant unique de l'utilisateur, c'est cet identifiant qui sert de clé à la liaison entre Publik et le portail-métier. Enfin, le web-servicetokenfournit deux valeursiss(identifiant de l'émetteur) etsid(identifiant de la session) qui doivent être enregistrés dans la session créée sur le portail métier, en vue d'assurer la mécanique de déconnexion (voir plus bas).

5.3.appeler le web-serviceuser-info(IDP_URL/idp/oidc/user_info/) pour obtenir les attributs de l'utilisateur qui lui sont autorisés.

5.4. déterminer si le

sub

est connu

* si lesubest connu, il connecte l'usager à son compte ou un de ses comptes (voir plus haut)
* si lesubest inconnu, il doit lancer un processus d'appairage ou de création de compte, nécessitant des interaction ou pas avec l'utilisateur (cette partie est entièrement à la charge de l'éditeur métier)

Description technique non-exhaustive de la déconnexion unique¶

La déconnexion pourra avoir lieu :

* sur la plateforme Publik, et dans ce cas le portail métier en sera notifié si un SSO a eu lieu vers lui durant la session courante en suivant la spécification "frontchannel logout"
* sur le portail métier, et dans ce cas il DOIT le notifier à la plateforme Publik en suivant la spécification "RP initiated logout"

SLO initié par Publik (Frontchannel Logout)¶

Voirhttp://openid.net/specs/openid-connect-frontchannel-1_0.html#RPLogout

La plateforme Publik procédera à une re-direction sur l'URLfrontchannel_logout_urivia uneiframeinvisible, le portail métier devra procéder à la déconnexion de la session en cours sur toute requête à cette URL et faire en sorte qu'elle ne puisse jamais être mise en cache par le navigateur.

Deux paramètres sont envoyés dans la query-string de l'URLfrontchannel_logout_uri:issetsid. Ce sont ceux qui ont été reçus lors de l'appel au web-service token au début de la création de la session (voir plus haut). Ces deux paramètres permettent de retrouver la session en jeu sur le portail métier, et de la détruire afin d'assurer la déconnexion.

Note : il convient de régler les entêtes de sécurité de l'URL pour que celle-ci soit utilisable dans uneiframe. Notamment il ne faut pas renvoyer d'entête de restrictionX-Frame-Options, ni de limitation viaContent-Security-Policy.

SLO inité par le portail métier (RP initiated Logout)¶

Voirhttps://openid.net/specs/openid-connect-rpinitiated-1_0.html

Le portail-métier devra rediriger le navigateur de l'utilisateur sur l'URLIDP_URL/idp/oidc/logout/, il pourra passer une URL de retour via le paramètrepost_logout_redirect_uri. Cette URL devra être préalablement déclarée auprès de l'administrateur Publik.

Remontée d'information¶

Publik propose un point d'entrée unique pour la gestion de la relation usager, à ce titre il est important que Publik puisse centraliser toutes les informations importantes des portails métiers tiers. Pour cela nous proposons la possibilité d'appeler des web-services portés par les portails métiers en vue d'afficher des informations dans les pages du portail citoyen de Publik.

* tous les web-services devront être servis via HTTPS:// et une authentification HTTP Basic
* tous les web-services devront échanger en utilisant le format JSON en entrée (POST) et en sortie
* en sortie toutes les réponses des web-services devront suivre le formalisme suivant :dans le cas passant :{"err":0,"data":{}}errcontiendra0si tout s'est bien passé, sinon1ou une chaîne de caractère indiquant le type de l'erreur,datacontiendra les données en sortie du web-service dans un dictionnaire JSONdans le cas non passant :{"err":"code-erreur-xxx","err_desc":"",}errcontiendra un code erreur (éventuellement1si rien de plus précis n'est décidé)err_desccontiendra un texte décrivant l'erreur.
* les codes d'erreur HTTP (4xx, 5xx) ne devront être utilisé qu'en cas d'erreur exceptionnelle système (mauvaise URL invalide, erreur interne, etc..) jamais pour retourner une erreur prévue, ceci pour différencier les erreurs techniques des erreurs métiers.
* l'identifiant du compte/profil visé dans le portail ne devra se faire que via lesubmis en place via le SSO, ce sub pourra être passé soit dans le contenu JSON (POST en JSON,{"sub": "xxx"}), soit comme paramètre d'URL (https://portail/web-service/factures/?sub=xxxx)

Affichage de demandes en cours dans le portail-métier¶

Publik étant spécialisé dans la mise en place de télé-services, il y a un formalisme particulier à adopter pour faire remonter des demandes dans le portail Publik.

Ce téléservice devra répondre sur un GET et prendre en entrée lesubcomme paramètre de l'URL (le chemin de l'URL n'est pas imposé). La réponse devra avoir la forme exacte suivante :

GET/api/demandes/?sub=xxx{"err":0,"data":[{"datetime":"2018-03-04 12:34:32","name":"Demande de carte de stationnement","status":"En attente d'information","form_number":"1234","form_status_is_endpoint":false,"url":"https://portail-metier/demandes/1234/","draft":false}]}

Champ | Type | Obligatoire | Description
----------------------------------------
datetime | string, la date au format ISO8601 YYYY-MM-DD HH:MM:SS | Oui | la date de création de la demande
name | string | Oui | le nom du type de demande
form_number | string | Oui | l'identifiant de la demande (numéro ou autre)
url | string | Oui | lien profond vers la demande, si une URL par demande n'est pas disponible le portail métier peut se contenter de renvoyer l'URL d'une page affichant toutes les demandes en cours
status | string | Oui | le statut actuel de la demande, "Nouvelle", "En cours", "En attente d'information", à définir par le portail mais la chaîne doit être présentable directement à l'usager, ce ne doit pas être un code
form_status_is_endpoint | booléen | Non | vrai si le statut de la demande indique qu'elle est terminée
draft | booléen | Non | vrai si la demande est un brouillon

Affichage des factures en cours venant du portail-métier¶

Publik contient nativement un système de remontée et paiement de factures, pour permettre une intégration des factures exposées par un portail métier tiers, il y a là aussi un formalisme particulier à respecter.

Le portail métier DOIT fournir un web-services porté par une URL de base que nous nommeronsBASE_URL, de la formeBASE_URL/invoices/, le dernier élément du chemin est obligatoire.

GET/api/invoices/?sub=xxx{"err":0,"data":[{"id":"939456","label":"restauration août 2015","amount":"37.26","total_amount":"37.26","created":"2015-08-01","pay_limit_date":"2015-09-29","paid":false,"no_online_payment_reason":"litigation","payment_url":"https://portail-metier/factures/934395/pay/","pdf_url":"https//portail-metier/factures/934395/pdf/F20180192.pdf",...(autresinformationssilelogicielbackendendonne)},]}

id | string, libre | Oui | identifiant interne au portail métier de la facture, uniquement pour debug
amount | string, décimal | Oui | montant du reste à payer, nombre décimal formaté avec un point décimal et non une virgule décimale (à l'anglaise)
total_amount | string, décimal | Oui | montant total de la facture, format identique àamount
created | string, date ISO | Oui | date de création de la facture, format ISO8601 YYYY-MM-DD
pay_limit_date | string, date ISO | Oui | date limite de paiement de la facture, date exlue (i.e. à partir de cette date le paiement n'est plus possible), format ISO8601 YYYY-MM-DD
payment_url | string, URL | Non | l'URL pour payer la facture si celle-ci est payable en ligne
pdf_url | string, URL | Non | l'URL vers le PDF de la facture si celle-ci est téléchargeable
non_online_payment_reason | sttring, enum | Non | si payment_url est absent, la raison éventuelle de la non-possibilité de paiement en ligne (contestation, prélèvement, délai dépassé), voir plus loin les valeurs possibles

Les valeurs actuellement possibles pour

no_online_payement_reason

sont :

Valeur | Description
litigation | la facture pose un problème
autobilling | la facture est payée par prélèvement automatique
past_due_date | il n'est plus possible de payer cette facture en ligne car un délai est dépassé

Remontée d'autres informations1¶

Pour tout autre type d'information nous imposons le formalisme générique suivant, en plus des pré-requis donnés plus haut :

* le web-service doit répondre sur un GET
* il doit accepter un seul paramètre à cette url:sub

Ce web-service retournera une description du formatage attendu pour ces donnés selon le formalisme suivant :

* datacontiendra une liste de données qui seront transformés en HTML, chaque donnée est décrite par un dictionnaire et possède un type, ex:{"type":"block","label":"Mes informations familles","content":[...],"edit_url":"https://portail-metier/ma-famille/",}

Type | Description
------------------
block | un bloc composé d'autres éléments, permet de grouper
text | un paragraphe, peut contenir un texte simple, pré-formaté ou formaté en HTML, en utilisant uniquement les balises autorisés dans un noeud <p> du HTML (balises inline,<em/>,<i/>,<b/>), ainsi qu'un lien d'édition (pictogramme stylo dans le coin haut-droit du contenu)
table | un tableau, contenant des lignes qui contiennent soit des entêteheadersoit des cellules de contenutext

Tous les types acceptent les attributs suivants :

* labelqui ajoutera un titre avec le bon niveau d'imbrication avant le contenu,
* idetclass(respectivement une chaîne et une liste de chaînes) permettant de donner des valeurs pour les attributs HTML correspondant, simplifiant l'application d'une feuille de style.

Exemple de présentation d'un profil famille venant d'un portail famille :

{"err":0,"data":{"type":"block","label":"Ma famille","edit_url":"https://portail-famille/ma-famille/edit/","content":[{"type":"text","id":"adresse","label":"Adresse","pre":true,"content":"1 rue du calvaire\nXX100 MAVILLE"},{"type":"text","id":"parent1","class":"parent","label":"Premier parent","html":true,"content":"Jean-Michel <b>DUPOND</b>, né le 12 décembre 1964 à Marseille",},{"type":"text","id":"parent2","class":"parent","label":"Second parent","html":true,"content":"Régine <b>DUPOND</b>, né MARTIN le 12 décembre 1964 à Lyon"}{"type":"block","label":"Enfants","content":[{"type":"text","content":"Kévin DUPOND, 5 ans, né le 22 mars 2013",}]}]}}

Le but de ce formalisme est de laisser à la fois un peu de liberté au portail métier sur les contenus et aussi la liberté pour Publik d'appliquer des feuilles de style aux contenus.

Coté Publik, ces contenus seront présentés via des cellules JSON (cellule associant un web-service JSON avec un template).

1technologie équivalentehttps://github.com/portabletext/portabletext

Dépôt d'une demande¶

Voirhttps://doc-publik.entrouvert.com/dev/echanges-logiciel-de-demandes-metier/en sachant que l'information « sub » peut être envoyée dans la demande si elle doit être reliée à un compte dans le logiciel cible.

# Échanges avec un logiciel de gestion de demandes «métier»¶

Échanges avec un logiciel de gestion de demandes «métier»¶

* Contenu
* Échanges avec un logiciel de gestion de demandes «métier»Principes des échangesCréation d'une demande dans le logiciel tiersAjout de document sur une demande crééeRemontée du statut d'une demande dans PublikCommentaires lors du traitement dans le logiciel tiersSystème en mode «push» : déclenchements par le logiciel tiersRéférentiels, listes de choixUsage des données reçuesFiltrage des éléments d'un référentielListe en mode auto-complétionFormat des réponses en cas d'erreurLorsque Publik envoie des données mal formatéesAutres erreursSécurisation de la communication entre Publik et les webservices du logiciel

Un cas habituel de logiciel tiers est celui qui traite des demandes «métier», par exemple des signalements de problèmes sur la voiries ou des demandes d'intervention concernant la gestion des eaux.

Un tel logiciel peut être connecté avec Publik afin que :

* un usager puisse envoyer une demande (un signalement) vers le logiciel
* par la suite, qu'il puisse être informé de l'avancement de sa demande (prise en charge, traitement en cours, etc.)

Pour mettre en place cette connexion, le logiciel doit exposer un certains nombres de webservices à disposition de Publik. Cette documentation les décrit.

Principes des échanges¶

Publik créé la demande dans le logiciel tiers : les données de la demande et les documents liés si nécessaire.

Publik interroge ensuite le logiciel pour connaître le statut de la demande. Ce statut est éventuellement accompagné d'informations complémentaires.

Selon les informations reçues, Publik informe l'usager de l'avancement de sa demande, par courriel, SMS, message à l'écran ou tout autre moyen.

Publik répète cette interrogation toutes les 6 ou 12h, jusqu'à ce que la demande atteigne un statut «final». Les échanges la concernant s'arrêtent alors.

Création d'une demande dans le logiciel tiers¶

Une fois la demande saisie par l'usager, Publik l'envoie dans le logiciel métier. Pour cela, un appel HTTP POST est fait vers une URL proposée par le logiciel, dans notre exemplehttps://logiciel.tiers/api/creation-nouvelle-demande, mais tout autre format d'URL est possible.

Cet appel POST envoie un dictionnaire JSON, à plat, contenant une suite de clés-valeurs :

POST https://logiciel.tiers/api/creation-nouvelle-demande
Content-Type: application/json
Accept: application/json

{
  "info1": "valeur1",
  "info2": "valeur2",
  "info3": "valeur3",
  "info4": "valeur4",
  ...
}

Noter que le formulaire n'est pas envoyétel quel, tel que saisi par l'usager : certains champs peuvent être modifiés, adaptés, transformés ou normalisés. Par exemple, si l'usager a choisi la ville "Grenoble" dans la liste, c'est son code INSEE qui peut être envoyé dans le logiciel (cf plus bas la gestion des référentiels). C'est donc au logiciel tiers de décrire l'ensemble des données dont il a besoin pour créer une demande : le formulaire Publik sera adapté pour les obtenir de l'usager, et la traduction technique précise sera faire lors de l'appel HTTP POST.

Attention : par défaut pour chaque "valeurX", Publik ne sait envoyer que des chaînes de caractères. Ainsi, si des nombres doivent être transmis, ils le seront sous forme de chaîne de caractère. D'autres types de données peuvent être possibles,  mais il convient alors de vérifier que Publik peut les gérér.

En retour, Publik attend un dictionnaire avec deux entrées :

* err: doit être à 0 (le nombre entier 0) en cas d'absence d'erreur
* data: contient toute les données nécessaires à la suite du traitement. Ça sera en général la référence de la demande créée dans le logiciel, référence qui sera utilisée par Publik pour les communications ultérieures relative à cette demande.

Exemple de réponse attendue :

(... dictionnaire JSON de la demande à créer ...)

200 OK

{
  "err": 0,
  "data": {
     "numero": "42",
     "url": "https://logiciel.tiers/api/demande/42/",
     "statut": "demande créée",
     "datetime": "2021-09-09T15:20:12" 
  }
}

Publik va stocker toutes ces informations dans la demande. L'élément important et nécessaire ici estnumero, qui sera la référence dans le logiciel.

En cas de problème, la réponse sera du même format mais avec unerrà 1 (ou toute autre valeur différente du nombre 0) : lire la section sur la gestion de erreur plus bas dans ce document.

Ajout de document sur une demande créée¶

Une fois la demande créée, Publik peut y joindre les documents. Les documents sont envoyés en dehors de la création de la demande, et un par un : l'objectif est d'éviter tout engorgement, car il s'agit souvent de documents volumineux qui peuvent subir un filtrage par un équipement réseau entre Publik et le logiciel.

Pour chaque document, une requête HTTP POST est effectuée qui contient une référence à la demande créée. Par exemple :

POST https://logiciel.tiers/api/document-pour-demande/42/

{
  "document": {
     "filename": "nomdufichier.pdf",
     "content_type": "application/pdf",
     "content": "Y2VjaSBlc3QgdW4gZXhlbXBsZSBkZSBiYXNlNjQK..." 
  },
  "type": "passeport",
}

Le fichier est sérialisé dans une clédocument. Le contenu du fichier est envoyé danscontentencodé en base64, le nom du fichier estfilenameet son type MIME est danscontent_type. Ce format filename+content_type+content est imposé par Publik et n'est pas modifiable.

Dans l'exemple ci-dessus, untypeest indiqué qui permet au logiciel métier de savoir de quel document il s'agit. D'autres informations peuvent accompagner le document, selon ce qui est nécessaire au logiciel.

Le numéro de la demande pour laquelle le fichier est envoyé (ici 42) peut être indiqué :

* soit dans l'URL du POST, comme dans l'exemple
* soit dans la query-string, on aurait ici /api/document-pour-demande/?demande=42
* soit dans le dictionnaire JSON

En retour de cet appel HTTP POST, Publik attend un dictionnaire avec au moins une entréeerrà 0 (le nombre entier), et éventuellement des informations supplémentaires dans une clédata, par exemple :

200 OK

{
  "err": 0,
  "data": null
}

Comme pour la création de la demande, en cas d'erreur la réponse sera identique mais avecerrà 1 (ou toute autre valeur différente du nombre 0) : voire la section sur la gestion d'erreurs plus bas dans ce document.

Remontée du statut d'une demande dans Publik¶

Une fois la demande créée dans le logiciel, elle va y être traitée.

Publik va régulièrement interroger son statut, par exemple toutes les 6 heures, en effectuant une requête HTTP GET telle que :

GET https://logiciel.tiers/api/statut-demande/42/

Le numéro de la demande peut être dans l'URL comme dans cet exemple, ou dans laquerystringet on aurait alors par exemple /api/statut-demande/?demande=42.

En retour de cet appel HTTP GET, Publik attend un dictionnaire avec deux entréeserretdata: c'est dansdataque sont les informations de statut de la demande.

{
  "err": 0,
  "data": {
     "statut": "traitement-en-cours",                          # code du statut
     "statut_label": "Demande en cours de traitement"          # nom affiché à l'usager
     "commentaire": "Votre demande sera traitée le 15/01/2021"    
  }
}

Pour savoir réagir dans toutes les situations, Publik devra connaîtretousles statuts possibles, pour savoir ce qu'il doit faire de son côté : informer l'usager, clôturer la demande, etc.

Exemples de statuts que l'on peut imaginer (mais c'est le logiciel qui spécifiera la liste exacte selon son «métier») :

* refus
* traitement-en-cours
* cloture

Publik interroge régulièrement le statut de la demande, jusqu'à obtenir un statut final (par exemple "clos" ou "refus"). Le délai entre chaque interrogation est paramétrable dans Publik, c'est souvent 6h ou 12h, et ce pour chaque demande qui n'est pas encore clôturée.

Commentaires lors du traitement dans le logiciel tiers¶

Pendant le traitement de la demande, les agents peuvent éventuellement indiquer des commentaires destinés à l'usager.

Pour faire cela, lors de chaque interrogation du statut de la demande, Publik vérifie si le commentaire a changé. Si oui, alors il le communique à l'usager (par mail, sms, message à l'écran, selon l'action configurée dans Publik).

Système en mode «push» : déclenchements par le logiciel tiers¶

Dans ce qui est décrit ci-dessus, c'est Publik qui vient régulièrement demander au logiciel tiers le statut des demandes en cours. Cela présente plusieurs inconvénients :

* si 300 demandes sont en cours, Publik va faire 300 requêtes
* le délai entre chaque requête sur une demande sera de plusieurs heures (souvent 6 et 12) et ne permet pas donc pas réaction rapide du Publik
* si la demande a changé plusieurs fois de statut dans l'intervalle, Publik peut avoir raté les étapes transitoires cela peut compliquer la compréhension par l'usager de l'avancement de sa demande

Si le nombre de de demandes est important ou si la réactivité doit être grande, c'est plutôt le logiciel tiers qui doit informer de l'avancement des demandes.

Pour cela, le logiciel tiers peut déclencher des appels «_trigger_» sur Publik, sous forme de requête POST, selon ce format :

POST https://demarches.example.net/<slug-demarche>/<numero-de-demande>/jump/trigger/<declencheur>/
{
  "information": ...
}

Cet appel va demander à Publik que la demande de type<slug-demarche>, numéro<numero-de-demande>, effectue un saut nommé<declencheur>. Ce saut est programmé dans Publik, dans le workflow de la démarche concernée. Au passage, le logiciel pourra fournir des informations supplémentaires dans un dictionnaire JSON, qui seront enregistrée dans la demande Publik. Ces données pourront ensuite être exploitées dans le workflow, par exemple pour alimenter une donnée de traitement.

Plus de détails sur ce principe de traitement :https://doc-publik.entrouvert.com/dev/wcs/api-webservices/traitement-d-un-formulaire/

Ce mécanisme impose que le logiciel tiers détermine les URL à appeler. Pour cela, il devra connaître les codes<declencheur>possibles, et les appeler au moment opportun. Il doit aussi avoir reçu<slug-demarche>et<numero-de-demande>dans le JSON de la création de la demande.

Enfin, en mode «push», le logiciel tiers doit tracer (loguer) les appels qu'il effectue. Il doit savoir retenter un appel qui a échoué sur une erreur non fatale (erreur réseau, DNS, code HTTP 5xx, etc.). Il doit savoir lever une alerte en cas d'erreur fatale afin de pouvoir déboguer les problèmes le plus rapidement possible. (Pour information, comme pour toute requête, Publik ne logue que les métadonnées, donc ni le contenu des appels reçus, ni celui de la réponse envoyée.)

Référentiels, listes de choix¶

Le formulaire présenté à l'usager par Publik comporte souvent des champs de type listes. L'usager doit choisir un ou des éléments dans ces listes. Ces choix sont nécessaires à la création de la demande dans le logiciel métier, par exemple le type d'intervention, la nature du signalement, etc.

Le logiciel tiers doit fournir à Publik le contenu de ses listes. Comme exemple on imagine le cas d'un formulaire de demande d'intervention dans une école située sur le territoire d'une agglomération : le formulaire affichera les listes suivantes :

* les villes
* les établissements concernant la ville sélectionnée

Pour chaque liste, Publik interroge un webservice de référentiel, dans cet exemple on aurait :

* GEThttps://logiciel.tiers/api/referentiel/villes
* GEThttps://logiciel.tiers/api/referentiel/etablissements

La réponse à un référentiel est un document JSON de type dictionnaire, avec deux entrées :

* err: un code d'erreur, égal à 0 (le nombre entier 0) quand tout se passe bien (voir en fin de document pour la gestion des erreurs)
* data: la liste des items du référentiel, chaque item étant un dictionnaire contenant :id: identifiant unique de l'itemtext: texte affiché à l'usager, typiquement dans une liste affichée sur le formulairetoute autre information utile à afficher à l'usager ou à envoyer ensuite au logiciel dans la demande

Exemple d'une réponse simple pour la liste des villes, avec justeidettextpour chacune :

GET https://logiciel.tiers/api/referentiel/villes

200 OK

{
  "err": 0,
  "data": [
    {
      "id": "38185",
      "text": "Grenoble",
    },
    {
      "id": "38544",
      "text": "Vienne" 
    }
    (... les autres villes ...)
  ]
}

Mais on peut aussi ajouter d'autres détails sur chaque entrée, par exemple le code postal principal de chaque ville :

200 OK

{
  "err": 0,
  "data": [
    {
      "code_postal": "38000",
    },
    {
      "code_postal": "38200",
    }
    (... autres villes ...)
  ]
}

À noter que les éléments des listes doivent être triés dans l'ordre à afficher aux usagers, Publik ne re-trie pas les listes qu'il reçoit.

Usage des données reçues¶

Publik affiche sur le formulaire la liste des

text

, dans l'exemple ci-dessus ça sera Grenoble, Vienne, etc. Quand l'usager fait son choix dans cette liste, alors Publik dispose de toutes les informations liées à ce choix. Par exemple si l'usager choisi Vienne, Publik connaitra les valeurs suivantes :

* le nom de la ville choisie : "Vienne" (clétext)
* le code INSEE de cette ville : "38544" (cléid)
* et son code postal : "38200" (clécode_postal)

Toutes ces informations sont stockées et donc partie de la demande Publik. Elles peuvent toutes être utilisées pour communiquer ensuite avec le logiciel tiers lors de la création de la demande.

Ainsi, au lieu d'envoyer le nom "Vienne" au logiciel tiers qui devrait retrouver à quelle ville sa correspond dans sa base, Publik peut lui envoyer directement le code INSEE de la ville concernée "38544". Ce partage de référentiels permet donc une communication plus efficace entre Publik et le logiciel.

Filtrage des éléments d'un référentiel¶

Pour certaines listes, on voudra les restreindre en fonction de certains critères. Dans notre exemple on cherche à afficher les établissements d'une ville en particulier. Pour faire cela, Publik ajoute un critère dans l'URL lorsqu'il interroge le référentiel des établissements :GET https://logiciel.tiers/api/referentiel/etablissements?code_ville=38000

La réponse obéit strictement au même format que pour la liste complète des établissements, mais seuls les établissements de la ville concernée sont présents dansdata.

Liste en mode auto-complétion¶

Quand une liste contient plusieurs dizaines d'éléments, elle est trop longue à afficher dans un formulaire. Publik peut en proposer l'affichage en modeauto-complétion: l'usager doit taper quelques lettres et Publik affiche les éléments de la liste qui les contiennent.

Pour cela, le webservice référentiel concerné doit réagir à deux paramètres supplémentaires :qpour filtrer en fonction de ce que l'usager a tapé, etidpour remonter les informations du choix fait par l'usager.

* GET https://logiciel.tiers/api/referentiel/villes?q=gren: doit renvoyer la liste des villes qui contiennentgren, les 4 lettres tapées par l'usager pour sa recherche. Les éléments de la liste doivent être renvoyés selon l'ordre le pertinence (les plus pertinents en premier).

* GET https://logiciel.tiers/api/referentiel/villes?id=38000: doit renvoyer une liste ne contenant qu'un seul élément, à savoir la ville ayant le code 38000

Comme pour une requête filtrée, la réponse obéit strictement au même format que pour la liste complète : un dictionnaire avecerrà 0 (le nombre entier 0) etdataqui contient la liste des éléments.

Format des réponses en cas d'erreur¶

Lorsque Publik envoie des données mal formatées¶

Si les données envoyées par Publik ne sont pas dans un format attendu par le logiciel, celui-ci doit renvoyer une erreur avec le détail des incohérences constatées. Le retour est toujours un dictionnaire JSON avec deux entrée "err" et "data", mais cette foiserrdoit être différent de 0. Attention, erreur fréquente : sierrcontient la chaine de caractère "0" alors ça sera considéré comme un code d'erreur. Il faut utiliser le nombre entier 0.

Le message technique peut être en anglais (par exemple un retour d'erreur SQL) mais il doit permettre à un technicien de comprendre quel champ est en cause, et si possible le type d'erreur constaté (valeur impossible, mauvais type de donnée, …). Le message doit être contenu dans une clé "err_desc" (description de l'erreur). Si c'est utile, un code type d'erreur peut être retourné dans "err_class".

Le code de retour HTTP peut être 400, mais ce n'est pas obligatoire, le plus important est "err" différent de 0.

Par exemple si Publik envoie une demande avec une mauvaise information "foo" :

POST /api/creation-demande
{
  "foo": "trois" 
}

400 Bad Request

{
  "err": 1,
  "data": null,
  "err_desc": "valeur de foo non acceptée, doit être un entier",
  "err_class": "bad-request" 
}

Autres erreurs¶

Pour toutes les autres erreurs, par exemple si une écriture SQL ne se fait pas, ou qu'un autre problème technique survient lors de l'exécution du webservice par le logiciel, ce dernier doit tout de même répondre une réponse JSON (afin que Publik sache qu'il a bien interrogé le webservice mais que celui-ci a eu un problème interne).

Typiquement, il ne fait jamais renvoyer une erreur de type 500 ou une "traceback".

Donc, même en cas d'erreur :

* Le code HTTP de retour doit toujours être 200 (c'est-à-dire « l'échange avec le webservice a eu lieu et a voici sa réponse ») modulo l'exception du code 400 indiquée plus haut en cas de mauvais format d'interrogation du webservice.
* Le contenu du retour doit toujours être un dictionnaire JSON
* La clé "err" dans le JSON doit être différente de 0 ; très fréquemment on indique juste le nombre 1
* La clé "data" peut être vide ou inexistante ; on évitera de la valoriser pour ne pas engendrer de confusion

Pour aider à la compréhension de l'erreur, on peut ajouter :

* une clé "err_desc" qui décrira l'erreur, si possible en français. Elle est destinée à être affichée à un administrateur fonctionnel ou un technicien de Publik qui pourra comprendre le soucis
* une clé "err_class" contenant un identifiant de l'erreur, qui peut être par exemple utilisé pour que Publik gère automatiquement une nouvelle tentative si l'erreur est conjoncturelle (non fatale).

Par exemple en cas d'impossibilité de joindre le SGBD :

GET /api/status-demande?id=42

200 OK

{
  "err": 1,
  "err_desc": "table form_evolutions inaccessible",
  "err_class": "sql-error" 
}

Sécurisation de la communication entre Publik et les webservices du logiciel¶

Tous les échanges auront lieux en HTTPS avec un certificat valide. Au cas où le certificat est émis par une autorité de certification locale, il faut fournir le certificat de l'autorité (clé publique).

L'accès peut être reservé aux adresses IP d'hébergement de l'instance Publik qui effecture les requêtes.

Enfin, une authentification de type HTTP Basic peut être ajoutée en sécurité supplémentaire.

# API pour le paiement en ligne

API pour le paiement en ligne

Cette API, exposée par le module Combo sur le portail usagers, permet d'intégrer des paiements aux démarches. L'API présentée ici est donc destinée à être utilisée depuis des action webservices dans un workflow.

Cette API ne permet pas de piloter des paiements depuis une application tierce.

Création d'un item à payer

Sur/api/lingo/add-basket-itemvia la méthodeHTTP POST.

Paramètres JSON, corps de la requête

Nom | Description | Obligatoire | Exemple
amount | Montant à payer | OUI | 10.05
display_name | Description de l'item à payer | NON | Abonnement au cours de pétanque
url | URL permettant de remonter à la démarche ayant provoqué l'ajout de l'item à payer | NON | {{ form_url }}
capture_date | Date de remise en banque (au format yyyy-mm-dd), remise en banque immédiate si non spécifié | NON | 2019-05-06

Paramètres de la query string de la requête

Certains paramètres doivent être passés dans l'URL de la requête.

NameId | Identifiant de l'utilisateur (NameId ou email doit être spécifié) | NON | {{form_user_name_identifier_0}}
email | Email de l'utilisateur (NameId ou email doit être spécifié) | NON | gerard.lambert@rungis.fr
regie_id | Identifiant ou slug de la régie de paiement (la régie de paiement par défaut sera utilisée si non spécifiée) | NON | la-regie-pas-cher
cancellable | Autorise la suppression de l'item à payer par l'utilisateur (vrai par défaut) | NON | no

Une réponse JSON est retournée dont les entrées sont les suivantes.

result | Succès de l'ajout d'un item à payer | succes
id | Identifiant de l'item à payer | 12
payement_url | URL de paiement de cet item | https://payement-operator/mon-item

Suppression d'un item à payer

Sur/api/lingo/remove-basket-itemvia la méthodeHTTP POST.

basket_item_id | Identifiant de l'item à payer | OUI | 12
notify | Notifier la démarche de la suppression de l'item à payer (faux par défaut) | NON | true

Certains paramètres doivent être passé dans l'URL de de la requête

result | Succès de la suppression de l'item à payer | succes

# Appeler l’API depuis un logiciel ne gérant que les données « plates »

Appeler l’API depuis un logiciel ne gérant que les données « plates »

Aperçu

Certains logiciels n’envoient que des données JSON plates, c’est-à-dire que les données composées que d’un seule niveau, l’imbrication de dictionnaire ou de liste n’étant pas autorisées. C’est par exemple le cas de w.c.s. qui dans sa syntaxe de gabarit Django ne tolère pas l’imbrication de données.

Des données plus complexes peuvent être ré-assemblées par authentic à l’aide du caractère ‘/’ présent dans les clés de dictionnaire JSON transmis à authentic.

Si l’élément à droite du ‘/’ dans la clé est un nombre, alors celui-ci correspond à l’index du sous-élément dans la liste décrite. À l’inverse, s’il s’agit d’une chaîne de caractère quelconque, alors celle-ci correspond à la clé du sous-élément dans le dictionnaire décrit.

Par exemple, l’appel

{
    "a/b/c": "e",
    "b/0": 1,
    "b/1": 2
}

correspond à l’élément composé suivant

{
    "a": {"b": {"c": "e"}},
    "b": [1, 2]
}

Utilisation dans les appels Webservice vers Authentic

Cette syntaxe est tout particulièrement utile pour le remplacement des expressions Python dans les appels Webservice faits vers Authentic.

Par exemple, l’envoi de données composées sous la forme Python (en cours de dépréciation) suivante :

peut être remplacé comme ci-dessous :

API de gestion d’identités et d’accès (authentic)

* Gestion des utilisateursLister et rechercher des utilisateursCréer un utilisateurModifier un utilisateurSupprimer un utilisateurForcer le changement de mot de passe d’un utilisateur
* Gestion des rôlesLister les rôlesCréer un rôleModifier un rôleLister les membres d’un rôleAjouter un utilisateur dans un rôleRetirer un utilisateur d’un rôleGestion en masse des utilisateurs membres d’un rôleSupprimer un rôle
* Gestion des relations d’héritage entre rôlesLister les relations d’héritage d’un rôleAjouter des relations d’héritage entre rôleSupprimer les relations d’héritage d’un rôle
* Autres fonctions
* Approvisionner et déprovisionner les utilisateurs depuis authentic
* Appeler l’API depuis un logiciel ne gérant que les données « plates »

# w.c.s.

w.c.s.

w.c.s. est la brique centrale de Publik, celle qui regroupe :

* Les démarches
* Les listings de traitement de demandes
* Les fabriques de formulaires et wokflows

# Gestion des utilisateurs

Gestion des utilisateurs

Lesutilisateurssont des personnes disposant d'un compte dans Publik, qu'ils soient demandeurs ou destinataires des demandes.

Les comptes sont composés d'un certain nombre de champs paramatérables, obligatoires ou non.

* Lister et rechercher des utilisateurs
* Créer un utilisateur
* Modifier un utilisateur
* Supprimer un utilisateur
* Forcer le changement de mot de passe d’un utilisateur

# Réservation d'un créneau¶

Réservation d'un créneau¶

La réservation d'un créneau s'effectue par un appel à l’adresse/api/agenda/SLUG-DE-LAGENDA/fillslot/IDENTIFIANT-DU-CRENEAU/via la méthodeHTTP POST.

Cette procédure est commune aux agendas de type rendez-vous et évènement, seul le format de l'identifiant du créneau diffère.

Cette adresse est mentionnée dans le champfillslot_urlobtenu en demandant laliste des créneaux disponibles, ce qui évite la plupart du temps d'avoir à la construire manuellement.

Paramètres JSON, corps de la requête¶

La plupart des paramètres sont communs aux deux types d’agenda.

backoffice_url | URL de la démarche effectuant la réservation | {{form_url_backoffice}}
form_url | URL de la demande | {{form_url}}
cancel_callback_url | URL à appeler lors d’une annulation | 
cancel_booking_id | Identifiant de réservation à annuler | 45
count | Nombre de places à réserver | 2
label | Texte arbitraire pour l’affichage en backoffice | {{form_name|safe}}
user_display_label | Texte pour affichage dans export ics | {{form_name|safe}}
user_name | Nom complet l’utilisateur (peut être décomposé et remplacé par user_first_name et user_last_name) | {{form_user_display_name}}
user_first_name | Prénom de l’utilisateur | {{form_user_var_first_name}}
user_last_name | Nom de l’utilisateur | {{form_user_var_last_name}}
user_email | Adresse de courriel de l’utilisateur | {{form_user_email}}
user_phone_number | Numéro de téléphone de l’utilisateur | {{form_user_var_phone}}
user_external_id | Identifiant unique de l’utilisateur | {{form_user_nameid}}
exclude_user | Interdire à l’utilisateur d’avoir plusieurs réservations en même temps | true (false par défaut)
extra_emails | Adresses de courriel supplémentaires où envoyer un rappel | {{form_var_emails_raw}} ou "a@example.com,b@example.com"
extra_phone_numbers | Numéros de téléphone supplémentaires où envoyer un rappel | {{form_var_numbers_raw}} ou "+33122334455,+33122334466"
absence_callback_url | URL à appeler lorsque l’évènement est marqué comme pointé, en cas d’absence | 
presence_callback_url | URL à appeler lorsque l’évènement est marqué comme pointé, en cas de présence | 
sms_counter | Nom optionnel d’un compteur pour les statistiques d’envoi de SMS | 

Il est possible de passer n’importe quel paramètre en plus de ceux ci-dessus : ils seront enregistrés et apparaîtront dans la cléextra_datade l’API qui retourne lesinformations d’une réservation.

Les appels à absence_callback_url et presence_callback_url se feront en POSTant un objet avec les clés user_was_present (booléen), user_check_type_slug (identifiant du motif d’absence), user_check_type_label (libellé du motif d’absence).

Le cancel_booking_id permet de combiner l’annulation d’un créneau et la réservation d’un nouveau (par exemple sur un agenda différent).

Agenda évènement¶

Certains paramètres supplémentaires peuvent être inclus :

bypass_delays | Ne pas prendre en compte les délais de réservation | true (false par défaut)
events | Restreindre la réservation aux évènements passés ou futurs ("future" par défaut) | "future", "past", "all"
force_waiting_list | Forcer le passage en liste d’attente | true

Exemple¶

POST /api/agenda/foo-bar/fillslot/event-slug/

{
    "agenda": {
    "label": "Foo bar",
    "slug": "foo-bar" 
     },
     "api": {
     "accept_url": "http://chrono.dev.publik.love/api/booking/8/accept/",
     "anonymize_url": "http://chrono.dev.publik.love/api/booking/8/anonymize/",
     "booking_url": "http://chrono.dev.publik.love/api/booking/8/",
     "cancel_url": "http://chrono.dev.publik.love/api/booking/8/cancel/",
     "ics_url": "http://chrono.dev.publik.love/api/booking/8/ics/",
     "suspend_url": "http://chrono.dev.publik.love/api/booking/8/suspend/" 
      },
     "booking_id": 8,
     "datetime": "2017-05-21 17:00:00",
     "end_datetime": null,
     "err": 0,
     "in_waiting_list": False,
     "places": {
      "available": 19,
      "full": False,
      "has_waiting_list": False,
      "reserved": 1,
      "total": 20
     }
}

Agenda rendez-vous¶

use_color_for | Libellé auquel associer la couleur d’un rendez-vous dans le backoffice | 

Exemple¶

POST /api/agenda/rdv-pref/fillslot/18:2020-06-16-1000/

{
    "agenda": {
        "label": "rdv pref",
        "slug": "rdv-pref" 
    },
    "api": {
        "anonymize_url": "https://chrono.dev.publik.love/api/booking/50/anonymize/",
        "cancel_url": "https://chrono.dev.publik.love/api/booking/50/cancel/",
        "ics_url": "https://chrono.dev.publik.love/api/booking/50/ics/",
        "suspend_url": "https://chrono.dev.publik.love/api/booking/50/suspend/" 
    },
    "booking_id": 50,
    "datetime": "2020-06-16 10:00:00",
    "desk": {
        "label": "ds",
        "slug": "ds" 
    },
    "duration": 30,
    "end_datetime": "2020-06-16 10:30:00",
    "err": 0,
    "in_waiting_list": false,
    "resources": []
}

Agenda évènement : poser plusieurs réservations¶

Il est possible de réserver plusieurs évènements en une seule fois via un appelPOSTà l’adresse/api/agenda/SLUG-DE-LAGENDA/events/fillslots/.

Par rapport à l’appel classique de réservation d’un évènement, deux paramètres doivent obligatoirement être présents.

user_external_id | Identifiant unique de l’utilisateur. Grâce à cet identifiant, chaque appel aura pour effet de mettre à jour les réservations. | {{form_user_nameid}}
slots | Slugs des évènements à réserver. Une valeur vide aura pour effet d’annuler les réservations de l’utilisateur. | {{form_var_event_raw|join:","}}

Exemple¶

POST /api/agenda/foo-bar/events/fillslots/

{
     "err": 0,
     "booking_count": 3,
     "waiting_list_events": [
     {
        "id": "event-slug",
        "slug": "event-slug",
        ...
     }
     ],
     "cancelled_booking_count": 0
}

Agenda évènement : poser plusieurs réservations sur plusieurs agendas¶

Il est possible de réserver plusieurs évènements qui se trouvent sur des agendas différents via un appelHTTP POSTà l’adresse/api/agendas/events/fillslots/.

Paramètres de l’URL¶

agendas | Slugs des agendas concernés par l’appel. Ils permettent de savoir quelles réservations mettre à jour. | agenda-slug,agenda2-slug,agenda3-slug

slots | Slugs des évènements à réserver. Une valeur vide aura pour effet d’annuler les réservations de l’utilisateur. | agenda-slug@event-slug,agenda2-slug@event-slug

Exemple¶

POST /api/agendas/events/fillslots/?agendas=agenda-slug

{
     "err": 0,
     {
        ...
     }
     ],
}

Agenda évènement : réserver toutes les occurrences d’évènements récurrents¶

Il est possible de réserver un ou plusieurs évènements récurrents, en totalité ou sur une plage temporelle définie, via un appelPOSTà l’adresse/api/agendas/recurring-events/fillslots/.

agendas | Slugs des agendas concernés par l’appel. | agenda-slug,agenda2-slug,agenda3-slug
action | Action à réaliser sur les évènements. | update,bookouunbook
date_start | Réserver seulement les évènements commençant après cette date. | 2021-09-04
date_end | Réserver seulement les évènements commençant avant cette date. | 2022-06-21

slots | Slugs et jours des évènements à réserver. | agenda-slug@event-slug:0,agenda-slug@event2-slug:1 pour réserver le premier évènement tous les lundis et le second tous les mardis.

Exemple¶

POST /api/agendas/recurring-events/fillslots/?agendas=agenda-slug

{
     "err": 0,
     "booking_count": 142,
     "full_events": [
     {
        ...
     }
     ],
}

API Agendas

* Obtenir les créneaux d’un agenda
* Réservation d’un créneau
* Gestion des agendas
* Gestion des évènements
* Gestion des rendez-vous
* Gestion des réservations

# API Portails

Combo est le le logiciel des gestion des portails usagers et des portails agents; il dispose de quelques API accessibles uniquement via des appels webservices réalisés depuis Publik (usuellement le module de démarches), il n’y a actuellement pas de gestion d’accès permettant à une application extérieure d’exploiter ces API.

L'API Web Services est constituée d'appels REST, qui sont effectués en HTTPS pour assurer la sécurité et la confidentialité des échanges. Le format d'échange des données est JSON.

# Infrastructure SCSS

Infrastructure SCSS

Les tableaux ci-dessous reprennent les différents paramètres permettant de
modifier le rendu général des pages.  La première colonne reprend le nom du
paramètre, la deuxième sa description et la troisième la valeur par défaut.

$body-background | Couleur de fond de page | white
--------------------------------------------------
$font-color | Couleur du texte | #333
$link-color | Couleur des liens | #028
$link-hover-color | Couleur au survol des liens | null
$link-decoration | Décoration des liens | none
$link-hover-decoration | Décoration au survol des liens | underline
$font-family | Famille de police du texte | sans-serif
$font-size | Taille du corps du texte. Pour des raison d’accessibilité, il est 
    préférable de laisser l’usager pouvoir choisir sa taille en laissant cette 
    valeur à100%. | 100%
$font-line-height | Hauteur de l’interlignage du corps de texte | 1.4
$width | Largeur maximale de la page | 1000px
$header-background-color | Couleur de fond de l’entête de la page | null
$header-full-width-background | Extension de la couleur de fond de l’entête de la page à la largeur de l’écran
  (plutôt que la largeur du contenu) | true
$header-logo-size | Taille du logo de l’entête. 2 valeurs sont attendues : largeur et hauteur (ex:150px 75px). | null
$show-site-title | Afficher le titre du site. Le titre est masqué par défaut lorsqu’un logo est défini.trueoufalse | null
$footer-background | Couleur de fond du pied de page | #666666
$footer-full-width-background | Extension de la couleur de fond du pied de page à la largeur de l’écran
  (plutôt que la largeur du contenu). | true
$footer-color | Couleur du texte du pied de page | white
$footer-link-color | Couleur des liens du pied de page | $link-color
$border-radius | Taille de l’arrondi à appliquer à différents éléments | null
$sidebar-position | Position de la barre latérale (left/right) | left
$sidebar-width | Largeur de la barre latérale | 300px
$sidebar-max-width | Largeur maximale de la barre latérale, utile dans le cas où la valeur de$sidebar-widthest définie en % | $sidebar-width
$sidebar-min-width | Largeur minimale de la barre latérale, utile dans le cas où la valeur de$sidebar-widthest définie en % | 0
$columns-gutter | Espace (« gouttière ») entre les colonnes des modèles de page. | 20px
$sidebar-columns-gutter | Espace (« gouttière ») entre la barre latérale et les colonnes. | $columns-gutter
$edge-gutter | Espace (« gouttière ») entre le contenu et le bord du navigateur. | legacy
$grid-gutter | Espace (« gouttière ») entre les éléments disposés en grille. | 1rem
$zebra-color | Couleur d’arrière-plan par défaut des zebras | hsla(0, 0%, 0%, 0.06)

Titres

$title-background | Couleur de fond des titres | white
$title-color | Couleur du texte des titres | black
$title-transform | Transformation des caractères des titres | none
$title-font-family | Famille de police pour les titres | $font-family
$title-font-size | Taille de la police des titres | $font-size * 1.1
$title-font-style | Style de la police des titres | normal
$title-padding | Padding des titres | 0.7rem 1rem
$title-weight | Graisse de la police des titres | normal
$title-border-bottom | Bordure pour le bas des titres | 0
$title-border-radius | Taille de l’arrondi à appliquer aux titres | $border-radius
$title-border-top | Bordure pour le haut des titres | 0

Navigation

Ces paramètres contrôlent l’apparence de la barre de navigation.

$nav-background | Couleur de fond | white
$nav-full-width-background | Extension de la couleur de fond de la navigation à la largeur de l’écran
  (plutôt que la largeur du contenu). | false
$nav-color | Couleur du texte | black
$nav-active-color | Couleur "active", utilisée comme valeur par défaut pour des éléments
  ci-dessous | #005EA9
$nav-border-color | Couleur des bordures | $nav-active-color
$nav-border-radius | Taille de l’arrondi de la navigation | $border-radius
$nav-height | Hauteur | 3em
$nav-item-background | Couleur de fond des éléments | transparent
$nav-text-transform | Transformation des caractères des entrées du menu | none
$nav-item-selected-background | Couleur de fond de la page active | $nav-active-color
$nav-item-selected-color | Couleur du texte de la page active | $nav-menu-color
$nav-item-hover-background | Couleur de fond d’un élément au survol | $nav-item-selected-background
$nav-item-hover-color | Couleur du texte d’un élément au survol | $nav-item-selected-color
$nav-item-spacing | Espace entre les éléments | 0px
$nav-font-family | Famille de police de la navigation | null
$nav-font-style | Style de la police de la navigation | null
$nav-font-size | Taille de la police de la navigation | null
$nav-font-weight | Graisse de la police de la navigation | bold
$nav-mobile-menu-background | Couleur de fond du menu en mode mobile | #eee
$nav-mobile-menu-item-color | Couleur des entrées du menu en mode mobile | black
$nav-item-selected-mode | Mode d’affichage du menu sélectionné, soit background pour en changer
  la couleur du fond, soit bottom-border pour ajouter une bordure sous lui. | background
$nav-item-selected-border | Style de la bordure de l’élément sélectionné. | 2px solid $nav-active-color
$nav-item-hover-border | Style de la bordure de l’élément survolé. | $nav-item-selected-border
$nav-after-image | Ajout sous la navigation d’un bandeau avec l’image associée à la page.
  (ne fonctionne pas avec Internet Explorer) | true
$nav-after-image-height | Hauteur de l’éventuel bandeau image. | 300px
$nav-mobile-mode | Rendu de la navigation en mode mobile,nonepour conserver
  le rendu « desktop »,hamburgerpour placer la navigation dans un
  menu « hamburger »,bottom-barpour placer la navigation dans une
  barre en bas d’écran,hiddenpour cacher la navigation.Les paramètres supplémentaires pour le rendubottom-barsont
  détaillés dans la sectionapplication mobile. | hamburger

Moderesponsive

Ces paramètres contrôlent l’apparence de différents éléments quand la largeur
  de la fenêtre est sous une certaine taille.

$mobile-limit | Largeur sous laquelle adopter le style "mobile" | 800px
$mobile-width | Largeur maximale de la page "mobile" | null
$edge-gutter-mobile | Espace (« gouttière ») entre le contenu et le bord du navigateur. | $edge-gutter
$nav-mobile-limit | Largeur sous laquelle adopter la navigation "mobile" | $mobile-limit
$responsive-menu | Apparence du menu de navigation responsive, soit top-to-bottom, soit
  left-to-right | top-to-bottom
$responsive-menu-mask | Affichage d’un masque lorsque le menu mobile est déplié. Valable
  uniquement si$responsive-menu=left-to-right | false
$responsive-menu-mask-background | Couleur de fond du masque du menu mobile | rgba(0, 0, 0, 0.45)
$nav-button-background | Couleur de fond du bouton de navigation (menu hamburger) | $nav-active-color
$nav-button-color | Couleur des traits du bouton de navigation (menu hamburger) | $nav-menu-color
$nav-menu-side | Taille d’un bord du bouton de navigation | 50px
$nav-menu-color | Couleur des lignes dans le menu de navigation | white

Application mobile (PWA)

Ces paramètres contrôlent le rendu de la barre de navigation de bas
  d’écran, présente en mode mobile quand$nav-mobile-modea pour valeurbottom-bar.

$nav-mobile-bottom-bar-height | Hauteur de la barre de navigation en mode mobile. | 64px
----------------------------------------------------------------------------------------
$nav-mobile-bottom-bar-background | Couleur du fond | white
$nav-mobile-bottom-bar-color | Couleur du texte | $nav-color
$nav-mobile-bottom-bar-item-hover-background | Couleur de fond d’un élément au survol | $nav-item-hover-background
$nav-mobile-bottom-bar-item-hover-color | Couleur du texte d’un élément au survol | $nav-item-hover-color
$nav-mobile-bottom-bar-item-selected-background | Couleur de fond de l’élément actif | $nav-item-selected-backgroud
$nav-mobile-bottom-bar-item-selected-color | Couleur du texte de l’élément actif | $nav-item-selected-backgroud
$nav-mobile-bottom-bar-badge-background | Couleur de fond du badge reprenant le nombre de notifications. | #ee2222 (rouge)
$nav-mobile-bottom-bar-badge-color | Couleur du texte du badge reprenant le nombre de notifications. | white
$pwa-nav-limit | Largeur sous laquelle la navigation PWA est visible | $mobile-limit

$form-style | Style général des formulaires, soit « classic », soit « light » pour
  un rendu avec les libellés plus légers et uniquement une bordure basse
  pour les éléments. | classic
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$form-background | Couleur de fond d’une démarche. | $body-background
$form-sidebar-position | Position du code de suivi et des étapes, « left », « right » ou
  « top ». | left
$form-sidebar-width | Largeur de la barre latérale au formulaire | 18.5%
$form-sidebar-gutter | Espace entre la barre latérale et le formulaire | 2%
$form-titlebar-mode | Mode d’affichage du titre de la démarche, soit sur toute la largeur de
  page (page), soit sur la largeur et aligné avec le formulaire
  (form). | page
$form-accent-color | Couleur des cases à cocher et boutons radios natifs sélectionnés | null
$button-background | Couleur de fond des boutons | #37a7da
$button-color | Couleur du texte des boutons | blanc/noir selon $button-background
$button-font-weight | Graisse du texte des boutons | null
$button-border | Style de bordure des boutons | 1px solid transparent
$button-hover-background | Couleur de fond des boutons au survol | $button-background
$button-hover-color | Couleur du texte des boutons au survol | $button-color
$button-border-radius | Taille de l’arrondi à appliquer aux boutons | $border-radius
$button-focus-outline | Style du contour des boutons quand ils sont actifs | $widget-focus-outline
$button-focus-outline-offset | Décalage du contour des boutons quand ils ont actifs | $widget-focus-outline-offset
$widget-background | Couleur de fond des champs de formulaire (texte, liste…) | white
$widget-color | Couleur du texte des champs de formulaire (texte, liste…) | $font-color
$widget-border | Style de bordure des champs de formulaire (texte, liste…) | 1px solid #AAA
$widget-focus-background | Couleur de fond des champs de formulaire lorsqu’ils sont actifs (texte, liste…) | $widget-background
$widget-focus-color | Couleur du texte des champs de formulaire lorsqu’ils sont actifs (texte, liste…) | $widget-color
$widget-focus-border | Style de bordure des champs de formulaire lorsqu’ils sont actifs (texte, liste…) | $widget-border
$widget-focus-outline | Style du contour des champs de formulaire quand ils sont actifs | none
$widget-focus-outline-offset | Décalage du contour des champs de formulaire quand ils sont actifs | 0
$widget-box-shadow | Ombre des champs de formulaire | null
$widget-focus-box-shadow | Ombre des champs de formulaire quand ils sont actifs | none
$widget-border-radius | Taille de l’arrondi à appliquer aux champs de formulaire (texte, liste…) | 0
$widget-padding | Écarts de remplissage (padding) à appliquer aux champs de formulaire
  et aux boutons. | 0.4em 0.7em
$widget-custom-radio-checkbox | Rendu personnalisé des cases à cocher et des boutons radios (plutôt
  que le rendu standard proposé par le navigateur). | false
$widget-custom-radio-checkbox-color | Couleur des cases à cocher et boutons radios (bordure et marqueur)
  quand leur rendu est personnalisé. | $button-background
$widget-custom-radio-checkbox-border-color | Couleur de la bordure des cases à cocher et boutons radios
  quand leur rendu est personnalisé. | $widget-custom-radio-checkbox-color
$widget-custom-radio-checkbox-marker-color | Couleur du marqueur des cases à cocher et des boutons radios
  cochés quand leur rendu est personnalisé. | $widget-custom-radio-checkbox-color
$widget-unique-checkbox-position | Positionnement de la case à cocher d’un champ de type « Case à
  cocher (choix unique); soit « bottom » pour un rendu sous le libellé du
  champ (option par défaut), soit « left » pour un rendu à la gauche du
  libellé. | bottom
$buttons-order | Ordre particulier des boutons. Indiquer les boutons (submit,cancel,previous) dans l’ordre souhaité séparé par des vigules. Ajouter l’option(grow)après l’identifiant d’un bouton va pousser le⋅s bouton⋅s suivant⋅s sur la droite (ex:previous, cancel (grow), submit). | null
$buttons-alignment | Alignement des boutons. Toutes valeurs CSS dejustify-content | null
$buttons-with-icons | Ajoute des icônes aux boutons des formulaires des demandes. | false
$timetable-cell-background | Couleur de fond des créneaux horaires. | transparentize($button-background, 0.8)
$timetable-cell-hover-color | Couleur du texte au survol des créneaux horaires. | $button-color
$timetable-cell-hover-background | Couleur de fond au survol des créneaux horaires. | $button-background
$timetable-cell-selected-color | Couleur du texte du créneau horaire selectionné. | $timetable-cell-hover-color
$timetable-cell-selected-background | Couleur de fond du créneau horaire selectionné. | $timetable-cell-hover-background

Bloc étapes d’une démarche

Ces paramètres contrôlent le rendu du bloc présentant les étapes ou pages d’une démarche.

Le rendu de ce bloc diffère automatiquement en fonction de la taille de l’écran et de la position de lasidebar$form-sidebar-positionpour s’adapter aux différents terminaux :

* rendu mobile :seul l’étape courante est affichée avec une indication du nombre totale d’étapes ;
* rendu horizontal :Les marqueurs d’étapes (chiffres) s’affichent côte à côte et sur plusieurs itemgnes s’il le faut. Seul le label de l’étape en cours s’affiche ;
* rendu vertical :(s’affiche uniquement si la variable$form-sidebar-positiona la valeurleftouright) dispose les étapes les unes au dessous des autres avec chacune leur numéro et leur label

Plusieurs options sont également disponibles pour gérer le rendu dumarqueur d’étape(chiffre).

$wcs-steps-background | Couleur de fond du bloc | transparent
-------------------------------------------------------------
$wcs-steps-spacing | Fixe la taille des espacements entre les différents blocs, mais également entre les marqueurs chiffres et leur label | 0.35rem
$wcs-step-color | Couleur du texte des étapes non courantes | #868686
$wcs-step-current-color | Couleur du texte de l’étape courantes | $primary-color
$wcs-step-background | Couleur de fond des étapes | transparent
$wcs-step-current-background | Couleur de fond de l’étape courante | $wcs-step-background
$wcs-step-border-bottom | Épaisseur et couleur du filet qui sépare les étapes en mode vertical et du filet présent sous les marqueurs en mode horizontal.
          la valeurnonesupprimera les filets. | 1px solid $wcs-step-color
$wcs-step-current-border-bottom | Épaisseur et couleur du filet de l’étape courante.
          Si$wcs-step-border-bottomest ànone, ce filet sera automatiquementnoneégalement. | 3px solid $wcs-step-current-color
$wsc-step-before-piled | Cette option n’est valable qu’en mode vertical et si$wcs-step-backgrounda une valeur différente detransparent.
          Avec la valeurtrue, elle va superposer les étapes passée les unes sur les autres pour gagner de la place. | false
$wcs-step-marker-color | Couleur du chiffre des marqueurs d’étapes non courantes | $wcs-step-color
$wcs-step-current-marker-color | Couleur du chiffre du marqueur d’étape courante | $wcs-step-current-color
$wcs-step-marker-background | Couleur de fond des marqueurs d’étapes non courantes | $wcs-step-background
$wcs-step-current-marker-background | Couleur de fond du marqueur d’étape courante | $wcs-step-current-background
$wcs-step-marker-size | Taille du marqueur. La taille du marquer n’influe pas sur la taille du chiffre | 2.1em
$wcs-step-current-marker-enlarge | Facteur d’agrandissement de la taille du marqueur courant. Une valeur de1.1agrandira le marqueur de 110% | 1
$wcs-step-marker-type | Défini le style des marqueurs. Les marqueurs peuvent être sous forme de carrés (par défaut), de cercles mais également liés entre eux (par une ligne).
          Valeurs possibles:tied,disc,disc tied.
          Il est possible de gérer le rendu de la ligne avec les variables$wcs-step-marker-tie-coloret$wcs-step-marker-tie-width | square
$wcs-step-marker-background-type | Cette option ne fonctionnera que si$wcs-step-marker-backgroundest une couleur pleine.
          Avec la valeurgradient, elle permet de générer un dégradé en fond des marqueurs non courant permettant de souligner visuellement la progression. | solid
$wcs-step-current-label-color | Cette option ne fonctionnera que si$wcs-step-marker-backgroundest une couleur pleine.
          Avec la valeurgradient, elle permet de générer un dégradé en fond des marqueurs non courant permettant de souligner visuellement la progression. | $wcs-step-current-color
$wcs-step-current-color | Couleur du label de l’étape courante | solid
$wcs-steps-small-layout-limit | Fixe la valeur du point de rupture entre le rendu mobile et horizontal | $very-small-limit

Cellules

$cell-background | Couleur de fond des cellules | white
$cell-border | Bordure des cellules | 1px solid #ccc
$cell-border-radius | Taille de l’arrondi des cellules | $border-radius
$cell-color | Couleur du texte des cellules | inherit
$cell-entry-border-color | Bordure des éléments de cellule | 1px solid #ccc
$cell-entry-font-weight | Graisse du texte (lien) d’un élément | normal
$cell-entry-color | Couleur du texte (lien) d’un élément | $link-color
$cell-entry-hover-background | Couleur de fond d’un élément survolé | inherit
$cell-entry-hover-color | Couleur du texte d’un élément survolé | inherit
$cell-entry-hover-effect | Effet au survol des éléments dans les cellules, none pour un fond
  directement uni, left-to-right pour faire apparaitre celui-ci de gauche à
  droit, right-to-left de droite à gauche, top-to-bottom de haut en bas,
  bottom-to-top de bas en haut et middle-to-edges, horizontalement du milieu
  vers les bords. | none
$cell-image-position | Position de l’image qui peut être associée à une cellule « démarches
  d’une catégorie », les valeurs possibles sonttoppour
  avoir l’image en haut de cellule etafter-titlepour avoir
  l’image après le titre de cellule. | after-title
$cell-image-padding | Espace autour de l’image qui peut être associée à une cellule « démarches
  d’une catégorie ». | 0.5rem
$cell-title-cover-border | Détermine si le titre des cellules doit couvrir la bordure | true
$footer-menucell-separator | Style de bordure utilisée comme séparateur vertical entre les entrées
  d’une cellule menu placée dans le pied de page | none

Messages

Options pour paraméter l’affichage des messages. 4 types de messages : succès, information, avertissement, erreur.

$notification-style | Rendu des messages, soit « classic »,
    soit « border-icon » pour un rendu plaçant l’icône en couleur sur un trait
    à gauche, soit « border-bar » pour un rendu avec une bordure et une bande
    de couleur pour l’icône. | classic
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
$notification-icon-size | Taille de l’icône illustrant le message | 1.5remou2rem
$notification-icon-position | Position vertical de l’icône du message. « top » ou « center ». | top

Carrousels

Une cellule menu prendra la forme « carrousel » si elle est définie avec
  « carrousel » comme slug.

$carrousel-height | Hauteur du carrousel | 20rem
------------------------------------------------
$carrousel-text-position | Position du texte des différentes pages; indiqué par 2 valeurs
  séparées par un espace. La première indique le positionnement vertical
  (left,middleouright),
  la seconde le positionnement horizontal (top,middleoubottom). | Exemple :top right
$carrousel-navigation | Détermine si la navigation permettant de passer d’un élément à
  l’autre est affichée. (visible ou none) | visible
$carrousel-navigation-color | Couleur des éléments de navigation (disque et flêches) | $button-color
$carrousel-navigation-bullet-border | Bordure du disque de navigation. | 1px solid white
$carrousel-navigation-bullet-color | Couleur du disque de navigation. | $carrousel-navigation-color
$carrousel-navigation-bullet-size | Taille du disque de navigation. | 10px
$carrousel-arrows | Détermine si les flèches (gauche/droite) permettant de passer d’un
  élément à l’autre sont affichées. (visible ou none) | visible
$carrousel-arrows-color | Couleur des flèches de navigation. | $carrousel-navigation-color
$carrousel-item-mask-color | Couleur du masque qui se superpose à l’image de la diapositive | rgba(0, 0, 0, 0.3)

Tableaux

Ces paramètres contrôlent l’apparence des tableaux sur lesquels la
  classe pk-data-table est appliquée.

$table-caption-color | Couleur du texte de la légende des tableaux | $title-color
---------------------------------------------------------------------------------
$table-caption-side | Position de la légende par rapport au tableau; les valeurs possibles sont
  top (au-dessus) et bottom (en-dessous). | top

Ces paramètres contrôlent l’apparence de l’entête des tableaux sur lesquels la
  classe pk-data-table-headers est appliquée (n’a d’effet que si la classe
  pk-data-table est aussi appliquée).

$table-headers-background | Couleur de fond de l’entête | $title-background
---------------------------------------------------------------------------
$table-headers-color | Couleur du texte de l’entête | $title-color
$table-headers-font-style | Style de la police de l’entête | $title-font-style
$table-headers-font-size | Taille de la police de l’entête | $title-font-size
$table-headers-font-weight | Graisse de la police de l’entête | $title-weight
$table-headers-font-family | Famille de police de l’entête | $title-font-family
$table-headers-text-transform | Transformation des caractères de l’entête | $title-transform

Retour en haut

Bouton permettant de remonter en haut de page. Élément masqué par défaut. Si affiché, il le sera par défaut sous la forme d’un lien en fin de pied de page

$back-top-display | Condition d’affichage du bouton. Valeurs possibles:mobile-only,block,inline,none. | none
------------------------------------------------------------------------------------------------------------
$back-top-icon-character | Caractère UTF-8 de l’icône du bouton. | "\f102"(icone "angle-double-top")
$back-top-icon-size | Taille de l’icône. | 2.5em
$back-top-icon-label-space | Espace entre l’icône et le label du bouton | 0.33em
$back-top-layout-direction | Position de l’icône par rapport au label. Soitvertical: icône au dessus du label, soithorizontal: icône à côté du label | vertical

# Dépréciation des conditions et expressions Python

Dépréciation des conditions et expressions Python

L’utilisation du langage Python pour les conditions et expressions est dépréciée depuis mars 2022 et un retrait de ces fonctionnalités est prévu pour le 31 décembre 2024. L’inventaire des utilisations se trouve repris dans lerapport de dépréciation, accessible depuis la page d’accueil de Publik Studio.

Les sources de données simples sont autotiquement converties en sources de données JSON mais il n’y a pas de transformation automatique pour les utilisations dans des conditions ou expressions, qui demandent une attention humaine au contexte.

Une commande (replace_python) a cependant été développée pour les équipes d’administration système, pour appliquer en masse des transformations qui auraient été collectées depuis un site de test, un catalogue de démarches, etc.

sudo -u wcs /usr/bin/wcs-manage replace_python --all-tenants -f /path/to/python_replacements.json

Le fichier JSON doit avoir la structure suivante, une clé "conditions" pour les remplacements de conditions et une clé "templates" pour les remplacements d’expressions/gabarits :

{"conditions": {"condition python": "condition django",par exemple :"utils.age_in_days (form_var_date) < -60": "form_var_date|age_in_days < -60",(...)},"templates": {"expression python": "gabarit django",par exemple :"str(int(form_var_passages or 0) + 1)": "{{ form_var_passages|default:0|add:1 }}",(...)}}

Il est également possible de pointer à cette commande une URL contenant un document suivant ce format, plutôt qu’un fichier local :

sudo -u wcs /usr/bin/wcs-manage replace_python --all-tenants --url https://example.net/python_replacements.json

# Gestion des évènements¶

Gestion des évènements¶

Obtenir des informations sur un évènement¶

Les informations sur un évènement sont accessibles à l’adresse/api/agenda/SLUG-DE-LAGENDA/status/SLUG-DE-LEVENEMENT/via la méthodeHTTP GET.

Exemple¶

GET /api/agenda/foo-bar/status/event-slug/

{
    "err": 0,
    "id": "event-slug",
    "slug": "event-slug",
    "text": "Event",
    "label": "Event",
    "date": "2020-06-11",
    "datetime": "2020-06-11 10:00:00",
    "description": null,
    "pricing": null,
    "url": null,
    "disabled": true,
    "checked": false,
    "api": {
              "bookings_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/bookings/event-slug/",
              "fillslot_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/fillslot/event-slug/",
              "status_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/status/event-slug/",
              "check_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/check/event-slug/",
    },
    "places": {
        "available": 0,
        "full": true,
        "has_waiting_list": false,
        "reserved": 3,
        "total": 3
    }
}

Quand une liste d'attente existe, le dictionnaireplacesest complété ainsi :

...
    "places": {
        "available": 0,
        "full": true,
        "reserved": 5,
        "total": 30,
        "has_waiting_list": true,
        "waiting_list_total": 10,
        "waiting_list_reserved": 2,
        "waiting_list_available": 8,
        "waiting_list_activated": true
    }

Le booléenwaiting_list_activatedsignifie que la prochaine réservation sera envoyée en liste d'attente.

Obtenir la liste des réservations d’un évènement¶

La liste des réservations d’un utilisateur pour un évènement donné est accessible à l’adresse/api/agenda/SLUG-DE-LAGENDA/bookings/SLUG-DE-LEVENEMENT/via la méthodeHTTP GET. Le paramètreuser_external_idest obligatoire pour désigner l’utilisateur.

Exemple¶

GET /api/agenda/foo-bar/bookings/event-slug/?user_external_id=xxx

{
    "err": 0,
    "data": [
        {"id": 1, "in_waiting_list": true},
        {"id": 2, "in_waiting_list": false}
    ]
}

Agenda évènement : Marquer un évènement comme pointé¶

Un évènement peut être marqué comme pointé via un appel à l’adresse/api/agenda/SLUG-DE-LAGENDA/check/SLUG-DE-LEVENEMENT/via la méthodeHTTP GET.

GET /api/agenda/foo-bar/check/event-slug/

{
    "err": 0,
}

Ajouter un évènement¶

L’ajout d’un évènement s’effectue par un appel à l’adresse/api/agenda/SLUG-DE-LAGENDA/event/via la méthodeHTTP POST.

Deux paramètres doivent obligatoirement être présents.

start_datetime | Date et heure | "2021-10-22 09:45", sous forme de gabarit{{today|date:"Y-m-d"}}{{today|time:"H:i"}}
places | Nombre de places | 10

Paramètres optionnels.

label | Libellé optionnel pour identifier la date | "..."
duration | Durée (en minutes) | 90
publication_datetime | Date·heure de publication | "2021-10-07 10:00", sous forme de gabarit, par exemple{{today|date:"Y-m-d 10:00"}}
waiting_list_places | Places dans la liste d’attente | 3
description | Description | "..."
pricing | Tarif (text) | "2€", "gratuit", ...
url | URL vers un site tiers | "https://doc-publik.entrouvert.com"

Des paramètres supplémentaires permettent de définir un événementrécurrent :

recurrence_days | Jours de la récurrence | "0,1,6" pour lundi, mardi et dimanche
recurrence_week_interval | Répéter toutes X semaines | 1 (défaut), 2 ou 3
recurrence_end_date | Date de fin de la récurrence | "2021-10-20"

Les jours de la récurrence et la date de fin de récurrence doiventêtre fournis pour créer un événement récurrent.

Exemple¶

POST /api/agenda/SLUG-DE-LAGENDA/event/

{
   "data" : {
      "date" : "2021-11-22",
      "datetime" : "2021-11-22 09:45:00",
      "description" : "Une description associée",
      "duration" : 90,
      "id" : "mon-evenement",
      "label" : "Mon événement",
      "pricing" : "2€",
      "recurrence_days" : [
         0,
         1,
         6
      ],
      "recurrence_end_date" : "2021-10-20",
      "recurrence_week_interval" : 2,
      "slug" : "mon-evenement",
      "text" : "Mon événement",
      "url" : "https://doc-publik.entrouvert.com" 
   },
   "err" : 0
}

Mettre à jour un événement¶

Les événements sont modifiables à l’adresse/api/agenda/SLUG-DE-LAGENDA/event/SLUG-DE-LEVENEMENT/via la méthodeHTTP PATCH.

Les paramètres utilisables sont les mêmes que ceux de la requête d’ajout.Il n'y a pas besoin de passer l'ensemble des paramètres, seul les paramètres fournis seront mis à jour.

Exemple¶

PATCH /api/agenda/foo-bar/event/mon-evenement/

(même retour que pour la méthode POST)

Il y a cependant certaines restrictions :

Restrictions sur les événements récurrents¶

On ne peut pas modifier les paramètresstart_datetime,recurrence_daysetrecurrence_week_interval

{
    "err": 1,
    "err_class": "start_datetime cannot be modified because some recurrences have bookings attached to them." 
}

On ne peut pas réduire la date de fin de récurrence(recurrence_end_date) avant un la date de la dernière réservation faite sur l’événement.

{
    "err": 1,
    "err_class": "recurrence_end_date cannot be modified because bookings exist after this date." 
}

Restrictions sur les occurrences des événements récurrents¶

Les champspublication_datetimeet ceux définissant larécurrence (recurrence_days,recurrence_week_intervaletrecurrence_end_date) ne sont pas modifiables sur les récurrencesd’événements récurrents.

{
    "err": 1,
    "err_class": "publication_datetime cannot be modified on an event recurrence" 
}

# Gestion des rendez-vous¶

Gestion des rendez-vous¶

Obtenir les types de rendez-vous¶

Les types de rendez-vous d’un agenda sont accessibles à l’adresse/api/agenda/SLUG-DE-LAGENDA/meetings/via la méthodeHTTP GET.

Exemple¶

GET /api/agenda/rdvs-autre/meetings/

{
    "data": [
        {
            "api": {
                "datetimes_url": "https://chrono.dev.publik.love/api/agenda/rdvs-autre/meetings/base/datetimes/" 
            },
            "duration": 30,
            "id": "base",
            "text": "base" 
        },
        {
            "api": {
                "datetimes_url": "https://chrono.dev.publik.love/api/agenda/rdvs-autre/meetings/court/datetimes/" 
            },
            "duration": 15,
            "id": "court",
            "text": "court" 
        }
    ]
}

De manière analogue, il est possible de préciser un type de rendez-vous et d’obtenir les informations le concernant via un appel à l’adresse/api/agenda/SLUG-DE-LAGENDA/meetings/SLUG-DU-TYPE-DE-RDV/.

GET /api/agenda/rdvs-autre/meetings/base/

{
    "data": {
        "api": {
            "datetimes_url": "https://chrono.dev.publik.love/api/agenda/rdvs-autre/meetings/base/datetimes/" 
        },
        "duration": 30,
        "id": "base",
        "text": "base" 
    }
}

Obtenir les guichets¶

Les guichets d’un agenda sont accessibles à l’adresse/api/agenda/SLUG-DE-LAGENDA/desks/via la méthodeHTTP GET.

Exemple¶

GET /api/agenda/rdvs-autre/desks/

{
    "data": [
        {
            "id": "aa",
            "text": "aa" 
        },
        {
            "id": "bb",
            "text": "bb" 
        },
        {
            "id": "guichet-1",
            "text": "Guichet 1" 
        }
    ]
}

Obtenir les resources¶

Les ressources d’un agenda sont accessibles à l’adresse/api/agenda/SLUG-DE-LAGENDA/resources/via la méthodeHTTP GET.

Exemple¶

GET /api/agenda/rdvs-autre/resources/

{
    "data": [
        {
            "id": "resource-1",
            "text": "Resource 1",
        "description": "Foo bar resource 1" 
        },
        {
            "id": "resource-2",
            "text": "Resource 2",
        "description": "Foo bar resource 2" 
        }
    ]
}

Une version à jour est disponible

[ici](https://doc-publik.entrouvert.com/dev/api-agendas/)

.

# Installation d'un environnement de développement local¶

* Contenu
* Installation d'un environnement de développement localPré-requis systèmeInstaller PublikAdministration systèmeServicesUtilisation du serveur web UWSGICommandes d'administrationMettre à jour son installationMise à jour complèteMises à jour cibléesMise à jour du certificat TLSMise à jour du code sourceUtilisation avancéePersonnalisation de l'installationDéploiement d'un nouveau tenantSuppression des tenantsSuppression complète de l'environnement de développementDNSMot de passe sudoObtenir de l'aide

Installation d'un environnement de développement local¶

Ce document explique le fonctionnement d'un ensemble de playbooksAnsiblequi installe les sources et configure, pour le développement local, l'ensemble desbriques de Publik. Pour mieux comprendre le rôle de toutes ces briques, lisez le documentprésentation générale.

Pré-requis système¶

* Debian bookworm (stable) ou trixie (testing) : l'environnement de développement Publik fonctionne sous Debian. Si vous utilisez un autre système nous conseillons vivement d'installer une machine virtuelle ou un conteneur Linux sous Debian.
* L'utilisateur linux utilisé doit êtresudoermais ne doit pas être l'utilisateurroot.

Installer les logiciels suivant :

* Ansible (une version supérieure ou égale à 2.5 est nécessaire)
* Git
* GNU Make

Via la commande :

sudo apt install git ansible make

Installer Publik¶

Ne pas lancer les commandes en tant qu'utilisateur root

* Clonez le dépôt git publik-devinst :

git clone https://git.entrouvert.org/publik-devinst.git && cd publik-devinst

* lancer l'installation de Publik

make install

Votre mot de passe sudo vous sera demandé, voiricisi vous voulez savoir pourquoi.

* lancer le déploiement d'un tenant

make deploy

Vous avez maintenant une instance de Publik fonctionnelle qui tourne sur votre machine, accessible à cette adresse :https://combo.dev.publik.love/.

Utilisateur :admin@localhostMot de passe :admin

* Après votre première authentification, si vous ne voyez pas d'entrée "Formulaires" et/ou "Workflows" dans le menu, une visite sur la page suivante devrait résoudre le problème :https://wcs.dev.publik.love/login.
* Sur les pages "Fabrique de formulaires" vous sera indiqué la nécessité de "définir desrôles", rendez vous surhttps://authentic.dev.publik.love/manage/roles/pour créer un rôle.

Administration système¶

* Le code source des briques de publik sont disponibles dans dépôts git dans/home/utilisateur/src
* Les briques sont installés dans unvirtualenvpython qui se trouve ici/home/utilisateur/envs/publik-env-py3

Services¶

Les services qui constituent votre instance de Publik sont les suivants :

* authentic-multitenant
* bijoe
* chrono
* combo
* fargo
* hobo
* hobo-agent
* passerelle
* wcs
* welco

Les services sont démarrés automatiquement et sont gérés parsupervisord.Pour faire des opérations sur un service :

sudo supervisorctl {start|status|stop} django:nomduservice

Par exemple :

sudo supervisorctl {start|status|stop} django:passerelle

Les logs des service sont disponibles dans/var/log/nomduservice/stderr.loget/var/log/nomduservice/stdout.log

Pour faire tourner un service dans une console :

sudo supervisorctl stop django:nomduservice
/home/utilisateur/envs/publik-env-py3/bin/nomduservice-server

sudo supervisorctl stop django:passerelle
/home/utilisateur/envs/publik-env-py3/bin/passerelle-server

Des directives de configuration django peuvent être ajoutés dans un ou plusieurs fichiers python, à placer dans/home/utilisateur/.config/publik/settings/nomduservice/settings.d/.En revanche ne pas modifier/home/utilisateur/.config/publik/settings/nomduservice/settings.py, fichier de configuration principal d'un service, qui sera écrasé lors d'une mise à jour de votre installation.

Utilisation du serveur web UWSGI¶

Les services lancés par défaut utilisent le serveur de développement django. Il est possible d'utiliser un "vrai" serveur web à la place, uwsgi. D'abord couper le service de base, puis lancer le service uwsgi :

sudo supervisorctl start uwsgi:nomduservice-uwsgi

sudo supervisorctl stop uwsgi:passerelle-uwsgi

Pour visualiser la journalisation de UWSGI :

sudo supervisorctl tail -f  uwsgi:nomduservice-uwsgi stderr

Pour un service donné le fichier de configuration uwsgi se trouve dans/home/utilisateur/.config/publik/settings/nomduservice/uwsgi.ini.La personnalisation de cette configuration peut être faite dans un fichier/home/utilisateur/.config/publik/settings/nomduservice/setttings.d/uwsgi-local.ini.

Commandes d'administration¶

Les commandes d'administration de chaque service sont disponibles dans/home/utilisateur/envs/publik-env-py3/bin/nomduservice-manage, par exemple :

/home/utilisateur/envs/publik-env-py3/bin/hobo-manage

Mettre à jour son installation¶

D'abord mettre à jour l'utilitaire d'installation :

cd ~/src/publik-devinst && git pull

Mise à jour complète¶

Via la même commande que lors de l'installation.

Attention si vous avez fait des commits dans la branche main d'une des briques de Publik et que ces commits ne sont pas poussés sur nos dépôts, ces commits seront perdus.En revanche si vous avez travaillé dans vos propres branches, tout va bien se passer.

Cette opération pouvant prendre un certain temps, nous proposons des raccourcis plus rapides si vous désirez effectuer uniquement les taches suivantes : mise à jour du certificat TLS ou mise jour du code source.

Mises à jour ciblées¶

Les mise à jour ciblées décrites ci-dessous sont déjà effectuées lors d'une mise à jour complète. Une mise à jour complète pouvant prendre un temps conséquent, nous proposons quelques raccourcis.

Mise à jour du certificat TLS¶

Nous proposons un certificat wildcard qui couvre tous les noms *.dev.publik.love, ce certificat est téléchargé à l'installation.Notez qu'il s'agit d'un certificat LetsEncrypt, donc sa durée de vie n'est pas longue, trois mois au mieux. Si la version que vous aviez téléchargé a expiré,vous pouvez télécharger un certificat valide avec la commande :

make renew-certificate

Mise à jour du code source¶

Seront également effectuées quelques opérations afférentes à la mise jour du code source.

make upgrade

Utilisation avancée¶

Personnalisation de l'installation¶

Le comportement de l'installation peut être personnalisé :

* en copiant le fichier local-inventory.yml.example vers un fichier local-inventory.yml
* puis en éditant local-inventory.yml et en modifiant les variables de configuration qui s'y trouvent

Les variables les plus communément utilisées sont les suivantes :

* clean_venv (true/false) : suppression de l'environnement virtuel python  existant avant l'installation (par défaut false)
* compile_theme (true/false) : compilation des thèmes graphiques (par défaut true)
* delete_all_tenants (true/false) : lors de la suppression des tenants, suppression de tous les tenants (par défaut true, si false, suppression des tenants déclarés uniquement)
* git_ssh (true/false) : cloner les dépôts git en utilisant le protocole ssh au lieu de https (par défaut false)
* src_dir : le répertoire dans lequel les dépots git seront clonés (par défaut /home/nom-de-votre-utilisateur/src)

Déploiement d'un nouveau tenant¶

D'abord, notez que chaque brique de Publik tourne dans un serveur web sécurisé indépendant et fonctionne selon une architecturemulti-tenants.Chaque tenant (une instance locale d'une brique Publik) est identifié par son URL.Vous pouvez déployer de nouveaux tenants en plus de ceux déployés par défaut.Pour ce faire, dans le fichier local-inventory.yml décrit précédemment, dé-commenter les lignes de la sectiontenants_confet remplacercustomnamepar un nom de votre choix,puis invoquer la commande de déploiement de tenant.

(qu'il faut parfois lancer plusieurs fois et être patient en raison des messages RabbitMQ qu ne sont pas consommés ni ackés à cette date)

Pendant l’exécution, vous pouvez lire les logs de votre "agent" hobo qui configure vos tenants :

sudo tail -f /var/log/hobo-agent/stderr.log

Suppression des tenants¶

Par défaut tous les tenants seront supprimés

make delete

Pour supprimer uniquement certains tenants, il faut que l'optiondelete_all_tenantssoit mise àfalse. Seront alors supprimés uniquement les tenants déclarés dans la sectiontenants_confde votre configuration.

Suppression complète de l'environnement de développement¶

make clean

DNS¶

La zonedev.publik.loveest configurée pour que tous les nomsfoobar.dev.publik.loveaient comme adresse 127.0.0.1, c'est-à-dire votre machine.

Pour vérifier que la résolution DNS fonctionne :

$ host foobar.dev.publik.love
foobar.dev.publik.love has address 127.0.0.1

Si le serveur DNS de votre fournisseur d'accès est menteur (par exemple chez l'opérateur Free) alors ça ne marchera pas. Utilisez plutôt un service de DNS correct tel queQuad9(9.9.9.9) ou installez un résolveur chez vous.

Si vous travaillez sans connexion Internet, ou si vous utilisez un autre nom de domaine, vous pouvez éditer votre fichier/etc/hosts, par exemple :

# à poser à la fin de /etc/hosts, à adapter selon les noms des sites que vous avez choisi de déployer
127.0.0.1  agent-combo.dev.publik.love authentic.dev.publik.love bijoe.dev.publik.love chrono.dev.publik.love combo.dev.publik.love fargo.dev.publik.love hobo.dev.publik.love  passerelle.dev.publik.love wcs.dev.publik.love

Mot de passe sudo¶

Une série de fichiers à l'extérieur du répertoire personnel doivent être modifiés, c'est la raison pour laquelle l'accès "sudo" est demandé lors de l'installation.Voici le liste des actions effectuées par le playbook qui nécessitent les droits administrateurs :

* installation de paquets systèmes (la liste est disponible au début du fichierroles/base/tasks/main.yml)
* création d'un rôle et de bases de données postgres
* création de fichiers de configuration supervisord dans/etc/supervisor/conf.d
* création de fichiers de configuration nginx dans/etc/nginx/sites-enabledet/etc/nginx/sites-available
* création d'une clé secrète pour chaque service de publik (/etc/nomduservice/secret)
* création d'un répertoire dans/var/lib/nomduservicepour chaque application
* création d'un répertoire de log dans/var/log/nomduservicepour chaque application

En cas de problème, vous pouvez obtenir de l'aide en créant une demande de support ici :https://dev.entrouvert.org/projects/publik-devinst/issues, merci d'y décrire aussi précisément que possible le problème rencontré.

Si l'installation échoue, joindre à votre demande un fichier de log de l'installation lancée en mode verbeuse.Un tel fichier peut par exemple s'intitulerdebug.loget s'obtenir en lançant l'installation de la façon suivante :

make install > debug.log

Si l'installation déroule jusqu'à la fin mais que l'instance obtenue vous semble non fonctionnelle, merci de joindre des captures d'écran, etc.

# Gestion des agendas¶

Gestion des agendas¶

Lister les agendas¶

La liste des agendas est accessible à l’adresse/api/agenda/via la méthodeHTTP GET.

Paramètres¶

q | Filtrer les agendas selon leur slug. | q=piscineretournera les agendas dont les slugs sont « piscine_1 » et « first_piscine » mais pas « salle_des_fetes ».
category | Filtrer les agendas selon leur catégorie. | 
with_open_events | Exclure les agendas qui n’ont pas d’évènements ouverts. | with_open_events=truene retournera que les agendas ayant des évènements ouverts.

Exemple¶

GET /api/agenda/

{
  "data": [
      {
      "text": "Un agenda",
      "id": "un-agenda",
      "slug": "un-agenda",
      "kind": "events",
      "minimal_booking_delay": 1,
      "minimal_booking_delay_in_working_days": False,
      "maximal_booking_delay": 56,
      "edit_role" : "Agent",
      "view_role" : "Agent",
      "category" : "une-categorie",
      "absence_reasons": [
          {"id": "reason-1", "slug": "reason-1", "text": "Reason 1", "label": "Reason 1"},
          {"id": "reason-2", "slug": "reason-2", "text": "Reason 2", "label": "Reason 2"},
      ],
      "api": {
          "datetimes_url": "http://chrono.dev.publik.love/api/agenda/un-agenda/datetimes/",
          "fillslots_url": "http://chrono.dev.publik.love/api/agenda/un-agenda/fillslots/",
      },
      },
      {
      "text": "Un autre agenda",
      "id": "un-autre-agenda",
      "slug": "un-autre-agenda",
      "kind": "meetings",
      "resources": [
          {"id": "resource-1", "text": "Resource 1", "description": "Foo bar Resource 1"},
          {"id": "resource-2", "text": "Resource 2", "description": "Foo bar Resource 2"},
      ],
      "api": {
          "meetings_url": "http://chrono.dev.publik.love/api/agenda/un-autre-agenda/meetings/",
          "desks_url": "http://chrono.dev.publik.love/api/agenda/un-autre-agenda/desks/",
          "resources_url": "http://chrono.dev.publik.love/api/agenda/un-autre-agenda/resources/",
          "fillslots_url": "http://chrono.dev.publik.love/api/agenda/un-autre-agenda/fillslots/",
      },
      },
}

Ajouter un agenda¶

L’ajout d’un agenda s’effectue par un appel à l’adresse/api/agenda/via la méthodeHTTP POST.

Cette procédure est commune aux agendas de type rendez-vous et évènement.

slug | Identifiant pour adresse URL | "mon-agenda"
label | Libellé | "Mon Agenda"

La plupart des paramètres optionnels sont communs aux deux types d’agenda.

kind | Type de l’agenda | "events" (défaut), "meetings" ou "virtual"
minimal_booking_delay | Nombre de jours minimal (borne incluse) pour réserver | 1
maximal_booking_delay | Nombre de jours maximal (borne exclue) pour réserver | 56
anonymize_delay | Délai d’anonymisation (en jours) | 30
edit_role | Rôle d’édition | "Administateur fonctionnel"
view_role | Rôle de visualisation | "Administateur fonctionnel"
category | Slug de la catégorie de l'agenda | "une-category"

Les paramètres qui encadrent la période de réservation sont mieux décritsici

Un paramètre supplémentaire peut être inclut sur les agendas évènements :

minimal_booking_delay_in_working_days | Délai de réservation minimal en jours ouvrés (booléen) | false (défaut), true

Exemple¶

POST /api/agenda/

{
   "data" : [
      {
         "api" : {
            "datetimes_url" : "https://chrono.dev.publik.love/api/agenda/mon-agenda/datetimes/",
            "fillslots_url" : "https://chrono.dev.publik.love/api/agenda/mon-agenda/fillslots/" 
         },
         "category" : "une-categorie",
         "edit_role" : "Administrateur fonctionnel",
         "id" : "mon-agenda",
         "kind" : "events",
         "maximal_booking_delay" : 56,
         "minimal_booking_delay" : 1,
         "minimal_booking_delay_in_working_days" : true,
         "slug" : "mon-agenda",
         "text" : "Mon Agenda",
         "view_role" : "Administrateur fonctionnel" 
      }
   ],
   "err" : 0
}

Mettre à jour un agenda¶

Les agendas sont modifiables à l’adresse/api/agenda/SLUG-DE-LAGENDA/via la méthodeHTTP PATCH.

Les paramètres utilisables sont les mêmes que ceux de la requête d’ajout, à l'exception du paramètrekind, car le type d'un agenda existant ne peut pas être modifié.Il n'y a pas besoin de passer l'ensemble des paramètres, seul les paramètres fournis seront mis à jour.

Exemple¶

PATCH /api/agenda/agenda-evenement/

Dupliquer un agenda¶

Un agenda peut être dupliqué via l’adresse/api/agenda/SLUG-DE-LAGENDA/duplicate/via la méthodeHTTPPOST.

Nom | Description | Remarque
label | Libellé pour l’agenda dupliqué
slug | Slug pour l’agenda dupliqué | Si le slug n’est pas mentionné il sera créé automatiquement sur base du libellé

Exemple¶

POST /api/agenda/agenda-evenement/duplicate/
{
  "label": "Nouveau libellé",
  "slug": "identifiant-personnalise" 
}

→
{
  "data": {
    "id": "identifiant-personnalise",
    "slug": "identifiant-personnalise",
    "text": "Nouveau libellé",
    "kind": "events",
    "minimal_booking_delay": 1,
    … (autres attributs de paramétrage) …
    "api": {
      "datetimes_url": "https://…/api/agenda/identifiant-personnalise/datetimes/",
      "backoffice_url": "https://…/manage/agendas/NUM/" 
    },
  }
}

Obtenir des informations sur un agenda¶

Les informations de paramétrage d’un agenda sont accessibles à l’adresse/api/agenda/SLUG-DE-LAGENDA/via la méthodeHTTP GET.

Exemple¶

GET /api/agenda/agenda-evenement/

{
    "data": {
        "api": {
            "datetimes_url": "https://chrono.dev.publik.love/api/agenda/agenda-evenement/datetimes/",
            "fillslots_url": "https://chrono.dev.publik.love/api/agenda/agenda-evenement/fillslots/" 
        },
        "id": "agenda-evenement",
        "kind": "events",
        "maximal_booking_delay": 56,
        "minimal_booking_delay": 1,
        "minimal_booking_delay_in_working_days": True,
        "slug": "agenda-evenement",
        "text": "Agenda Evenement",
        "edit_role" : "Agent",
        "view_role" : "Agent",
        "category" : "une-categorie",
    }
}

Supprimer un agenda¶

La suppression d'un agenda s'effectue via un appel à l’adresse/api/agenda/SLUG-DE-LAGENDA/via la méthodeHTTP DELETE.L'appel échouera si l'agenda contient des réservation actives.

Exemple¶

DELETE /api/agenda/agenda-evenement/

{
    "err": 0,
}

# Approvisionner et déprovisionner les utilisateurs depuis authentic

Approvisionner et déprovisionner les utilisateurs depuis authentic

Authentic peut être utilisé comme référentiel des utilisateurs et servir à approvisionner et à dé-provisionner des applications tierces.

Les applications interrogent authentic pour ces opérations. Authentic ne fait pas de notification des évènements sur les utilisateurs aux applications.

S'il n'est pas possible d'intégrer cela directement dans une application, une application en charge d'interroger authentic et de répercuter les changements dans la base utilisateur de l'application cible est à développer.

Approvisionnement

Pour l'approvisionnement, un script est à développer pour consulter les utilisateurs d'authentic en utilisant le WebService/api/users/et ensuite apporter les modifications dans la base utilisateurs de l'application cible.

Ce script est à exécuter à intervalle régulier. La durée de l'intervalle dépend du besoin de synchronisation des comptes.

Afin de ne lister que les utilisateurs créés et modifiés le paramètremodified__gtdoit être passé en paramètre de la requête de lecture avec pour valeur la date de dernière syncrhonisation.

Dé-provisionnement

Pour dé-provisionner, un script est à développer pour consulter les utilisateurs d'authentic qui n'existent plus en utilisant le WebService de « Tests d'existence des comptes en masse »/api/users/synchronization/et ensuite apporter les modifications dans la base utilisateurs de l'application cible (suppression, désactivation, archivage, etc.).

Exemple de script

Ci-dessous un exemple de script réalisant un approvisionnement et un dé-provisionnement depuis authentic sur un autre autentic.

# authentic2 - Authentic2 synchronization script example
# Copyright (C) 2017-2018  Entr'ouvert
#
# This program is free software: you can redistribute it and/or modify it
# under the terms of the GNU Affero General Public License as published
# by the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program.  If not, see.

import datetime
import requests
import sys

import django.db
from django.conf import settings
from django.contrib.auth import get_user_model
from django.core.management.base import BaseCommand

from authentic2_auth_oidc.models import OIDCProvider, OIDCAccount

class Command(BaseCommand):
    def handle(self, *args, **options):
        User = get_user_model()

        verbose = int(options['verbosity']) > 0

        a2_provider = OIDCProvider.objects.get(slug='a2_source')
        auth = (a2_provider.client_id, a2_provider.client_secret)

        # check all existing users
        def chunks(l, n):
            for i in range(0, len(l), n):
                yield l[i:i + n]

        url = settings.A2_SOURCE_API_BASE_URL + 'users/synchronization/'
        unknown_uuids = []
        for accounts in chunks(OIDCAccount.objects.filter(provider=a2_provider), 100):
            subs = [x.sub for x in accounts]
            resp = requests.post(url, json={'known_uuids': subs}, auth=auth)
            unknown_uuids.extend(resp.json().get('unknown_uuids'))

        User.objects.filter(oidc_account__sub__in=unknown_uuids).delete()

        # update recently modified users
        url = settings.A2_SOURCE_API_BASE_URL + 'users/?modified__gt=%s' % (
                datetime.datetime.now() - datetime.timedelta(seconds=120)).strftime('%Y-%m-%dT%H:%M:%S')
        resp = requests.get(url, auth=auth)
        for user_dict in resp.json()['results']:
            try:
                user = User.objects.get(email=user_dict['email'])
            except User.DoesNotExist:
                continue
            for claim in a2_provider.claim_mappings.all():
                setattr(user, claim.attribute, user_dict.get(claim.claim))
                try:
                    setattr(user.attributes, claim.attribute, user_dict.get(claim.claim))
                except AttributeError:
                    pass
            user.save()

# Développement d’un connecteur avec Passerelle¶

* Contenu
* Développement d’un connecteur avec PasserelleDémarrageCode du connecteurInstallation du connecteurActivation du connecteurMigration initialeInstanciation du connecteurEndpointsJournalisationAutorisations d'accèsDocumentationParamétrages supplémentairesExécution de tâches planifiées (cron)Suivi de la disponibilitéTâches asynchronesTests unitairesAu-delà

Développement d’un connecteur avec Passerelle¶

Passerelle est le module en charge de l'interconnexion de Publik vers les API d'autres applications; cette documentation concerne le développement d'un connecteur en utilisant Passerelle et s'appuie pour cela surl'installation d'un environnement de développement local.

⚠ Passerelle n'est pas l'unique possibilité d'interconnexion de Publik vers les autres applications, tous les échanges de Publik se font en HTTPS, cela permet à toute application tierce, en exploitant les actions, formats et API de Publik, d'interopérer directement avec celui-ci, sans connecteur particulier, ou à travers d'un module indépendant (ESB, proxy d'API externe, etc.).

Démarrage¶

Il faut d'abord créer un répertoire qui contiendra le connecteur, appelons ce répertoire "passerelle-test" (mkdir passerelle-test).

Dans ce répertoire (cd passerelle-test), il faut créer le module Python qui correspondra au connecteur, ici les tirets ne sont pas autorisés dans les noms, appelons-le donc "passerelle_test", un module Python est un simple répertoire (mkdir passerelle_test) contenant un fichier__init__.py, qui peut être vide (touch passerelle_test/__init__.py).

On a alors cette arborescence de fichier :

passerelle-test/
passerelle-test/passerelle_test/
passerelle-test/passerelle_test/__init__.py   # fichier vide

Code du connecteur¶

Le code du connecteur se crée dans le fichierpasserelle-test/passerelle_test/models.py:

passerelle-test/passerelle_test/__init__.py
passerelle-test/passerelle_test/models.py      # code du connecteur

Ce fichiermodels.pydécrit unmodèle Django, dans Passerelle on le fait hériter du modèle "BaseResource" qui contient déjà tout ce qui structure un connecteur :

frompasserelle.base.modelsimportBaseResourceclassTestConnector(BaseResource):category='Divers'classMeta:verbose_name='Connecteur de test'

La catégorie où se range le connecteur se définit dans l'attributcategoryet le nom du connecteur va lui dans les métadonnées du modèle.

Très clairement ce connecteur ne fait encore rien mais il y a désormais assez de code pour l'instancier ; mais avant cela, il faut qu'il puisse être installé sur le système.

Installation du connecteur¶

Pour que le connecteur puisse être installé, il faut créer un fichiersetup.pyà la racine du projet (i.e. directement dans le répertoirepasserelle_test/); son contenu peut être minimal :

#! /usr/bin/env pythonfromsetuptoolsimportsetup,find_packagessetup(name='passerelle-test',author='John Doe',author_email='john.doe@example.net',url='http://example.net/',packages=find_packages(),)

Le code d'installation exige la présence d'un fichier de documentation README, il doit donc être créé pour l'occasion (il peut très bien être vide,touch README).

À ce stade, l'arborescence du projet est donc celle-ci :

passerelle-test/README
passerelle-test/setup.py
passerelle-test/passerelle_test/models.py

Il est maintenant possible de lancer l'installation, en mode développement pour permettre à nos modifications ultérieures d'être prises en compte sans demander à chaque fois une réinstallation (/home/utilisateur/envs/publik-env-py3/bin/python setup.py develop@).

$ /home/utilisateur/envs/publik-env-py3/bin/python setup.py develop
running develop
running egg_info
writing passerelle_test.egg-info/PKG-INFO
writing top-level names to passerelle_test.egg-info/top_level.txt
writing dependency_links to passerelle_test.egg-info/dependency_links.txt
reading manifest file 'passerelle_test.egg-info/SOURCES.txt'
writing manifest file 'passerelle_test.egg-info/SOURCES.txt'
running build_ext
Creating /home/utilisateur/envs/publik-env-py3/lib/python3.7/site-packages/dist-packages/passerelle-test.egg-link (link to .)
Adding passerelle-test 0.0.0 to easy-install.pth file

Installed /home/test/passerelle-test
Processing dependencies for passerelle-test==0.0.0
Finished processing dependencies for passerelle-test==0.0.0

Activation du connecteur¶

Le connecteur a désormais tout le nécessaire pour être activé, il reste juste à le déclarer dans la configuration, pour cela il faut créer un fichier/home/utilisateur/.config/publik/settings/passerelle/settings.d/connecteur.py(ou tout autre nom en.py), avec ces deux lignes :

INSTALLED_APPS += ('passerelle_test',)
TENANT_APPS += ('passerelle_test',)

Migration initiale¶

Django dispose d'un système automatique demigration des donnéesdes différents modèles, qui facilite grandement les mises à jour. Dans la majorité des cas ce système est automatique, il est temps de l'initialiser en créant une première migration :

$ /home/utilisateur/envs/publik-env-py3/bin/passerelle-manage --forceuser makemigrations passerelle_test
Migrations for 'passerelle_test':
  0001_initial.py:
    - Create model TestConnector

Si cette commande échoue sur un problème d'accès, vérifiez que votre utilisateur est bien dans le groupe "passerelle".

Instanciation du connecteur¶

Passerelle peut désormais être rédémarré,sudo supervisorctl restart passerelle. Et voilà, il est maintenant possible de naviguer, le nouveau connecteur apparaîtra dans la liste des connecteurs disponibles.  Créons-le et donnons-lui le nom de "démo", sa première instance devient disponible :https://passerelle.dev.publik.love/passerelle-test/demo/

Endpoints¶

C'est ici que tout commence car bien sûr un connecteur vide n'a aucun intérêt, il faut désormais lui ajouter le code qui le rendra utile, sous forme de "endpoints", les URL qui seront utilisées pour exposer les webservices.

Il faut importer le code permettant de déclarer les endpointsfrom passerelle.utils.api import endpointen haut du fichiermodels.py, et ensuite, dans le modèleTestConnectorcréé plus haut, nous pouvons alors déclarer un premier endpoint,

classTestConnector(BaseResource):[…]@endpoint()definfo(self,request):return{'hello':'world'}

Redémarrons Passerelle pour que le code soit pris en compte (sudo supervisorctl restart passerelle) et voilà, accéder à l'URL du endpoint,https://passerelle.dev.publik.love/passerelle-test/demo/inforetourne la donnée au format JSON :

{"hello":"world"}

Il est aussi possible pour un endpoint d'attendre des paramètres, déclarons donc un deuxième endpoint, faisant l'addition de nombres entiers et retournant le résultat :

classTestConnector(BaseResource):[…]@endpoint()defaddition(self,request,a,b):return{'total':int(a)+int(b)}

Visiterhttps://passerelle.dev.publik.love/passerelle-test/demo/addition?a=2&b=3retournera au format JSON :

{"total":5}

Journalisation¶

Passerelle suit la configuration de la journalisation établie au niveau de Django (cfJournalisationdans la documentation officielle de Django) et ajoute à celle-ci une journalisation interne, consultable depuis la page de visualisation du connecteur.

L'objetloggerd'un connecteur dispose des méthodes standards de log (debug, info, warning, critical, error, fatal); ainsi un connecteur opérant une division pourrait logguer au niveau "debug" toutes les demandes et logguer au niveau "error" les divisions par zéro :

classTestConnector(BaseResource):[…]@endpoint()defdivision(self,request,a,b):self.logger.debug('division de %s par %s',a,b)try:return{'result':int(a)/int(b)}exceptZeroDivisionError:self.logger.error('division par zéro')raise

Autorisations d'accès¶

Par défaut les endpoints ajoutés sont privés, limités à une permissioncan_access, un tableau de gestion des autorisations d'accès est automatiquement inclus à la page de gestion du connecteur.

can_accessest le nom par défaut utilisé pour limiter l'accès mais il est possible d'augmenter la granularité des autorisations, on pourrait ainsi avoir un autre endpoint dont l'accès serait différencié :

classTestConnector(BaseResource):[…]_can_compute_description='Accès aux fonctions de calcul'@endpoint(perm='can_compute')defaddition(self,request,a,b):return{'total':int(a)+int(b)}

À noter également l'ajout dans la classe d'un attribut_can_compute_description, qui servira au niveau de l'interface à fournir une description pour cette autorisation d'accès.

Il est possible de créer des accès ouverts, en passantOPENcomme permission d’accès :

classTestConnector(BaseResource):[…]@endpoint(perm='OPEN')definfo(self,request):return{'hello':'world'}

Documentation¶

Pour renforcer l'utilité de la page d'information d'un connecteur il est important de documenter le connecteur et ses différents endpoints.  Le connecteur en lui-même peut être décrit en ajoutant un attributapi_description.  Pour les endpoints, cela passe par l'ajout de paramètres à la déclaration@endpoint:

classTestConnector(BaseResource):[…]api_description="Ce connecteur propose quelques opération arithmétiques élémentaires."@endpoint(description='Addition de deux nombres entiers',parameters={'a':{'description':'Un premier nombre','example_value':'7'},'b':{'description':'Un second nombre','example_value':'2'}})defaddition(self,request,a,b):return{'total':int(a)+int(b)}

Dansdescriptionse place donc une description général de l'endpoint et dansparametersse place les informations sur les différents paramètres autorisés par l'appel, pour chacun d'eux une description et une valeur qui sera reprise en exemple peuvent être fournies.

Paramétrages supplémentaires¶

À l'instanciation d'un connecteur quelques paramètres sont demandés, un titre et une description, ainsi que le niveau de journalisation souhaité.  Il est possible d'ajouter d'autres paramètres, il faut pour cela ajouter de nouveaux attributs à la classe du connecteur. Comme noté en début de document cette classe correspond à unmodèle Django, il s'agit ainsi d'y ajouter deschamps.

Comme exemple, créons un connecteur dont le rôle sera de nous renseigner sur le bon état de fonctionnement, ou pas, d'une adresse, en faisant en sorte que cette adresse soit un paramètre supplémentaire du connecteur.

Il faut donc ajouter un attribut au modèle,url = models.URLField(...)et cette information sera par la suite disponible dansself.url:

importrequestsfrompasserelle.base.modelsimportBaseResourceclassTestConnector(BaseResource):category='Divers'url=models.URLField('URL',default='http://www.example.net')classMeta:verbose_name='Connecteur de test'@endpoint(description='Teste une adresse')defup(self,request):try:response=self.requests.get(self.url)response.raise_for_status()exceptrequests.RequestException:return{'result':'%s est en panne'%self.url}return{'result':'%s est ok'%self.url}

Comme le modèle se trouve modifié, il est nécessaire de prévoir pour la base de données une migration qui ajoutera une colonne pour ce champurl,/home/utilisateur/envs/publik-env-py3/bin/passerelle-manage --forceuser makemigrations passerelle_test.  Cette migration sera exécutée automatiquement au redémarrage de Passerelle, qui est donc nécessaire à cette étape.

Note :self.requestsutilisé ici est un wrapper léger au-dessus du moduleRequests, qui ajoute une journalisation et une expiration automatique des appels.

Exécution de tâches planifiées (cron)¶

Un connecteur peut souhaiter exécuter des tâches de manière régulière, comme par exemple lancer une synchronisation avec un référentiel externe.  Passerelle prend en charge quatre fréquences, une tâche peut être planifiée pour s'exécuter toutes les heures, tous les jours, toutes les semaines ou tous les mois.  Pour ce faire il faut définir dans le connecteur une fonction avec la tâche à exécuter et la nommer selon la fréquence (hourly / daily / weekly / monthly).

frompasserelle.base.modelsimportBaseResourceclassTestConnector(BaseResource):[…]defhourly(self):pass# code exécuté toutes les heures

⚠ Les tâches planifiées sont lancées automatiquement dans un environnement de production debian mais pas dans un environnement de développement local.

Pour lancer manuellement une tâche planifiée dans un environnement de développement local (remplacer hourly pas daily / weekly / monthly selon le cas) :

/home/utilisateur/envs/publik-env-py3/bin/passerelle-manage tenant_command cron -d passerelle.dev.publik.love hourly

Suivi de la disponibilité¶

Dans le prolongement des tâches planifiées se trouve le suivi de la disponibilité.  Un connecteur peut régulièrement (toutes les cinq minutes) interroger le service distant pour s'assurer de sa disponibilité et marquer celui-ci si jamais ce n'était pas le cas.

Il suffit pour assurer cela de définir une méthodecheck_status, le service sera considéré indisponible quand la méthode lèvera une exception.

frompasserelle.base.modelsimportBaseResourceclassTestConnector(BaseResource):[…]defcheck_status(self):response=self.requests.get('http://example.net')response.raise_for_status()

⚠ Le suivi de disponibilité est lancé automatiquement dans un environnement de production debian mais pas dans un environnement de développement local.

Pour lancer manuellement le suivi de disponibilité dans un environnement de développement local :

/home/utilisateur/envs/publik-env-py3/bin/passerelle-manage tenant_command cron -d passerelle.dev.publik.love availability

Tâches asynchrones¶

Les tâches planifiées s'exécutent de manière régulière, il peut également être utile d'exécuter des tâches de manière ponctuelle, par exemple pour transférer en tâche de fond un fichier important. La méthodeadd_jobpermet d'ajouter une tâche de fond, qui sera exécutée après la requête.

classTestConnector(BaseResource):[…]@endpoint(description='Transfert de données',parameters={'src':{'description':'Source'},'dst':{'description':'Destination'},})deftransfert(self,request,src,dst):self.add_job('execution_transfert',src=src,dst=dst)return{'msg':'Transfert planifié','err':0}defexecution_transfert(self,src,dst):# ici obtenir les données depuis la source puis les transférer à destinationpass

La méthodeadd_jobprend comme paramètres le nom de la méthode à exécuter puis une série libre de paramètres nommés, qui seront utilisés lors de l'exécution.

Quand des tâches existent, la page du connecteur les reprend dans un tableau.

⚠ Dans un environnement de développement local, les tâche asynchrones ne sont exécutées que si passerelle utilise le serveurUWSGI.

Tests unitaires¶

Ils sont indispensables pour dormir tranquille, ils se créent dans un nouveau répertoire,testset utilisent les modulespytest,pytest-djangoetdjango-webtest(ces trois modules doivent donc être installés).

Il y a d'abord à définir un fichiertests/settings.pyparticulier, qui assurera la présence du connecteur :

INSTALLED_APPS+=('passerelle_test',)

Puis ensuite créer un fichier pour les tests en eux-mêmes, ça peut êtretests/test_connecteur.py, il commencera par les imports des modules souhaités puis la définition des objets qui seront ensuite utiles.

# -*- coding: utf-8 -*-importpytestimportdjango_webtestfromdjango.contrib.contenttypes.modelsimportContentTypefrompasserelle_test.modelsimportTestConnectorfrompasserelle.base.modelsimportApiUser,AccessRight@pytest.fixturedefapp(request):# création de l'application Djangoreturndjango_webtest.DjangoTestApp()@pytest.fixturedefconnector(db):# création du connecteur et ouverture de la permission "can_access" sans authentification.connector=TestConnector.objects.create(slug='test')api=ApiUser.objects.create(username='all',keytype='',key='')obj_type=ContentType.objects.get_for_model(connector)AccessRight.objects.create(codename='can_access',apiuser=api,resource_type=obj_type,resource_pk=connector.pk)returnconnector

Vient alors enfin le temps de tester le connecteur, pour un test sur la fonction d'addition :

deftest_addition(app,connector):resp=app.get('/passerelle-test/test/addition?a=5&b=3')assertresp.json.get('total')==8

Les tests s'exécutent ensuite via la commandepy.test, en pointant le fichiersettings.pycréé spécialement :

$ DJANGO_SETTINGS_MODULE=passerelle.settings PASSERELLE_SETTINGS_FILE=tests/settings.py py.test 
======================================= test session starts =======================================
platform linux2 -- Python 2.7.14+, pytest-3.3.1, ...
cachedir: .cache
Django settings: passerelle.settings (from environment variable)
rootdir: ..., inifile:
plugins: ...
collected 1 item

tests/test_connecteur.py::test_addition PASSED                                              [100%]

==================================== 1 passed in 0.48 seconds =====================================

Au-delà¶

* gestion des POST.
* pattern sur les endpoints.
* Squelette HTML de description du connecteur.

# Paramétrage w.c.s.

Paramétrage w.c.s.

Pour l'administration système,w.c.s.dispose d'une série de paramètres concernant son fonctionnement et son intégration dans le système d'information.

# API Agendas

Chrono est un logiciel de gestion d'agendas, séparés en deux type : rendez-vous et évènement. Certains points d'accès sont commun, d'autres sont réservées à un type d'agenda précis. Le terme générique de « créneau » est utilisé à la fois pour parler des évènements réservables et des rendez-vous disponibles.

Ces API sont accessibles uniquement via des appels webservices réalisés depuis Publik (usuellement le module de démarches), il n’y a actuellement pas de gestion d’accès permettant à une application extérieure d’exploiter ces API.

L'API Web Services est constituée d'appels REST, qui sont idéalement effectués en HTTPS, pour assurer la sécurité et la confidentialité des échanges. Le format d'échange des données est JSON.

# Développement d'une cellule alimentée par JSON¶

* Contenu
* Développement d'une cellule alimentée par JSONDéfinition de la celluleRendu de la celluleParamétrage de la celluleRécupération de données supplémentairesGestion du cacheUtilisation du profil de l'usager

Développement d'une cellule alimentée par JSON¶

Il est possible d'ajouter de nouveaux types de cellules pour afficher des données disponibles au format JSON, ces cellules apparaitront ensuite dans la liste des cellules disponibles, sous un sous-titre "Extra".

Définition de la cellule¶

Dans lessettings(soit lesettings.pydu projet, soit lesettings.jsondu domaine), la définition se fait dans une cléJSON_CELL_TYPES.

Par exemple, pour la création d'une cellule affichant la qualité de l'air, tirant ses données du site strasmap.eu, la cellule serait annoncée de la sorte :

"JSON_CELL_TYPES": {"info-atmo": {"name":"Info Atmo","url":"http://strasmap.eu/remote.amf.json/Atmo.status"}
}

Rendu de la cellule¶

La suite du travail consiste à fournir un gabarit de rendu pour ces données, ceux-ci se placent dans le répertoire templates/combo/json/ du site (e.g. /var/lib/combo/tenants/www.example.net/templates/combo/json/), avec comme nom l'identifiant de la cellule + ".html", ex:info-atmo.html.

Il s'agit d'un gabarit Django, ils sont documentés en détails à cette adresse :https://docs.djangoproject.com/fr/1.11/ref/templates/

Les données qui auront été téléchargées sont mises à disposition dans la variablejson; ainsi, avec le fichier téléchargé ayant cette structure :

{"cdate":"mer. 06 déc. 2017","calltime":10000,"datatime":"mer. 06 déc. 2017 à 09:49","pdate":"jeu. 07 déc. 2017","ctext":"Pour ce mercredi, le maintien d'un temps calme accompagné de brumes matinales favorisera une nouvelle augmentation des niveaux de particules.
              La qualité de l'air devrait être bonne à moyenne en plaine avec des indices 4 à 5 sur 10 en particules alors qu'elle restera très bonne sur les reliefs
              avec des indices 2 en ozone.","ptext":"Jeudi, sous un temps sec et lumineux, les émissions de polluants seront bien dispersées par le vent. En plaine, les particules devraient se contenir
              à des indices 4 sur 10 maximum et sur les reliefs l'ozone dominera à des indices 2-3. C'est donc une bonne voire très bonne qualité de l'air qui
              sera attendue sur le territoire alsacien.","s": [
      {"lc":"bonne","cp":"#9AEB00","cc":"#9AEB00","sp":"status_4","lp":"bonne","sc":"status_4","id":67043},
      {"lc":"bonne","cp":"#1AD100","cc":"#1AD100","sp":"status_3","lp":"bonne","sc":"status_3","id":67049},
      […]

La cellule doit trouver la ligne correspondant au code INSEE de la commune pour en afficher la qualité de l'air puis afficher l'information textuelle générale.

{% for city in json.s %}
  {% if city.id == 67482 %}<h2>Qualité de l'air : {{city.lc}}</h2>{% endif %}
{% endfor %}<p>{{json.ctext}}</p><p><small>{{json.datatime}}</small></p>

Paramétrage de la cellule¶

Plutôt qu'avoir le code INSEE en dur dans le gabarit, il est possible de rendre la cellule paramétrable en faisant évoluer sa déclaration vers la suivante :

"JSON_CELL_TYPES": {"info-atmo": {"name":"Info Atmo","url":"http://strasmap.eu/remote.amf.json/Atmo.status","form": [
      {"varname":"commune","type":"string","label":"Commune"}
    ]
  }
}

Les paramètres sont accessibles dans la variableparameters, le gabarit devient donc :

  {% ifequal parameters.commune city.id|stringformat:"s" %}<h2>Qualité de l'air : {{city.lc}}</h2>{% endif %}

Dans cet exemple précis, le code INSEE de la commune se trouve sous forme d'entier et non de chaine de caractères, la condition utilise donc{% ifequal %}etcity.idest converti en chaine par le filtrestringformat:"s".

Récupération de données supplémentaires¶

La suite, c'est se dire qu'il est plus facile d'écrire Oberschaeffolsheim que 67350 et permettre le paramétrage de la cellule via un nom de commune plutôt que le code INSEE. Pour réaliser ça la cellule va faire appel à une deuxième source de données, qui contient la correspondance entre les codes et les noms.

La déclaration de la cellule ajoute donc cette seconde URL :

"JSON_CELL_TYPES": {"info-atmo": {"name":"Info Atmo","url":"http://strasmap.eu/remote.amf.json/Atmo.status","additional-data": [
      {"key":"communes","url":"http://strasmap.eu/remote.amf.json/Atmo.geometry"},
    ],"form": [
    ]
  }
}

Le contenu qui en sera récupéré sera mis à disposition dans la variablecommunes(spécifiées dans l'attributkey). Il s'agit donc de boucler pour trouver le code de la commune selon son nom puis de reprendre comme précédemment sur la recherche de la qualité associée au code :

{% for commune in communes.s %}
  {% if commune.ln == parameters.commune %}
    {% for q in json.s %}
      {% ifequal commune.id q.id|stringformat:"s" %}<h2>Qualité de l'air : {{q.lc}}</h2>{% endifequal %}
    {% endfor %}
  {% endif %}

Gestion du cache¶

Par défaut les données téléchargées sont conservées en cache 60 secondes, on peut augmenter cette durée en accompagnant les URL d'une clécache_duration:

"JSON_CELL_TYPES": {"info-atmo": {"name":"Info Atmo","url":"http://strasmap.eu/remote.amf.json/Atmo.status","cache_duration":3600,"additional-data": [
      {"key":"communes","url":"http://strasmap.eu/remote.amf.json/Atmo.geometry","cache_duration":86400},
    ]
  }
}

Utilisation du profil de l'usager¶

Pour revenir au contenu, plutôt qu'un paramétrage de la commune, on pourrait vouloir la récupérer depuis le profil de l'usager, on passerait alors par un appel supplémentaire, vers l'API du fournisseur d'identités :

      {"key":"user","url":"{{ idp_url }}api/users/{{ user_nameid }}/"}
    ]
  }
}

On voit ici la possibilité d'utiliser des variables dans les URL,{{ idp_url }}reprendra l'adresse du fournisseur d'identités et{{ user_nameid }}contiendra l'identifiant unique de l'usager.

Plutôt que comparer avec le paramètre de la cellule, la comparaison peut donc se faire par rapport au profil de l'usager, pour lequel on suppose qu'il contiendra sa commune dans le champcity:

  {% if commune.ln == user.city %}
  {% endif %}

# Gestion des réservations¶

Gestion des réservations¶

Obtenir la liste des réservations d’un utilisateur¶

La liste des réservations d’un utilisateur est accessible à l’adresse/api/bookings/via la méthodeHTTP GET.

user_external_id | Identifiant unique de l’utilisateur (obligatoire). | {{form_user_nameid}}
agenda | Restreindre les réservations à un agenda. | Slug d’un agenda.
category | Restreindre les réservations à une catégorie d’agenda. | Slug d’une catégorie.
date_start | Filtrer les réservations selon leur date de début. | 2021-09-15
date_end | Filtrer les réservations selon leur date de fin. | 2021-09-20

Exemple¶

GET /api/bookings/?user_external_id=xxx

{
    "err": 0,
    "data": [
    {
        "id": 4,
        "in_waiting_list": false,
        "user_was_present": true,
        "user_absence_reason": "",
        "extra_data": null
    },
    {
        "id": 11,
        "user_was_present": null,
    }
    ]
}

Obtenir des informations sur une réservation¶

Les informations sur une réservation sont accessibles à l’adresse/api/booking/ID-DE-LA-RESERVATION/via la méthodeHTTP GET.

Exemple¶

GET /api/booking/4/

{
    "err": 0,
    "data": {
    "booking_id": 4,
    "in_waiting_list": false,
    "user_was_present": true,
    "user_absence_reason": "",
    "extra_data": null
    }
}

Erreur : réservation annulée¶

{
    "err": 1,
    "err_class": "booking is cancelled" 
}

Mettre à jour les informations sur une réservation¶

Les informations sur une réservation sont modifiables à l’adresse/api/booking/ID-DE-LA-RESERVATION/via la méthodeHTTP PATCH.

user_was_present | Information de pointage témoignant de la présence de l’utilisateur. | true
user_absence_reason | Motif d’absence | 

Il est possible de passer n’importe quel paramètre en plus de ceux ci-dessus : ils seront enregistrés et apparaîtront dans la cléextra_datade l’API qui retourne lesinformations d’une réservation.

Exemple¶

PATCH /api/booking/4/

{
    "err": 0,
}

{
    "err": 1,
}

Erreur : réservation en liste d’attente¶

{
    "err": 3,
    "err_class": "booking is in waiting list" 
}

Erreur : l’évènement est marqué comme déjà pointé¶

{
    "err": 5,
    "err_class": "event is marked as checked" 
}

Annuler une réservation¶

Il est possible d’annuler une réservation grâce à un appel à l’adresse/api/booking/ID-DE-LA-RESERVATION/cancel/via la méthodeHTTP POST.

Exemple¶

POST /api/booking/4/cancel/

{
    "err": 0,
}

Erreur : réservation déjà annulée¶

{
    "err": 1,
    "err_class": "already cancelled" 
}

Accepter une réservation¶

Il est possible de déplacer une réservation de la liste d’attente vers la liste principale grâce à un appel à l’adresse/api/booking/ID-DE-LA-RESERVATION/accept/via la méthodeHTTP POST.

Exemple¶

POST /api/booking/4/accept/

{
    "err": 0,
    "overbooked_places": 0
}

{
    "err": 1,
}

Erreur : la réservation n’est pas en liste d’attente¶

{
    "err": 3,
    "err_class": "booking is not in waiting list" 
}

Suspendre une réservation¶

Inversement, il est possible de déplacer une réservation de la liste principale vers la liste d’attente grâce à un appel à l’adresse/api/booking/ID-DE-LA-RESERVATION/suspend/via la méthodeHTTP POST.

Exemple¶

{
    "err": 0,
}

{
    "err": 1,
}

Erreur : la réservation est déjà en liste d’attente¶

{
    "err": 3,
    "err_class": "booking is already in waiting list" 
}

Redimensionner une réservation¶

Il est possible de modifier le nombre de places prises par une réservation grâce à un appel à l’adresse/api/booking/ID-DE-LA-RESERVATION/resize/via la méthodeHTTP POST.

count | Nombre de places. | 2

Exemple¶

POST /api/booking/4/resize/

{
    "err": 0,
}

{
    "err": 1,
}

Erreur : évènement plein¶

{
    "err": 3,
    "err_class": "sold out" 
}

Anonymiser une réservation¶

Il est possible d’anonymiser une réservation grâce à un appel à l’adresse/api/booking/ID-DE-LA-RESERVATION/anonymize/via la méthodeHTTP POST.

Exemple¶

POST /api/booking/4/anonymize/

{
    "err": 0,
}

Supprimer une réservation¶

Il est possible de supprimer une réservation grâce à un appel à l’adresse/api/booking/ID-DE-LA-RESERVATION/via la méthodeHTTP DELETE.

Exemple¶

DELETE /api/booking/4/

{
    "err": 0,
}

{
    "err": 1,
}

# Obtenir les créneaux d’un agenda¶

Obtenir les créneaux d’un agenda¶

Deux API existent pour récupérer les créneaux réservables d’un agenda, selon s’il est de type rendez-vous ou évènements. Certains paramètres sont communs :

Nom | Description | Valeurs permises | Notes
--------------------------------------------
date_start | Filtrer les évènements selon leur date de début. | Date au format YYYY-MM-DD. | {{today|date:"Y-m-d"}}retournera les événements disponibles à partir d’aujourd’hui.
date_end | Filtrer les évènements selon leur date de fin. | Date au format YYYY-MM-DD. | {{today|add_days:16|date:"Y-m-d"}}retournera les événements disponibles avant J+15 (la borne supérieure étant exclue).
user_external_id | Inclure des informations supplémentaires en fonction de l’utilisateur spécifié. | Identifiant unique d’un utilisateur. | Chaque créneau contiendra une nouvelle clébooked_for_external_userqui indiquera si l’utilisateur a déjà une réservation.
exclude_user_external_id | Désactiver les créneaux pour lesquels l’utilisateur spécifié a déjà une réservation. | Identifiant unique d’un utilisateur. | Les créneaux déjà réservés apparaîtront désactivés, de manière analogue à s’ils étaient complets.
hide_disabled | Exclure les créneaux désactivés. | trueoufalse | 
bypass_delays | Ne pas prendre en compte les délais de réservation. | trueoufalse(valeur par défaut) | Usuellement pour permettre à un agent de passer outre ceux-ci; le paramètre doit alors également être mentionné au moment de la réservation (l’appel à l’API « fillslot »).

Agenda évènement : obtenir l’ensemble des évènements¶

La liste des évènements d’un agenda est accessible à l’adresse/api/agenda/SLUG-DE-LAGENDA/datetimes/via la méthodeHTTP GET.

min_places | Filtrer les évènements selon leur nombre de places libres minimum. | Entier supérieur à 1. | Si un utilisateur souhaite réserver 2 places, il est utile de ne présenter que les évènements où au moins deux places sont vacantes.
events | Inclure les évènements futurs (par défaut) ou passés. | all,futureoupast. | 

Exemple¶

GET /api/agenda/foo-bar/datetimes/

{
    "err": 0,
    "data": [
        {
        "text": "Event",
        "label": "Event",
        "date": "2020-06-11",
        "datetime": "2020-06-11 10:00:00",
        "description": null,
        "pricing": null,
        "url": null,
        "disabled": true,
        "api": {
        },
            "places": {
                "available": 0,
                "full": true,
                "has_waiting_list": false,
                "reserved": 3,
                "total": 3
            }
        },
        {
        "id": "event2-slug",
        "slug": "event2-slug",
        "text": "Event 2",
        "label": "Event 2",
        "date": "2020-06-12",
        "datetime": "2020-06-12 10:00:00",
        "disabled": false,
        "api": {
        "bookings_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/bookings/event2-slug/",
        "fillslot_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/fillslot/event2-slug/",
        "status_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/status/event2-slug/",
        "check_url": "http://chrono.dev.publik.love/api/agenda/foo-bar/check/event2-slug/",
        },
                "available": 3,
                "full": false,
                "reserved": 0,
                "total": 3
            }
        }
    ],
    "meta": {
    "no_bookable_datetimes": false,
    "bookable_datetimes_number_total": 2,
    "bookable_datetimes_number_available": 1,
    "first_bookable_slot": {
        ...
    }
    }
}

Agenda rendez-vous : obtenir les créneaux disponibles¶

La liste des évènements d’un agenda est accessible à l’adresse/api/agenda/SLUG-DE-LAGENDA/meetings/SLUG-DU-TYPE-DE-RDV/datetimes/via la méthodeHTTP GET.

resources | Filtrer les créneaux où certaines resources sont disponibles. | Liste de slugs séparés par des virgules. | 
minutes | Filtrer les créneaux sur l'horaire de début du créneau | Des nombres entiers de 0 à 59, séparés par des virgules | 0,30 retournera les créneaux qui commencent au heures piles et au demi-heures.

Exemple¶

GET /api/agenda/rdvs-autre/meetings/base/datetimes/

{
    "data": [
          {
            "api": {
                "fillslot_url": "https://chrono.dev.publik.love/api/agenda/rdvs-autre/fillslot/19:2020-08-05-1500/"                                                                                               
            },
            "date": "2020-08-05",
            "datetime": "2020-08-05 15:00:00",
            "disabled": true,
            "id": "19:2020-08-05-1500",
            "text": "5 août 2020 15:00" 
        },
        {
            "api": {
                "fillslot_url": "https://chrono.dev.publik.love/api/agenda/rdvs-autre/fillslot/19:2020-08-05-1515/"                                                                                               
            },
            "datetime": "2020-08-05 15:15:00",
            "disabled": false,
            "id": "19:2020-08-05-1515",
            "text": "5 août 2020 15:15" 
        },
        {
            "api": {
                "fillslot_url": "https://chrono.dev.publik.love/api/agenda/rdvs-autre/fillslot/19:2020-08-05-1530/"                                                                                               
            },
            "datetime": "2020-08-05 15:30:00",
            "id": "19:2020-08-05-1530",
            "text": "5 août 2020 15:30" 
        }
    ],
    "meta": {
    "bookable_datetimes_number_total": 3,
    "bookable_datetimes_number_available": 2,
            "api": {
            },
        }
    }
}

Agenda évènement : obtenir l’ensemble des évènements de plusieurs agendas¶

Il est possible d’obtenir une liste d’évènements aggrégés depuis plusieurs agendas via un appelHTTP GETà l’adresse/api/agendas/datetimes/(noter les pluriels).

agendas | Identifiants des agendas. | agenda-slug,agenda2-slug

Ce paramètre est obligatoire et vient s’ajouter à la liste des paramètres acceptés par l’API de récupération des évènements classique.

Réponse¶

La réponse est la même que celle de l’API de récupération des évènements classique. La seule différence est que les identifiants des évènements (clé "id") sont constitués de la concaténation entre le slug de l’agenda et le slug de l’évènement. Cela permet leur réutilisation dans l’API deréservation multiple.

Agenda évènement : obtenir les évènements récurrents¶

La liste des évènements récurrents définis sur un agenda est accessible à l’adresse/api/agendas/recurring-events/?agendas=SLUG-DE-LAGENDAvia la méthodeHTTP GET.

Attention, les occurrences d’un évènement récurrents sont bien retournées par l’API/datetimes/décrite plus haut. Cette API n’est utile que dans des cas très spécifiques, où l’on voudrait récupérer l’évènement récurrent source plutôt que les évènements directement réservables qui en découlent.

Les évènements retournés sont réservables grâce à l’API deréservation multiple des évènements récurrents.

Ce paramètre est obligatoire.

Exemple¶

GET /api/agendas/recurring-events/?agenda=SLUG-DE-LAGENDA

{
    "data": [
    {
        "date": "2021-09-06",
        "datetime": "2021-09-06 14:00:00",
        "id": "xxx@event-slug:0",
        "text": "Lundi: Évènement",
        "url": null
    },
    {
        "date": "2021-09-21",
        "datetime": "2021-09-21 14:00:00",
        "id": "xxx@other-event-slug:1",
        "text": "Mardi: Autre Évènement",
    }
    ]
}

Exemple de création graphique avec intégration personnalisée

Ce niveau de prestation s’applique lorsque lorsque la collectivité souhaite disposer d’une charte graphique spécifique pour le portail usagers Publik, charte alors créée par Entr'ouvert.

Mes démarchesVille de LilleAffichage desktop / affichage mobile

# Gestion des relations d’héritage entre rôles

Gestion des relations d’héritage entre rôles

Les relations d’héritage permettent de cascader les permissions et de gérer plus finement le contrôle d’accès.

* Lister les relations d’héritage d’un rôle
* Ajouter des relations d’héritage entre rôle
* Supprimer les relations d’héritage d’un rôle

# Autres fonctions

Autres fonctions

Vérifier un couple identifiant-mot de passe

La vérification d'un couple identifiant-mot de passe se fait avec le WebService accessible à l'adresse/api/check-password/via la méthodeHTTP POSTen soumettant un document JSON décrivant l'identifiant et le mot de passe de l'utilisateur que l'on souhaite vérifier.

L'utilisateur employé pour faire l'appel doit avoir le rôleAdministrateur des utilisateurs.

Cette fonction n'ouvre pas de session pour l'utilisateur dont on vérifie l'identifiant et le mot de passe.

Paramètres

Propriété | Description | Valeur requise | Valeur permise
username | identifiant | oui | chaîne quelconque
password | mot de passe | oui | chaîne quelconque

Les valeurs null ne sont pas autorisées.

Exemple

$ curl --header "Content-Type: application/json" --data '{"username": "john.doe", "password": "secret"}' https://admin:admin-password@host_authentic2/api/check-password/

POST /api/check-password/ HTTP/1.1Content-Type: application/json
Authorization: Basic xxxx
Content-Length: xxx

{
    "username": "john.doe",
    "password": "secret",
}

Retour Passant

HTTP/1.1 200 OK

{
        "result": "1",
}

Cas non-passant

Code | Signification | Contenu
------------------------------
403 | Permission non accordée d'effectuer l'action | {"errors":"You do not have permission to perform this action.","result":0}
200 | Le couple identifiant-mot de passe n'est pas valide | {"errors":["Invalid username/password."],"result":0}

Par exemple :

HTTP/1.1 403 FORBIDDEN
Server: nginx
Date: Tue, 15 Jan 2019 14:28:12 GMT
Content-Length: 50
Connection: keep-alive
Content-Language: fr
Vary: Accept-Language, Cookie
Allow: POST, OPTIONS

{"errors":"You do not have permission to perform this action.","result":0}

Date: Tue, 15 Jan 2019 14:26:12 GMT
Content-Length: 52
Strict-Transport-Security: max-age=31536000;

{"errors":["Invalid username/password."],"result":0}

Tests d'existence des comptes en masse

Le test d'existence des comptes en masse se fait avec le WebService accessible à l'adresse/api/users/synchronization/via la méthodeHTTP POSTen soumettant un document JSON décrivant la liste des identifiants des utilisateurs à tester.

known_uuids | liste des identifiants | oui | 

Exemple

POST /api/users/synchronization/ HTTP/1.1Authorization: Basic xxx
Content-Length: xxxx

{
    "known_uuids":["e46d46ebcb1d4d6bac4571159b542389", "1234567890"],
}

200 Ok

{
    "unknown_uuids":["1234567890"],
    "result":1
}

400 | Le format de la requête est invalide (JSON mal formaté, attribut manquant, etc..) | Un document JSON décrivant les erreurs rencontrées
401 | L'authentification a échouée | 

400 BadRequest

{    
    "detail":"JSON parse error - Expecting ',' delimiter: line 1 column 53 (char 52)" 
}

Provisionner des objets dans les autres applications

Permet d'assurer qu'au utilisateur ou un rôle crée dans authentic sera disponbile dans les autres birques de Publik. Se fait avec le WebService accessible à l'adresse/api/provision/via la méthodeHTTP POSTen soumettant un document JSON contenant l'identifiants de l'objet à provisionner.

user_uuid | identifiant d'un utilisateur | non | 
role_uuid | identifiant d'un rôle | non | 

Exemple

POST /api/provision/ HTTP/1.1Authorization: Basic xxx

{
    "user_uuid": "e46d46ebcb1d4d6bac4571159b542389"
}

Retour passant

200 Ok

{
    "err": 0,
    "leftover_audience": [],
    "reached_audience": ["https://hobo-foo.test.entrouvert.org/accounts/mellon/metadata/", "https://demarches-foo.test.entrouvert.org/saml/metadata", "https://passerelle-foo.test.entrouvert.org/accounts/mellon/metadata/", "https://foo.test.entrouvert.org/accounts/mellon/metadata/", "https://agents-foo.test.entrouvert.org/accounts/mellon/metadata/", "https://agendas-foo.test.entrouvert.org/accounts/mellon/metadata/", "https://statistiques-foo.test.entrouvert.org/accounts/mellon/metadata/"] 
}

# Introduction aux API de gestion d’identités et d’accès

Introduction aux API de gestion d’identités et d’accès

Cette section de la documentation s'adresse aux développeurs d'applications tierces désirant interfacer celles-ci avec le module de gestion d’identités et d’accès (techniquement nommé authentic).

Cette documentation se veut facile à lire, avec beaucoup de notes et d'exemples. Les différentes pages détaillent les points d'accès à utiliser pour réaliser les différentes opérations.

Les exemples donnés dans ce document utilisent pour la plupart l'outil en ligne de commandecurlqui permet de manière simple l'envoi de requêtes HTTP à un serveur.

L'API Web Services est constituée d'appels REST, qui sont idéalement effectués en HTTPS, pour assurer la sécurité et la confidentialité des échanges. Le format d'échange des données est JSON. Ces deux propriétés la rendent accessible facilement à tous les langages et environnements de programmation modernes.

Authentification et identifiant des utilisateurs

L'authentification se fait en utilisant des comptes d'utilisateurs créés dans authentic. Ces comptes sont considérés comme des « comptes techniques » mais ils sont créés comme n'importe quel utilisateur. L'identifiant et le mot de passe du compte sont utilisés en utilisant le mode d'authentification HTTP Basic lors des appels aux WebServices. Lors de l'utilisation de l'API avec un compte utilisateur, l'identifiant des utilisateurs servi est l'identifiant unique uuid.

Les identifiants des clients OpenIDConnect (OIDC) peuvent également être utilisés pour interroger l'API. L'authentification HTTP Basic est toujours utilisée. L'identifiant employé est le Client ID du client OIDC. Le mot de passe utilisé est le Client Secret OIDC du client OIDC. Dans ce cas, l'identifiant des utilisateurs servi est l'identifiant désignant l'utilisateur auprès de ce service OIDC appelé sub.

Contrôle d'accès

En utilisant la fonctionnalité des rôles affectés aux utilisateurs, il est possible d'autoriser ou non les différentes actions : créer, modifier, rechercher, supprimer.

Par exemple, les utilisateurs listés via l'API se limitent à ceux visible du compte utilisateur employé pour interroger l'API.

# Vue d’ensemble sur les connecteurs

Vue d’ensemble sur les connecteurs

Les connecteurs sont ce qui va permettre à Publik d'échanger des informations par le biais de webservices avec une application métier ou même simplement d'aller récupérer données dans un fichier tableur (CSV ou ODS).

Nous avons une liste (pas forcément très à jour, n'hésitez pas à nous contacter) desconnecteurs existants.

Aller chercher des informations dans un fichier tableur est relativement aisé, vous pouvez construire unesource de donnéeset élaborer ensuite desrequêtes avancées.

Enfin, il est possible dedévelopper de nouveaux connecteurswebservices, mais la tâche est nettement plus ardue et dépend des webservices offerts par l'application en face.

Introduction

La connexion de Publik avec des systèmes tiers permet des échanges d'informations de diverse nature, à des endroits et des moments différents. Cette documentation présente les principes généraux de ces échanges, d'un point de vue technique.

Les natures, lieux et moments d'interconnexion étant nombreux dans Publik, définir un connecteur commence par une description des fonctionnalités attendues, en terme de service à rendre aux utilisateurs, qu'ils soient usagers (aspects frontoffice) ou agents (aspects backoffice).

Une fois établies ces spécifications fonctionnelles générales, on étudie comment le connecteur peut être créé : quelles seront les informations à échanger, à quel moment, où les afficher, etc. À cet instant de l'étude, il est nécessaire de disposer des éléments techniques concernant le ou les systèmes tiers, voire d'un contact avec un technicien ou un développeur chez ce tiers.

Cette documentation détaille les différentes possibilités des connexion à l'heure actuelle (bien que Publik dispose de systèmes génériques à de nombreux endroits, de nouvelles peuvent être imaginées). À la fin du document sont présentés quelques formats de connecteurs habituels pour des domaines métier déjà couverts par Publik.

Lieux et moments de connexion

Sur les portails

Un système Publik dispose de deux portails : le portail usager (front-office) et le portail agent (back-office). Ils sont tous les deux opérés par la brique logicielle nommée Combo. Il s'agit d'un CMS simplifié, dédié à la création de portails.

Comme dans de nombreux CMS, les pages sont composées de «cellule» d'informations. C'est dans ces cellules qu'il est possible d'afficher des informations provenant de systèmes tiers. On distingue principalement deux type d'informations :

* les informations générales au site, par exemple les actualités du lieu ou la liste des arrêts de bus ;
* les informations liées à l'utilisateur connecté, par exemple la liste des livres empruntés à la médiathèque, ou la liste des factures de cantine à payer.

Ces informations sont obtenues à travers des connecteurs, qui vont chercher l'information dans les logiciels tiers « en temps réel », c'est-à-dire au moment de l'affichage de la page.

À noter que Publik utilise ce principe en interne : quand un usager se connecte, on lui affiche une cellule contenant la liste de ses demandes en cours. Celles-ci sont obtenues par Combo depuis la brique w.c.s. (qui gère les démarches dans Publik).

Lors de la saisie des demandes (formulaires)

Lors de l'affichage d'un formulaire, Publik peut afficher des données provenant d'un système tiers, par exemple la liste des rues de la ville ou la liste des enfants de la famille de l'usager.

Publik va interroger le système tiers au moment de l'affichage du formulaire. Il peut récupérer des informations générales (la liste de rues) ou liées à l'usager (la liste des enfants). Cela peut aussi être des informations liées à un choix précédent dans le formulaire, par exemple la liste des associations liées au domaine du sport (ce domaine ayant été choisi par l'usager préalablement dans le formulaire).

Les informations ainsi remontées peuvent être affichées sous forme de liste de choix (système "select" en HTML). Si la liste est trop longue, Publik (w.c.s.) peut n'afficher qu'une partie de la liste en fonction des lettres tapées au clavier par l'usager ("typeahead").

Une fois que l'usager a choisi la valeur, toutes les données relatives provenant du logiciel tiers sont disponibles dans le formulaire, au même titre que les autres informations saisies librement.

Lors du traitement des demandes (workflows)

Après saisie de la demande, celle-ci entre en traitement dans un "workflow". Celui-ci est un ensemble de statut, chacun de ces statut contenant des actions qui permettent entre autre de changer de statut (pour faire progresser la demande).

Un type d'action particulier permet de faire appel à un connecteur : « appeler un webservice ». Publik peut alors communiquer avec un logiciel tiers, pour :

* récupérer des informations (par exemple le secteur scolaire correspondant à la rue indiquée par l'usager) ;
* récupérer un document (par exemple l'attestation de scolarité de son enfant) ;
* envoyer des informations (par exemple une demande d'inscription à la médiathèque) et récupérer le résultat (numéro de la demande dans le logiciel tiers)

Les données récupérées font ensuite partie de la demande, et on peut donc chaîner des appels, par exemple :

* appel webservice « envoi d'une demande de badge de parking » : récupération du numéro de la demande "N" ;
* appel webservice « récupération de l'état de la demande "N" » : faire avancer la demande selon que le badge a bien été émis ou est refusé (et dans les autres cas, tenter à nouveau l'appel 12h plus tard)

Voir aussi la documentation officielle de Publik sur cette action :

https://doc-publik.entrouvert.com/admin-fonctionnel/fabrique-de-workflows/les-actions-de-workflow/elements_appeler-webservices/

Ces appels au connecteur peuvent intervenir à tout moment dans le workflow. Ils peuvent être lancés "en temps réel" au moment où l'agent travaille sur la demande et la fait avancer parmi les statuts, ou bien en "tâche de fond" lors que des délais d'expiration et/ou de certaines conditions sont configurés pour faire avancer la demande.

Pilotage des demandes depuis un logiciel tiers

Dans le workflow de traitement d'une demande, il est également possible de configurer des déclencheurs (triggers) qui sont autant de webservices rendus disponibles à une application tierce. Celle-ci peut appeler le webservice déclencheur et Publik va alors faire avancer la demande vers le statut cible. Au passage, l'application tierce peut envoyer des données qui seront alors ajoutées au formulaire.

Ce système est notamment utilisé en interne par Publik pour gérer le paiement lié à une demande, et la faire passer d'un statut "à payer" à un statut "payé", ou "refusé" ou "annulé" selon le déclencheur appelé par le système de paiement de Publik.

Dans le code des conditions et des expressions

Dans les formulaires et dans les workflows, des conditions sont utilisables, écrites sous forme d'expressions en langage Python ou en langage de gabarits Django. À cet instant il est aussi possible de faire appel à un connecteur pour récupérer une valeur et l'inclure à la condition.

On peut ainsi,par exemple:

* sur un formulaire, décider d'afficher une page seulement si un connecteur répond "OK" ;
* sur un formulaire, refuser de passer à la page suivante tant qu'un connecteur n'accepte pas les valeur saisies sur la page actuelle ;
* dans un workflow, décider de passer dans un certain statut seulement si le connecteur a répondu une certaine valeur ;
* etc.

Les possibilités sont aussi vastes que ce qu'un langage de programmation permet.

Lors du paiement

Aspect moins générique que les précédents, Publik dispose d'un module de paiement (nommé "lingo"). Il est connectable d'un côté avec les principaux systèmes de paiement en ligne du marché, de l'autre avec un logiciel tiers quand on doit informer ce dernier qu'un paiement a eu lieu, ou a échoué.

Lorsqu'il est connecté avec un logiciel tiers, cela permet d'informer immédiatement du paiement d'une facture ; celle-ci ne sera alors plus visibleparmila liste des factures à payer qui seront remontées depuis le même logiciel.

Géocodage et base d'adresses

Publik peut effectuer géocodage et géocodage inversé.

Dans un formulaire, l'utilisation d'un champ de type «carte» permet à l'usager de cliquer sur un lieu précis. Publik peut alors interroger un connecteur de géocodage inverse et trouver l'adresse correspondante. L'interrogation a lieu au moment où l'usager indique sa position (soit par le clic sur la carte, soit parce qu'il a accepté d'être géolocalisé).

Plus tard dans le workflow, il est possible de (re)géolocaliser la demande en interrogeant un connecteur de géocodage, sur l'adresse indiquée par l'usager. On peut alors ensuite rappeler un géocodage inverse pour trouver l'adresse normée selon le référentiel tiers. Cela permet aussi de remonter d'autres informations liées à un SIG (Système d'Information Géographique), comme le bureau de vote ou le secteur scolaire.

Par ailleurs Publik peut utiliser une base d'adresse, typiquement la liste des rues, pour aider à la saisie. Un connecteur de type "base adresse" renvoie la liste des voies de la ville (voir plus haut les possibilités d'affichage de liste dans les formulaires).

Lors de l'authentification

Pour éviter une gestion manuelle de l'accès au backoffice, Publik peut se connecter à un annuaire LDAP (ou Active Directory). Cela permet de retrouver dans Publik l'ensemble des agents de la ville, en leur permettant d'utiliser leurs identifiant et mot de passe habituels. L'authentification est faite au moment de la connexion, et elle s'effectue en interrogeant l'annuaire (aucun code d'authentification, aucun mot de passe n'est copié sur Publik).

Il est aussi possible de fédérer les comptes de Publik avec des systèmes SSO tiers, tels que FranceConnect, un compte métropolitain ou tout autre fournisseur d'identité local, tant qu'il suit un protocole de fédération standard comme OpenID Connect ou SAML.

Single Sign On (SSO)

Par ailleurs Publik est lui-même fournisseur d'identité selon les protocoles OpenID Connect ou SAML. On peut donc relier des logiciels tiers selon ces protocoles, afin d'offrir une fonctionnalité de SSO : une fois l'usager connecté à Publik, il accède directement aux applications tierces sur lesquels il est fédéré, sans avoir à saisir identifiant ou mot de passe.

Nature des informations échangées

Format général

En entrée comme en sortie, les webservices de Publik utilisent des messages au format JSON (http://json.org/).

En entrée, quand il s'agit d'un GET, les éventuelles données sont dans les arguments de l'URL (query string). Quand il s'agit d'un POST, le format des données à envoyer (payload) à un webservice dépend de ce que celui-ci attend ; il s'agit en général d'un dictionnaire, simple liste de clé-valeur. Il peut également y avoir aussi des informations dans les arguments de l'URL (query string).

En sortie, sauf exception, le format est le suivant :

{

"err": 0,

"data": ...

}

Les deux clés sont obligatoires. La valeur de "err" est 0 quand il n'y a pas eu d'erreur. Dans ce cas, "data" contient les données demandées.

En cas d'erreur, "err" est différent de 0 et il peut exister deux clés "err_class" et "err_desc", qui sont respectivement la classe et une description de l'erreur :

{

"err": 1,                             # différent de zéro

"err_class": "TypeError",             # le nom de la classe d'erreur (optionnel)

"err_desc": "name must be a string",  # une description de l'erreur (optionnel)

"data": null                          # il peut y avoir des données

}

Quand le résultat n'est pas du JSON, par exemple quand un webservice doit renvoyer un document PDF, il est renvoyé tel quel, classiquement, avec les entêtes HTTP normales, notamment le « Content-Type ». En cas d'erreur, on peut ajouter une entête « x-error-code » contenant l'équivalent du "err" du format JSON.

Référentiels

Les référentiels utilisés par Publik sont une liste de doublons "id" "text". Par exemple une liste des rues :

id | text

1 | rue du Château

2 | avenue du Maine

3 | place Denfert-Rochereau

Toutes les valeurs sont des chaînes de caractères. Ceci donne en JSON :

GET /liste-des-rues/

{

"err": 0,

"data": [

{"id": "1", "text": "rue du Château"},

{"id": "2", "text": "avenue du Maine"},

{"id": "3", "text": "place Denfert-Rochereau"}

]

}

Dans un formulaire, c'est la liste des "text" qui est présentée à l'usager, dans l'ordre reçu. Le "id" est conservé dans les donnéesrawdu formulaire. Typiquement, si le champ a « rue » comme identifiant, alors on aura deux variables disponibles dans le formulaire : « form_var_rue » (text) et « form_var_rue_raw » (id).

Les services qui renvoient un référentiel peuvent gérer un argument "q" pour filtrer les résultats. Cela permet de présenter des formulaires où l'usager doit saisir quelques caractères pour voir les possibiltés disponibles. Par exemple :

GET /liste-des-rues/?q=eau

{

"err": 0,

"data": [

]

}

En plus des deux clés id et text obligatoires, on peut ajouter d'autres valeurs, par exemple :

{

"err": 0,

"data": [

{"id": "1", "text": "rue du Château", "type": "rue", "arr": "14"},

{"id": "2", "text": "avenue du Maine", "type", "avenue", "arr": "14"},

{"id": "4", "text": "place de la Concorde", "type": "place", "arr": "8"}

]

}

Les valeurs "type" ou "arr" ne seront pas présentées à l'usager, mais seront, comme "id", enregistrées dans les variables du formulaire. Par exemple si l'usager choisi la rue du Château, on aura dans les données du formulaire :

* form_var_rue : "rue du Château"

* form_var_rue_raw : "1"

* form_var_rue_type : "rue"

* form_var_rue_arr : "14"

Géocodage (inverse)

Concernant le géocodage, et notamment l'accès à un référentiel des adresses, Publik suit l'API du service Nominatim (

http://wiki.openstreetmap.org/wiki/FR:Nominatim

) avec format=json.

Exemple :

GEThttp://nominatim.openstreetmap.org/reverse?format=json&lat=48.833698&lon=2.323397

{

...

"display_name": "169, Rue du Château, Quartier de Plaisance, Paris 14e Arrondissement, Paris, Île-de-France, France métropolitaine, 75014, France",

"address": {

"house": "169",

"road": "Rue du Château",

"suburb": "Quartier de Plaisance",

"city_district": "Paris 14e Arrondissement",

"city": "Paris",

"county": "Paris",

"state": "Île-de-France",

"country": "France",

"postcode": "75014",

"country_code": "fr"

},

...

}

Remontée d'informations génériques

D'une façon générale, un webservice tiers peut renvoyer n'importe quelles données :

GET /foo/

{

"err": 0,

"data": ...  # ici un objet JSON

}

Ces données peuvent être utilisées par Publik :

* dans une cellule du CMS Combo de type « Cellule JSON » : le résultat du webservice est envoyé au moteur de Django. Il faut écrire le gabarit correspondant (https://docs.djangoproject.com/fr/3.2/ref/templates/) pour que la cellule affiche les données selon le format désiré ;
* dans un appel webservice de traitement d'une demande : le résultat « data » est alors enregistré en tant qu'objet dans les données du formulaire. Si l'appel webservice a pour identifiant « ws » et que data contient {"cle": "valeur", "cle2": "valeur2"} alors le formulaire aura deux variables « ws_response_data_cle » ("valeur") et « ws_response_data_valeur2 » ("valeur2") ;
* au niveau de w.c.s. dans des gabarits avec la syntaxe « {{ webservice.slug_du_webservice.data.cle }} » où « slug_du_webservice » est déclaré dans les paramètres.

L'URL d'interrogation peut contenir des paramètres, soit dans le chemin soit dans la

query string

. En effet les URLs sont configurable selon une syntaxe Django, par exemple :

* https://logiciel/school/{{ form_var_school_raw }}/{% if form_var_details %}?details=on{% endif %}

Ainsi Publik peut accéder à des familles de webservices de type REST (ou autre langage de requête décrite par l'URL), récupérer le résultat et l'afficher à l'usager sur le portail ou le stocker comme information additionnelle dans une demande.

RSS / Atom

Il existe dans Combo une cellule « Fil RSS » qui prend en entrée une URL (webservice) qui renvoie un document au format Atom ou RSS, plus exactement tout format reconnu par

https://pythonhosted.org/feedparser/

.

Appairage avec un compte tiers

Un mécanisme important dans un portail usager est de pouvoir connecter son compte usager avec des systèmes tiers, tels que son « compte famille » ou son « compte médiathèque ».

Pour cela, on doit disposer d'un webservice permettant de relier le compte Publik, déterminé par un NameID (une chaîne de caractères aléatoires, parfois appelée « pseudonyme ») avec le compte tiers, décrit par des données d'identification et souvent d'authentification, c'est un dire en général un nom d'utilisateur, ou un numéro de dossier, et un mot de passe ou code d'accès.

L'appel au système d'appairage est effectué ainsi par Publik :

POST /link

{

"name_id": "abc123def987",

"login": "user42",      # exemple decredentials; ça pourrait être

"password": "pass"      # par exemple un code d'activation unique

}

et le résultat attendu est :

{

"err": 0,     # appairage effectué

"data": "ok"  # (optionnel, sans effet)

}

Le connecteur appelé doit alors maintenir une table de correspondance entre le name_id Publik et le compte tiers.

À noter que c'est le connecteur qui décide si un compte Publik peut être relié à un ou plusieurs comptes tiers.

Remontée d'informations liées

Par la suite, Publik peut interroger des webservices en ajoutant le « name_id » du compte Publik dans l'URL ou dans le payload. Le connecteur doit alors trouver les données demandées correspondantes à l'usager dans le système tiers.

Exemple d'un référentiel lié à l'usager : la liste des enfants de la famille, connus du logiciel de gestion de scolarité

GET /children?name_id=abc123def987

Host: logiciel-enfance

{"err": 0, "data": [{"id": "42-1", "text": "enfant1" },

{"id": "42-2", "text": "enfant2" }]}

Exemple de données JSON liées à un usager : données de l'association à laquelle il est relié, connue du logiciel de gestion des associations

GET /asso/informations/?name_id=abc123def987

Host: logiciel-associations

{

"err": 0,

"data": {

"nom": "April",

"siret": "...",

"adresse": {...},

"president": "..."

}

}

Dés-appairage

Pour que l'usager puisse couper la connexion, un webservice de désappairage doit être disponible. Un simple

GET /unlink?name_id=abc123def987

{"err": 0, "data": "ok"}

suffit. En cas d'appairage multiple, on peut préciser le compte tiers à délier avec un « &login=user42 » dans l'URL, ou envoyer le name_id et le login en payload d'un POST.

Injection de données vers un logiciel tiers

Dans un workflow, Publik peut envoyer des données vers un logiciel tiers. Pour cela, il utilise le verbe POST et envoie un dictionnaire JSON simple (à plat). Ce dictionnaire est complètement configurable (clé et valeur) dans la configuration de l'action de workflow.

Exemple d'appel lancé par Publik (dans un workflow de w.c.s.) :

POST /inscription/centre-aere?

{

"enfant_id": "42-2",

"centre_id": "67",

"date-debut": "2018-01-01",

"date_fin": "2018-12-31"

}

En retour, le logiciel tiers indique avec un {"err": 0, ... } le succès de l'opération :

{

"err": 0,    # injection réussie

"data": "ok" # sans signification

}

Usage des référentiels

Lors de l'injection vers un logiciel tiers, il peut être nécessaire de suivre les référentiels de celui-ci, par exemple la liste des centres de loisirs pour y gérer les inscriptions : le centre choisi devra être envoyé sous forme d'un identifiant connu par le logiciel tiers ("centre_id" dans l'exemple ci-dessus).

Pour cela, on aura pris soin d'utiliser au préalable un webservice de référentiels (cf supra) lors de l'affichage du choix du centre dans le formulaire présenté à l'usager.

Il est donc important de noter que dans la très grande majorité des cas, un système d'injection de données de Publik vers un tiers nécessite que ce dernier ait d'abord mis à disposition l'ensemble de ces référentiels.

Suivi des données injectées

Un cas d'usage fréquent de l'injection de données est l'injection d'une demande, validée par un agent dans Publik, vers le logiciel tiers. La demande va être traitée dans le logiciel tiers, et devra être suivie par Publik.

Pour cela, lors de l'injection, le logiciel tiers renvoie le numéro de la demande créée :

POST /demande-inscription/

{ ... }

{

"err": 0,       # réponse : demande créée

"data": {

"id": "7834"  # et correspondance dans le logiciel tiers

}

}

Si l'action d'appel webservice a comme identifiant "demande_inscription" alors la demande dans Publik dispose d'une variable « demande_inscription_response_data_id » égale à "7834".

Ensuite, dans le workflow, Publik est programmé pour venir interroger régulièrement (ou manuellement) une URL de suivi de cette demande, par exemple configurée àhttps://logiciel-scolaire/demande/[demande_inscription_response_data_id]/status. L'action d'appel du webservice sera donc :

GET /demande/7834/status

{

"err": 0,

"data": {

"status_id": "4",

"status": "instruction",

"status_long": "instruction de la demande en cours"

}

}

Et dans le workflow Publik, en fonction du "status" ici obtenu, on fait avancer la demande vers le statut correspondant dans Publik.

Pilotage d'une demande Publik par un système tiers

Dans le cas où le logiciel tiers veut directement faire avancer une demande dans Publik, la communication se déroule dans l'autre sens : c'est le logiciel tiers qui appelle un webservice mis à disposition par Publik. Ces webservices sont nommés déclencheurs (triggers) et sont paramétrés dans les workflows de traitement d'une demande, au travers des sauts automatiques (cfhttps://doc-publik.entrouvert.com/admin-fonctionnel/fabrique-de-workflows/les-actions-de-workflow/actions_transition-automatique/)

La demande d'un changement d'état se fait par une requête POST à l'adresse du formulaire en question, suivi de « /jump/trigger/ » et de l'identifiant du déclencheur, par exemple :

POST /inscriptions/newsletter/14/jump/trigger/validate

Host: demarches.example.net

Publik (w.c.s.) retourne alors une réponse JSON avec une clé "err" :

{"err": 0, "url": null}

Il est également possible d'accompagner le déclenchement d'un changement de statut d'une série de données, sous forme d'un dictionnaire JSON à plat, qui seront enregistrées dans les données de workflow du formulaire.

{"donnee1": "valeur1", "donnee2": "valeur2", ... }

Paiement

Lorsqu'un logiciel dispose de factures, il les met à disposition via des webservices : Publik les affiche à l'utilisateur et lui permet de les payer en ligne. Un autre webservice disponible sur le logiciel tiers permet à Publik de l'informer des paiements effectués.

S'agissant de données liées à un usager, le système de facturation nécessite unappairagepréalable, cf supra.

Liste des factures

On distingue généralement deux types de factures : celles qui sont à payer (factures en cours), et celles qui ont déjà été payées (historique des paiements). Le format attendu est le même :

GET /invoices/?NameID=123abc987fed

{

"err": 0,

"data": [

{

"id": "934395",

"label": "restauration août 2015",

"amount": "37.26",    # note : pas de float, toujours des string

"total_amount": "37.26",

"online_payment": true,

"created": "2015-08-01T00:00:00",

"pay_limit_date": "2015-09-29T00:00:00",

"has_pdf": true,      # si un PDF est disponible, cf plus bas

"paid": false,

... (autres informations si le logiciel en dispose)

},

...

],

}

Si une facture ne peut pas être payée en ligne (prélèvement automatique, contentieux), on peut ajouter « "online_payment": false » . En sus "no_online_payment_reason" contient alors un slug du motif de l'impossibilité de non paiement en ligne, par exemple: autobilling, litigation.

Détails d'une facture — Version PDF

Deux webservices permettent d'afficher d'une part les détails sur une facture donnée :

GET /invoice/934395/?NameID=123abd987fed

{"err": 0, "data": { ... } }

et d'autre part PDF associé (qui sera proposé à l'usager quand "has_pdf" est à true) :

GET /invoice/934395/pdf?NameID=123abd987fed

Content-Type: application/pdf

<stream du PDF>

Paiement d'une facture

Lorsqu'une facture a été payée en ligne, Publik appelle le webservice suivant :

POST /invoice/934395/pay/?NameID=123abc987fed

{

"transaction_id": "<identifiant de la transaction>",

"transaction_date": "2016-01-05T12:00:00"

}

Le retour attendu par Publik est :

{"err": 0, "data": true}

Notification des factures à payer

Un système de notification permet d'informer les usagers que de nouvelles factures sont disponibles au paiement en ligne. Le ticket de ce développement :

https://dev.entrouvert.org/issues/13122

Annexes sur le paiement

Autres documentations liées au paiement dans Publik :

* https://dev.entrouvert.org/projects/publik/wiki/Paiement_fonctionnel
* https://dev.entrouvert.org/projects/publik/wiki/Paiement

Annuaire LDAP

Publik peut se connecter à un annuaire LDAP, généralement pour se synchroniser avec la liste des utilisateurs backoffice (agents). Les modalités de configuration sont habituelles, il faut configurer la brique Authentic de la solution avec les paramètres LDAP/ActiveDirectory cibles.

Lorsqu'un utilisateur se connecte, Publik tente de l'authentifier via LDAP. Si l'authentification réussie, le compte Publik de l'agent est alors créé ou mis à jour avec les données disponibles dans l'annuaire.

Par ailleurs, Publik vient régulièrement interroger l'annuaire pour construire la liste des comptes agents (provisionning). Cela permet d'avoir cette liste exhaustive visible dans Publik et par exemple d'attribuer les rôles aux agents sans qu'ils aient besoin de se connecter auparavant.

Publik dispose d'un fournisseur d'identité (brique Authentic de la solution) versatile : il peut fournir des identités selon les protocoles standards du marché, à savoir OpenID Connect et SAML.

La documentation pour établir une telle connexion est ici :Mise en place d'un SSO avec un portail métier

Ci-dessous un résumé rapide de ce que le service à connecter doit fournir, et ce que Authentic fourni, afin d'établir au final la "confiance" entre les deux entités.

Connexion OpenID Connect

Le logiciel tiers doit fournir les paramètres OIDC suivants :

* redirect_url
* post_logout_redirect_uri

Et  Authentic fourni :

* client_id
* client_secret
* authorization_url
* token_url

Connexion SAML

Le service doit fournir ses metadonnées SAML, qui sont enregistrées dans Authentic. De son côté, Authentic fourni ses metadonnées sur

https://authentic.example.net/idp/saml2/metadata

.

Connexion CAS

Un mode CAS+LDAP est également possible ; comme son nom l'indique il nécessite un annuaire partagé entre Publik et le logiciel tiers. C'est donc un mode de connexion qui est plutôt dédié aux utilisateurs backoffice (agents).

API Génériques

Dans cette section sont présentés quelques formats de webservices attendus pour remplir certaines fonctionnalités dans Publik.

Connecteur « famille »

Un connecteur générique « famille » existe dans Publik, qui propose un ensemble de webservice permettant de construire un portail famille minimal, permettant notamment de payer les factures :https://dev.entrouvert.org/projects/passerelle/wiki/Connecteur_famille

Si un logiciel tiers de gestion de l'enfance (scolaire, péri-scolaire, etc.) désire s'intégrer à Publik, il doit suivre les API décrites.

Connecteur « facturier »

Si un logiciel tiers propose des factures à payer à un usager, alors il peut suivre l'API correspondante : lire la partie «factures» dans le connecteur famille ci-dessus.

Géocodage & SIG

Publik peut suivre tout connecteur de géocodage suivant l'API de Nominatim (cf supra). Notez qu'un tel connecteur avec la BAN existe déjà (Base Adresse Nationale [française],https://adresse.data.gouv.fr/).

Pour l'affichage des cartes, Publik peut utiliser un moteur de tuiles spécifique tant qu'il est compatible avec leaflet (

http://leafletjs.com/

). Il est également possible d'afficher des points d'intérêt sur la carte, par exemple les stations de locations de vélo : le SIG doit pour cela fournir un webservice renvoyant les points au format GeoJSON (

http://geojson.org/

)

Gestion des agendas & rendez-vous

Publik dispose d'un logiciel interne de gestion des agendas et rendez-vous, dont l'usage technique est décrit dans la documentation officielle de Publik :https://doc-publik.entrouvert.com/admin-fonctionnel/prises-de-rendez-vous

Si un logiciel tiers veut proposer ce même service et s'intégrer « naturellement » à Publik, il doit suivre les API décrites.

Développement d'un connecteur

Ajouter un connecteur compatible Publik dans un logiciel tiers revient donc à proposer un ensemble de webservices suivant les modèles proposés ci-dessus, selon les fonctionnalités demandées.

Il s'agit donc de mettre en place des « endpoints » accessibles en GET ou en POST, échangeant des données au format JSON. Sauf exception le format de réponse est toujours de la forme {"err": 0, "data": ...}.

En cas d'appairage d'un compte Publik avec un compte sur le logiciel, Publik enverra en argument, ou dans le payload, le NameID du compte Publik. Le logiciel tiers doit maintenir une table de fédération entre ce pseudonyme et le compte local dans l'application.

En terme de sécurité d'accès au webservice, il convient de mettre en place :

* un chiffrage par SSL/TLS, c'est-à-dire en HTTPS pour un webservice, avec un certificat reconnu
* un filtrage par adresse IP (pour ne permettre que les accès par Publik) le cas échéant

Pour renforcer la partie sécurité, il est possible d'utiliser le système de signature de Publik, documenté ici :https://doc-publik.entrouvert.com/tech/wcs/api-webservices/authentification/. Cela permet au logiciel tiers d'être sûr que c'est bien Publik qui l'interroge, et d'éviter les rejeux.

Passerelle

Quand des webservices existent déjà, ou qu'un framework permet de créer des webservices sur le logiciel tiers, alors ils peuvent ne pas être compatibles avec Publik. Dans ce cas, on ajoute dans Passerelle un "traducteur" capable de passer du langage de Publik à celui du logiciel tiers.

Passerelle est un logiciel en Python/Django qui propose quelques outils pour aider à développer un tel connecteur. Il est particulièrement efficace quand le logiciel en face parle déjà en JSON, mais il peut gérer n'importe quel protocole accessible en Python, tel que SOAP.

Voici un exemple d'un code connecteur, qui va chercher une liste dans le logiciel tiers, et la propose à Publik sous la forme d'un référentiel selon l'API Publik :

@endpoint()

def classes(self, request):

# lire la liste des classes sur le logiciel tiers :

response = requests('https://logicielenfance/referentiel/classes').json()

# construire la réponse à renvoyer selon l'API Publik

data = []

for item in response:

# le "code" renvoyé par le logiciel tiers est le "id" dans l'API Publik

# le "label" renvoyé par le logiciel tiers s'appelle "text" dans l'API Publik

data.append({ "id": item["code"], "text": item["label"] })

return data

Si le webservice tiers était en SOAP, c'est la ligne "response = ..." qui ferait une requête SOAP au lieu d'un simple accès REST/JSON ici.

Pour en savoir plus et s'essayer au développements de connecteur dans Passerelle, lire :https://doc-publik.entrouvert.com/tech/connecteurs/developpement-d-un-connecteur/

Il est utile de consulter le code des connecteurs existants :

* https://git.entrouvert.org/passerelle.git/tree/passerelle/apps/: les connecteurs "officiels" qui couvrent des logiciels ou des principes transversaux
* https://git.entrouvert.org/passerelle.git/tree/passerelle/contrib/: les connecteurs "spécifiques" qui couvrent des besoins locaux à un client

Tous les connecteurs ne sont pas simples, ni toujours écrits dans les règles de l'art ; parfois les webservices proposés en natif sont éloignés des besoins fonctionnels, ou ne sont pas homogènes, et il ne suffit pas de faire une simple passerelle d'un webservice tiers vers une API Publik. Nous conseillons de regarder d'abord les "petits" connecteurs avec un ou deux enpoints, et parmi ceux-là de prendre ceux qui ont été codé le plus récemment.

Annexes

* Description d'API proposées par w.c.s.
* Connexion à un centre d'appel
* Stockage JSON intégré à Publik

# Gestion des rôles

Gestion des rôles

Les

[rôles](https://doc-publik.entrouvert.com/admin-fonctionnel/gerer-les-roles/)

sont central dans Publik puisqu'ils servent à définir toute les autorisations des utilisateurs sur la plate-forme.

* Lister les rôles
* Créer un rôle
* Modifier un rôle
* Lister les membres d’un rôle
* Ajouter un utilisateur dans un rôle
* Retirer un utilisateur d’un rôle
* Gestion en masse des utilisateurs membres d’un rôle
* Supprimer un rôle

Intégration par un agent administrateur fonctionnel

Le portail citoyen Publik (habituellement hébergé sur une adresse du type https://demarches.nomdelacollectivite.fr/) a une structure imposée mais est graphiquement adaptée à chaque utilisateur de la solution.Dans le cas d’une plate-forme livrée par Entr’ouvert, une prestation d’intégration graphique est prévue pour chaque client.

Le portail citoyen Publik est full web. Il a été pensé pour permettre aux usagers une prise en main rapide et simple. Les interfaces en front-office sont étudiées pour être légères et pour ne recourir au javascript que lorsque cela est nécessaire. Cela nous permet d’assurer une compatibilité avec l’ensemble des navigateurs web, y compris les navigateurs mobiles (smartphone, tablette), tout en consommant peu de ressources côté client.

Pour l’usager, il est important qu’il y ait continuité (même univers graphique) entre son espace usager, ses démarches en lignes, son fournisseur d’identité, etc.

Pour atteindre cet objectif, Entr'ouvert propose 3 niveaux de prestations d’intégration graphique :

* niveau 1 : l'intégration graphique native;
* niveau 2 : l'intégration graphique personnalisée;
* niveau 3 : la création graphique avec intégration personnalisée.

2 ressources peuvent être ajoutées par la collectivité elle-même :

* Le logo destiné au bandeau en tête du portail,
* L'image de fond du bandeau, au besoin.

Procédure :

* depuis le portail agent, allez dans /Éditer portail citoyen (et/ou /Éditer portail agent)
* dans le menu burger, en haut à droite, sélectionner /Ressources
* En face des ressources pré indiquées Têtière : logo et/ou Têtière : fond cliquer sur l'icône de téléchargement et choisir le fichier voulu.

# Intégration graphique native

Intégration graphique native

L’intégration graphique native permet de bénéficier d’une interface moderne, adaptée à l’usage mobile. Elle intègre le bandeau et le pied de page du site institutionnel de la collectivité ainsi que ses polices et une ou deux couleurs afin que les usagers n’ait aucun doute concernant le fait qu’ils sont sur un des sites de la collectivité.

Pas besoin de livrer de maquettes du portail citoyen.

Entr'ouvert récupère directement les éléments nécessaires sur le site institutionnel de la collectivité puis livre un thème graphique sur l’instance de test ; la collectivité peut demander des ajustements (dans la limite d'un aller-retour).

Dans le cas où la charte graphique du site institutionnel est amené à changer (refonte du site à venir par exemple), les éléments graphiques attendus sont les suivants :

* les éléments graphiques de base à fournir;
* les options de mise en page;
* les cellules dans le système de gestion de contenu de Publik;
* les options dans un formulaire.

# Feature flags

Feature flags

Les « feature flags » sont des paramètres globaux permettant d’activer une fonctionnalité particulière. Ils sont généralement utilisés pour entamer une phase de dépréciations ou pour des fonctionnalités trop expérimentales ou dangereuses pour être activées par défaut. Il faut bien avoir ça en tête au moment de les activer.

Module w.c.s.

Ces options se paramètrent dans la section [options] du fichier site-options.cfg, par tenant.

* 🦣 disable-internal-statistics : désactivation des statistiques internes (dépréciation)
* 🦣 disable-python-expressions : désactivation des expressions Python (dépréciation)
* 🦣 forbid-python-expressions : erreur en cas d’utilisation d’une expression Python (dépréciation)
* 🦣 forbid-new-python-expressions : erreur cas d’importation d’un fichier contneant une expression Python (dépréciation)
* 🦣 disable-jsonp-expressions : désactivation des sources de données JSONP (dépréciation)
* 🦣 sql-create-formdef-views : création de vues SQL par démarche (dépréciation)
* 🦣 workflow-functions-only : affichage exclusif des fonctions, pas les rôles. (dépréciation)
* 🦣 disable-workflow-form-to-workflow-data : désactivation du stockage des données des formulaires de workflow dans le dictionnaire global "workflow_data" (dépréciation)
* 🦣 disabled-fields : désactivation de types de champs (dépréciation)
* 🦣 settings-disabled-screens : désactivation d’écrans de paramètres (liste) (dépréciation)
* 🦣 settings-hidden-screens : non-affichage d’écrans de paramètres (liste) (dépréciation)
* 🦄 default-to-global-view : utilisation par défaut de la vue globale (expérimental)
* 🦄 enable-intermediate-anonymisation : activation de la possibilité d’anonymisation intermédiaire (désormais activé par défaut)
* 🍄 include-sendmail-custom-from-option : activation de l’option d’un entête "From" personnalisé sur l’action d’envoi de courriel (dangereux)
* 🍄 ignore-hard-limits : suppression des limites sur le nombre de champs etc. (dangereux)
* 🦄 force-lazy-mode : emploi exclusif du mode "lazy" pour les évaluations (expérimental)
* 🦄 enable-card-identifier-template : activation de la possibilité d’identifiants personnalisés sur les fiches (désormais activé par défaut)
* 🦄 workflow-status-loop : activation du système de répétition des actions d’un statut (expérimental)
* 🦄 enable-workflow-tests : activation des tests de workflow (expérimental)

# Sécurité du SaaS et conformité au RGPD

Sécurité du SaaS et conformité au RGPD

Entr'ouvert s’engage à mettre en œuvre les mesures de sécurité visant apporter une protection suffisante des données à caractère personnel. Ces mesures portent à la fois sur les données à caractère personnel confiées et sur les mesures générales de sécurité du système.

Les mesures de protection sur les données à caractère personnel

Les mesures mises en œuvre par Entr'ouvert sont adaptées à la sécurité des données confiées.

Sécurité des données

Nous respectons le principe de base de la protection des données qu'est la proportionnalité des mesures préventives - l'envergure de ces mesures étant directement liée à la criticité des données à caractère personnel collectées et traitées dans l'environnement Publik.

Notre moteur de base de données est le SGBDR (système de gestion de bases de données relationnelles) PostgreSQL, outil libre, reconnu pour sa robustesse et sa sécurité.

Nos bases de données, comme le reste de l'infrastructure Publik, sont situées sur des machines physiques hébergées par notre sous-traitant OVH, et accessible seulement à l'aide du protocole SSH par clé RSA (pas d'authentification par mot de passe, jugée d'une sécurité trop faible) par les administrateurs d'Entr'ouvert.L'ensemble de clés autorisées est maintenu de façon cohérente. Par exemple, lorsqu'un technicien quitte l'équipe, sa clé est désactivée.

Nos bases de données sont aussi sauvegardées toutes les nuits et ces sauvegardes sont stockées sur un site tiers.

Des sauvegardes quotidiennes sont conservées une semaine, et des sauvegardes mensuelles quatre mois. Les sauvegardes sont détruites au delà de ce délai.

Les mêmes critères de conservation sont appliqués à la sauvegarde des fichiers situés sur le système de fichier réseau NFS (Network File System).

Ces sauvegardes nous permettent entre autres de rétablir un état cohérent des bases de données en cas de compromission des données stockées.

Moyens de chiffrement employés pour les flux de données intégrés dans le traitement

Les communications se font en HTTPS (HTTP sur TLS).Le certificat HTTPS est soit délivré par la collectivité, soit obtenu via une autorité de certification reconnue (LetsEncrypt, par exemple).

D'un point de vue applicatif, l'interface entre logiciels métiers externes et la fabrique de formulaire contenant les données des utilisateurs se fait à l'aide de requêtes nécessairement signées, réduisant les risques d'usurpation d'identité numérique de l'un de ces logiciels.

Les signatures, de type HMAC (Hashed Message Authentication Code), se basent sur la fonction de hachage SHA-256 (Secure Hash Algorithm, produisant des hachés de 256 bits de longueur), considérée cryptographiquement robuste selon les critères en vigueur de nos jours.

Procédures garantissant que des tiers ne puissent pas avoir accès aux données confiées

Outre les procédures de chiffrement décrites plus haut, nous développons nos applications à l'aide du framework Django.

Ce dernier propose des mécanismes de prévention des attaques usuelles sur le Web ; notamment la prévention contre injections SQL, les scripts inter-site (Cross site-scripting, XSS), le forgeage de requêtes inter-site (Cross-site request forgery, CSRF).

Enfin, la partie publique des clés SSH autorisées à accéder aux différents serveurs est centralisée dans notre dépôt utilisé par l'outil de gestion de configuration de serveur Puppet.Le retrait d'une clé, par exemple lorsque quelqu'un se voit retirer ses accès aux serveurs, se fait de façon directe et est appliqué à l'ensemble de notre infrastructure.

L’anonymisation des données

L'anonymisation des données des utilisateurs est paramétrable dans Publik.

Les mécanismes d'anonymisation sont les suivants :

* anonymisation des données métiers et des données personnelles, par simple effacement des données contenues dans les champs.
* les métadonnées relatives aux demandes des usagers sont aussi anonymisées.Parmi ces métadonnées figurent le contexte de soumission de la demande, l'identifiant de l'usager associé à cette demande, ainsi que les rôles destinataires et les données de workflow. Une fois anonymisées, les demandes servent encore à des fins statistiques, elles sont injectées dans l'outil de business-intelligence (BiJoe).

D'une façon générale, le RGPD impose au minimum l'anonymisation (quand ce n'est pas la suppression) des données dès lors que leur conservation n'est plus utile au traitement auquel l'usager a consenti.

Les formations données par nos chefs de projets aux administrateurs fonctionnels, formations relatives à la construction des démarches en ligne avec Publik, tiennent compte de cette nécessité d'anonymiser les demandes contenant des données à caractère personnel.

Le cloisonnement des données

Le cloisonnement des données dans l'architecture Publik repose principalement sur les propriétés de multitenancy de notre moteur de base de donnée relationnelle PostgreSQL.

Le multitenancy (i.e. « multi-hôte ») permet à PostgreSQL d'assurer la séparation des données de plusieurs sites d'une même application.

Dans le cadre d'une installation Publik multi-collectivités, le système de contrôle d'accès basé sur les rôles (Role-Based Access Control, RBAC) permet de s'assurer que les données d'une collectivité restent cloisonnées à cette collectivité et aux rôles qui y sont liés (et donc qu'elles ne puissent pas être lues par un membre d'un autre collectivité de l'instance Publik, ce membre ne possédant pas les rôles adéquats).

Le contrôle des accès logiques

Le fournisseur et gestionnaire d'identités de Publik, Authentic, reprend et étend les mécanismes de contrôle d'accès du framework Django.

Ce fournisseur définit un ensemble de rôles techniques, pour sa gestion en interne, et un ensemble de rôles métiers, voués à être approvisionnés dans les autres briques du logiciels Publik.

Authentic assure aussi l'authentification des comptes usagers de Publik.

Il fournit un mécanisme d'authentification modulaire. Ainsi, l'usager s'identifie par login/mot de passe, ou bien, si Authentic est configuré pour, via un fournisseur d'identités tiers (lequel proposera alors indépendemment de Publik ses propres moyens d'authentification).

Le choix d'un mot passe pour l'authentification d'un usager doit respecter les contraintes suivantes : 8 caractères au minimum, dont au moins une lettre minuscule, un chiffre et une lettre majuscule.

La politique de complexité des mots de passe est paramétrable.Il est aussi possible d'activer un temps d'attente exponentiel après chaque tentative d'authentification infructueuse.

Enfin, le support de l'authentification à plusieurs facteurs est en voie de développement dans notre fournisseur d'identités Authentic.

La politique de journalisation

Une fonction de journalisation des actions impliquant les logiciels métiers externes est mise en place directement dans la base de connecteurs Passerelle.

Par ailleurs, une application de journalisation pour le fournisseur d'identité est en cours de développement.

La politique d’archivage

La conservation des données des systèmes de fichiers réseau inclut l'ensemble des logs Web et applicatifs.

Ces données, bien évidemment à caractère personnel, et à valeur juridique potentielle, bénéficient de la même politique de conservation stricte des sauvegardes des données des serveurs de l'architecture Publik.

La politique de sécurisation des documents papiers

Nous ne proposons pas de service impliquant une gestion de documents au format papier.

La politique de minimalisation des données collectées

La réduction de la collecte des données à ce qui est strictement nécessaire pour mener à bien le traitement fait partie de notre activité d'accompagnement à la conception des démarches dans Publik.

Les formation à la conception de ces démarches ont pour objectif majeur la sensibilisation à la nécessité de minimaliser la collecte de données.

Les cookies

Les cookies utilisé par Publik ne nécessite aucune demande de consentement (ils ne servent pas au traçage des activités de l'utilisateur, mais seulement à des fins techniques d'authentification).

Plus d'informations ici :Cookies et traceurs

Les mesures générales de sécurité du système

La sécurisation de l'exploitation

L'architecture redondée propose une conteneurisation des applications formant l'environnement Publik. Ces applications sont présentes sur chacun des deux serveurs de notre SaaS.La base de données est elle aussi redondée, sur les deux serveurs.

La charge des requêtes Web est répartie entre les deux nœuds du système redondé, et l'attribution à l'un ou l'autre des deux nœuds se fait en fonction de l'adresse IP du terminal de l'usager.

Cette répartition de charge est à la fois disponibles sur les plateformes de développement, de recettes et de production, et les spécifications matérielles de celles-ci sont adaptées à cette charge :

* Plateforme de développement :Processeur : Intel Xeon E5-1660v3 - 8c/16t - 3GHz /3,5GHzMémoire vive : 128Go DDR4 ECC 2400 MHzDisque : 1,2TB SSD NVMe
* Plateformes de recette et de production :Processeur : Intel 2 x Xeon E5-2640v3 - 16c/32t - 2,6GHz /3,4GHzMémoire vive : 128Go DDR4 ECC 1866 MHzDisque : 1,2TB SSD NVMe

Les principaux logiciels utilisés et maintenus à jour sont :

* le système d'exploitation Debian.
* la gestion de configuration des serveurs par Puppet.
* la réplication des données sur périphériques de bloc, par DRBD.
* la répartition de charge par HAProxy.
* le serveur Web nginx.
* l'interface uWSGI entre service Web et applications.
* le framework Web Django.
* nos propres applications formant l'environnement Publik.

Les mises à jour se font à l'aide du gestionnaire de paquets Debian, apt.

Un système de monitorage (Nagios) des serveurs permet de prévenir et détecter les différents pannes envisageables (serveur down ou saturation de l'espace mémoire RAM ou de l'un des disques notamment).

La limitation des accès physiques au matériel est assurée par notre hébergeur sous-traitant OVH, conformément à ses mesures prises pour le respect de la réglementation européenne en vigueur (https://www.ovh.com/fr/protection-donnees-personnelles/securite.xml).

La lutte contre les logiciels malveillants

Nos services sont déployés sur des machines constamment maintenues à jour (via les dépôts officiels Debian) et accessibles pour administration seulement en SSH (avec clé seulement, pas d'authentification par mot de passe acceptée), réduisant ainsi les risques d'attaque par force brute (attaquer par force brute un mot de passe d'une dizaine de caractère de longueur est très largement faisable, mais en faire de même pour la partie privée d'une clé RSA de 2048 ou 4096 octets de longueur est en pratique fantaisiste).

Nous utilisons strictement des logiciels libres reconnus pour leur rigueur dans la prise en compte des principes de sécurité, et notamment pour la rapidité de fourniture de correctifs logiciels en cas de faille nouvellement identifiée (Common Vulnerability Exposures ou CVE)

Par ailleurs, notre hébergeur OVH s'engage aussi à nous envoyer une alerte courriel dès lors qu'un de leurs outils de monitorage, installés sur nos serveurs, requiert une mise à jour de sécurité.

La gestion des postes de travail

Les mêmes critères de sécurité sont appliqués sur les postes de travail : machines à jour, exécutant des logiciels libres reconnus pour leur rigueur dans la prise en compte des principes de sécurité.

La protection des sites web

Nous utilisons une version de support à long-terme (LTS) de Django.

Les mesures de sécurité prescrites ici sont gérées par ce framework, qui fonctionne dans une version maintenue à jour sur notre SaaS.

Comme décrit plus haut dans ce document, ce framework inclut les mécanismes de sécurité adéquats pour faire face aux tentatives d'attaque usuelles sur le Web (injections SQL, session-hijacking, XSS, CSRF, etc.)

La sauvegarde des données

La haute-disponibilité des services Publik est assurée par la redondance de l'architecture publique sur notre plateforme SaaS, laquelle bénéficie d'un système de répartition de charge (HAProxy).

L'ensemble des services composant l'environnement Publik sont donc redondés, permettant la continuité en cas de panne (logicielle ou matérielle) d'un des services.Outre les sauvegardes quotidiennes décrites plus haut, la conservation des transactions récentes sur la base de données permet le rejeu de ces transactions sur le serveur Postgres, assurant ainsi, en cas d'attaque ou d'incohérence des données, un rétablissement de la base à l'instant voulu.

Notre hébergeur OVH assure aussi l'intégrité et la disponibilité des services par diverses mesures telles que la redondance des liaisons réseau, leur propre système de backup et la mise en place de groupes électrogènes de secours assurant plusieurs dizaines d'heures d'autonomie pour leurs sites hébergeant leurs salles serveurs.

La maintenance

Tout ce qui est de l'ordre de la maintenance physique est assuré par notre hébergeur sous-traitant OVH. OVH assure une maintenance physique « au mieux », pour assurer une disponibilité des services 24/7.

Notre hébergeur OVH dispose d'un mécanisme de détection et prévention des attaques par déni de service distribuées (DdoS).

Sur l'ensemble de notre serveur, toute opération jugée suspecte provoque l'envoi d'un mail d'alerte à l'administrateur du serveur. Une restriction des adresses IP à une ensemble d'adresses connues ou préalablement déclarées est en place pour l'accès en SSH aux machines.

Les mesures de sécurité physique

Les mesures de sécurité physiques sont prises par notre hébergeur OVH et sont détaillées sur leur documentation en ligne (https://www.ovh.com/fr/protection-donnees-personnelles/securite.xml).

La mise en place d’une traçabilité

Les erreurs applicatives Django provoquent l'envoi d'un rapport d'erreur à l'adresse électronique de l'administrateur technique de l'application.

En interne, un recueil de fiches post-accident (« postmortem ») contenant les mesures correctrices prises est maintenu à jour en continu.

Les mesures de sécurisation des matériels

La sécurisation du matériel utilisé par les employés fait écho aux mesures prises en termes de cloisonnement et de traçabilité décrites plus haut.

Une clé SSH par poste et par employé est utilisée pour l'accès aux serveurs, permettant une gestion aisée des accès (octroi ou révocation des droits d'accès aux serveurs, notamment).

Par ailleurs, aucune donnée des usagers n'est stockée sur support amovible.

Notre hébergeur OVH s'engage aussi à maintenir une politique de sécurisation des accès physiques, telle que disponible dans leur documentation (cfhttps://www.ovh.com/fr/protection-donnees-personnelles/securite.xml→ 16. Gestion des accès physiques des tiers → Engagements pris par OVH en sa qualité d'hébergeur).

Les mesures proposées visant à éloigner les risques

Les mesures de sécurité face à des risques physiques sont prises par notre hébergeur sous-traitant OVH. Des mesures matérielles telles que la redondance des alimentations électriques, des supports mémoires, des systèmes de refroidissement notamment, sont prises par OVH.

Par ailleurs, notre architecture redondée est répartie entre deux sites géographiques différents, permettant de répondre aux risques d'altération de données ou d'indisponibilité des services sur l'un des deux sites. Les sauvegardes se situent quant à elles sur un autre site géographique encore.

Les audits de sécurité

Des audits de sécurité sont possibles sur les plates-formes destinés à cet usage. Ils peuvent être conduits sur la plate-forme de test existante ou sur une plate-forme dédiée commandée à Entr'ouvert.

En revanche, notre SaaS de production contient des données personnelles et doit garantir en permanence le meilleur niveau de service; Nous n'autorisons pas qu'il soit chargé, stressé par des actions visant à le dégrader et n'est donc pas ouvert aux audits.

# Infrastructure d’hébergement SaaS « Entr'ouvert OVH »

Infrastructure d’hébergement SaaS « Entr'ouvert OVH »

Description

L'infrastructure de l'hébergement mutualisée par Entr'ouvert, pour ses clients ayant contracté un abonnement, est composée de serveurs répartis sur les centres de données français d'OVH (Roubaix, Gravelines) en accès et sauvegarde. Nos services sont redondants et répliqués en continu afin d'assurer une disponibilité permanente :une instance de Publik opérationnelle, à jour, toujours accessible par les usagers et les agents traitants.

Sécurité des données¶

* Les centres de données OVH sont certifiésISO 27001.
* Un service fiable et performant, sans perte de donnée.
* Les services sont redondants et répliqués en continu. Chaque nœud d'un cluster Publik dispose d'une copie synchrone de la base de donnée (PostgreSQL hot-standby) et d'une synchronisation en temps réel des données (réplication DRBD). En cas de dysfonctionnement d'une machine, la continuité du service et l'intégrité des données sont assurées par une procédure de bascule éprouvée.
* Les services sont supervisés : une supervision générale est assurée par des agents logiciels qui remontent les informations sur la plateforme de surveillance et alertent les administrateurs d’Entr’ouvert en temps réel.
* Des audits de sécurité sont régulièrement réalisés par des opérateurs indépendants.
* Des backups complets sont réalisés sur une machine isolée hors site ; le système de restauration est quotidiennement vérifié.
* Archivage continu des base-de-données et récupération de données à la minute (Point-in-time recovery).
* Temps d'intervention très rapide suite à un incident bloquant : <2h.
* Disponibilité garantie : > 99,5% (99,97% constatés en 2021), les temps d'interruption relevant presque exclusivement de mises à jour nocturnes planifiées les seconds et quatrièmes jeudi de chaque mois. Une page «Publik : offre SaaS — systèmes en production» affiche la disponibilité des services (briques logicielles composant Publik) en temps réel.
* Réversibilité : Entr'ouvert s'engage à vous restituer l'intégralité de vos données lorsque vous quittez la plateforme. Les logiciels et les spécifications permettant d'exploiter ces données sont libres. Les données vous appartiennent.
* Plan de continuité d'activité (PCA) : perte de données maximale admissible (PDMA/RPO) de 24 heures ouvrées.
* Plan de reprise d'activité (PRA) : perte de données maximale admissible (PDMA/RPO) de 48 heures ouvrées.

Nous avons une page plus détaillée concernant lasécurité du SaaS et le respect du RGPD.

Matériel¶

Les machines physiques sont robustes, elles sont issues de l'offrehaut de gamme d'OVH:

* ces machines sont équipées d'un matériel redondant (alimentation double, disques durs RAID 1) avec d'importantes capacités en matière de CPU (au moins 16 cœurs) et de mémoire vive (au moins 128Go). Ces machines sont remplacées régulièrement en partant toujours sur l'offre la plus puissante disponible afin de garantir les meilleures performances et de supporter sans délai des montées en charges brusques ;
* ces machines disposent de disques ultra-rapides (SSD) pour fournir des espaces disques locaux véloces si nécessaire (espace système, espaces temporaires) ; ainsi que de disques rapides (SAS ou SATA) pour des espaces de stockages locaux importants (backups locaux, fichiers transitoires) ;
* en termes de sécurité réseau, un pare-feu est présent sur chaque machine physique, Les flux sont filtrés par défaut et ouvert uniquement au cas par cas. Une surveillance « fail-to-ban » coupe les IP qui tentent des connexions non autorisées. L’hébergeur des machines physiques assure par ailleurs une protection anti-DDOS.

Environnements¶

Nous maintenons deux environnements Publik : test et production. Ils présentent les mêmes caractéristiques en termes de configuration et de disponibilité. Les instances de recette et de production sont strictement identiques, excepté les données hébergées et des dates de mises-à-jour.

# Présentation d’une brique¶

Présentation d’une brique¶

Une brique Entrouvert est un paquet Debian standard issu d’un module Python standard. C’est un logiciel libre dont vous pouvez obtenir et modifier les sources selon vos besoins. Les fichiers d’installation sont posés dans /var/lib/mabrique, et les fichiers de configuration sont placés dans /etc/mabrique. Les services et les journaux des briques sont pilotés par systemd.

Utilisation de cadriciels (frameworks)¶

Chaque brique logicielle est une application Python/Django – à l’exception de la brique w.c.s. qui utilise le cadriciel Quixote.

L’utilisation d’unframeworkpermet de disposer d’un ensemble de composants afin de développer plus rapidement, mais aussi de manière plus homogène, et surtout en assurant à tout moment une excellente sécurité de l’application. C’est en effet le framework qui :

* reçoit les données, les interprète et les valide avant de les envoyer à l’application ;
* permet de contrôler l’envoi des données aux bases de données par l’application (pas de requêtes SQL directes) ;
* sécurise les sorties de l’application (HTML) en imposant un contrôle fort sur les données affichables.

Dans Publik, en plus de l’utilisation de toutes les possibilités de Django d’autres protections sont mises en place :

* isolation des composants (chaque composant est une brique logicielle indépendante) ;
* chaque brique dispose de sa propre base de données, complètement isolée des autres (chaque base peut même être hébergée sur un serveur propre) ;
* chaque brique peut gérer plusieurs sites (mode multi-tenants), dans ce cas chaque site dispose d’un « tenant » dans la base de données sous forme d’un schéma PostgreSQL : chaque site est donc indépendant et isolé ;
* utilisation du front-end nginx pour diffuser tous les éléments statiques des applications ;
* connexion de l’application via le protocole wsgi pour un premier filtrage des requêtes (les requêtes invalides sont rapidement éliminées).

D’une façon générale, Publik utilise au maximum des composants éprouvés : le code des applications se concentre uniquement sur la logique de celles-ci. Il s’agit de suivre les principes DRY (Don’t Repeat Yourself) et KISS (Keep It Simple Stupid) afin de mieux sécuriser l’application : la sobriété recherchée par Publik est aussi présente dans le code du logiciel.

Dialogue entre les composants¶

Le schéma ci-dessus montre que l’application n’est pas en contact « direct » avec l’extérieur. Elle utilise toujours des composants logiciels soit éprouvés (celery, requests, tenant-schemas), soit communs à toutes les briques (hobo, mellon).

Dialogues entre briques¶

Les briques de Publik dialoguent via deux canaux :

* webservices (HTTPS JSON) pour ce qui concerne l’échange de données
* messages (AMQP) pour ce qui concerne la gestion des utilisateurs et des rôles,i.e.le provisioning au travers des différents composants

Par ailleurs, SAML est utilisé pour ce qui concerne le WebSSO (le dialogue se déroule via le navigateur de l’usager).

Chemin d’une requête¶

Une requête Publik chemine typiquement par les services suivants :

service web (nginx) :

* dispose d’un certificat SSL
* dispose des composants Publik
* interroge la base de donnée et répond aux requêtes des utilisateurs

service de base de données (PostgreSQL) :

* enregistre et restitue les données des applications,

# Haute disponiblité

Haute disponiblité

Ce chapitre présente des moyens permettant d’ajouter de la redondance en vue de garantir une meilleure disponibilité d’une installation de Publik. La charge du travail des logiciels de Publk est répartie sur plusieurs machines. Le service est maintenu en cas de panne de l'une d'entre elles.

Pré-requis

On décrit ici une installation avec deux frontaux, on aura donc besoin de :

* deux «frontaux», machines hôtes identiques (ici nomméesweb1etweb2) qui feront tourner les logiciels «briques»
* un service HAProxy en amont
* un service de base de données PostgreSQL
* un service de partage de fichiers NFS
* un système de gestion de configuration pour les frontaux (puppet, ansible, cfengine, chef, etc.).

Installation des composants («briques»)

Création des utilisateurs avec UID identiques sur tous les frontaux

Lors de partage de fichiers sur un réseau (NFS par exemple), il faut que les UID des utilisateurs Unix concernés par Publik soient les mêmes sur les deux machines web1 et web2. Cela peut se faire avec un script tel que :

#!/bin/sh

uid=2102

for user in hobo hobo-agent authentic-multitenant wcs passerelle combo fargo chrono lingo bijoe welco
do
    echo "create group $user ($uid)"
    addgroup --system --gid $uid $user
    echo "create user $user ($uid)"
    adduser --disabled-password --system --uid $uid --gecos "$user daemon" --ingroup $user --no-create-home --home /var/lib/$user $user
    uid=$(($uid+1))
done

Mais il est fortement recommandé que cela soit géré par un système de gestion de configuration (ansible, puppet, etc.).

Partage NFS des données /var/lib/composant

Les répertoires/var/lib/composantsont des montages NFS, donc partagés entre les frontaux. Ils appartiennent, chacun, à l'utilisateur Unix dédié.

Le système NFS doit être capable de gérer leslocks(attention notamment au réglage d'un éventuel pare-feu entre le serveur et les clients NFS).

Configuration des accès PostgreSQL

Avant l’installation des modules, il faut pour chacun d’eux (sauf w.c.s.) configurer l’accès a sa base PostgreSQL; par exemple, dans/etc/combo/settings.d/database.py:

# /etc/combo/settings.d/database.py
DATABASES['default']['NAME']='combo'DATABASES['default']['USER']='combo'DATABASES['default']['PASSWORD']='mot-de-passe-base-combo'DATABASES['default']['HOST']='serveur-sql-primaire'DATABASES['default']['PORT']='5432'

Mettre en place la même configuration pour tous les services.

Désactivation des crons sur tous les frontaux sauf un

Le système decronsde Publik ne sait pas fonctionner en parallélisation : il ne doit être laisséactif que sur un seul frontal.

Il faut donc désactiver les crons sur tous les autres frontaux pour tous les composants, à travers des fichiers /etc/composant/settings.d/disable_cron_jobs.py :

# /etc/combo/settings.d/disable_cron_jobs.pyDISABLE_CRON_JOBS = True

Installation des composants

Lancer l’installation des composants packagés. Attention, lors de cette étape, toujours refuser les éventuelles demandes de modification des fichiers de configuration :

apt install publik-base-theme
aptinstallhobo hobo-agent
aptinstallwcswcs-au-quotidien
aptinstallauthentic2-multitenantaptinstallcomboaptinstallpasserelleaptinstalllingo

Paramétrage du partage de fichiers

Pour s'assurer que le démarrer les services ne se fait qu'après le montage de NFS, on ajoutera un paramètreRequiresMountsFor=à la description du service. Exemple pour Combo :

#/etc/systemd/system/combo.service.d/wait-for-mnt-data.conf[Unit]RequiresMountsFor=/var/lib/combo

# Dépendances logicielles¶

Dépendances logicielles¶

Service de base de données¶

Chaque brique utilise une ou plusieurs bases de données PostgreSQL.

Composants logiciels sous-jacents¶

Publik est un logiciel développé en Python, sur le framework Django. Il est développé et testé pour fonctionner sur un système d’exploitation Debian GNU/Linux.

Le frontal web recommandé est nginx, bien que Publik puisse fonctionner avec Apache et d’autres serveurs HTTP. La liaison entre les applicatifs Python et le frontal web est assurée par uWSGI.

Les différents composants (briques) de Publik échangent des messages AMQP via RabbitMQ.

Publik nécessite PostgreSQL (version 11 ou supérieure) sur lequel chaque brique disposera de sa base de données propre.

Un système de cache compatible Django est nécessaire, memcached étant conseillé.

Certificats X509¶

La diffusion HTTPS étant obligatoire, il est nécessaire de disposer de certificats valides pour chaque brique déployée ; chacune des briques utilisant un nom de serveur distinct. En général, un certificat étoile (wildcard*.example.net) couvre toutes les briques.

# Création des bases de données¶

Création des bases de données¶

Vue générale¶

Chaque brique utilise une ou plusieurs bases de données PostgreSQL. Il est courant d’utiliser une installation à deux machines identiques en master/slave. Publik peut utiliser un système PostgreSQL existant, le cas échéant. Publik nécessite PostgreSQL version 11 ou supérieure (pour rappel, le support de PostgreSQL est d'environ 5 ans après la sortie d'une nouvelle version majeure).

Installation de PostgreSQL¶

Vérifier que les extensions PostgreSQL est installé :

aptinstallpostgresql

Création automatisée des bases de données¶

Nous proposons un script pour la création des bases de données (distribué via le paquet publik-common), l’utilisation standard s’adresse à un cluster postgresql local :

publik-create-databases

Création manuelle des bases¶

Chaque composant Publik doit disposer :

* d’une base de données dédiée,
* d’un accès spécifique à cette base via un usager postgreSQL dédié (avec un mot de passe SQL à créer pour chaque composant).

Principe pour le composantcombo :

CREATEUSERcomboPASSWORD'indiquer-ici-le-mot-de-passe-pour-combo';CREATEDATABASEcomboWITHOWNER=comboTEMPLATE=template0LC_COLLATE='fr_FR.UTF-8'LC_CTYPE='fr_FR.UTF-8';

Remarques :

* template0etLC_COLLATEetLC_CTYPEnécessaires parce que template1 est en en_US.UTF-8.
* pour le module authentic2-multitenant, le nom du rôle estauthentic-multitenantet le nom de la base estauthentic2_multitenant(adaptez les commandes précitées comme suit :CREATEUSER"authentic-multitenant"...)

La même opération doit être répétée pour chaque brique logicielle (bien sûr à chaque fois il fautnoter le mot de passechoisi, il sera nécessaire par la suite) :

* Combo
* Hobo
* Authentic
* Passerelle
* Fargo
* Bijoe
* Chrono

Pour étendre les possibilités de recherche plein texte, il est également utile d’activer l’extension « unaccent » dans la base de données Combo :

CREATEEXTENSIONunaccent;

Sur la base de données authentic, activer les extensions suivantes :

CREATEEXTENSIONunaccent;CREATEEXTENSIONpg_trgm;

Une brique est spécifique : w.c.s.. Pour w.c.s., il n’y a pas besoin de création d’une base, elle sera effectuée lors de l’instanciation. En revanche, l’utilisateur w.c.s. sur PostgreSQL doit avoir le droit CREATEDB, donc :

CREATE USER wcs PASSWORD 'indiquer-ici-le-mot-de-passe-pour-wcs' CREATEDB;

Sauvegarde

La mise en place d'un système de sauvegarde de la base de données est primordiale. Il est très fortement recommandé d'utiliser une solution de sauvegarde existante et éprouvée plutôt que de réaliser votre propre système. Nous utilisons pour notre offre SaaS le logiciel pgbackrest.

En cas de difficultés, nous vous invitons à contacter les entreprises spécialisées en support de PostgreSQL.

# Mises à jour des composants¶

Mises à jour des composants¶

Fréquence des mises à jour¶

Entr’ouvert livre une nouvelle version de Publik les soirs des 2ème et 4ème jeudi de chaque mois. L’installation peut être faite aussitôt, mais nous conseillons à des hébergeurs tiers non infogérés par Entr’ouvert de faire la mise à jour le mardi suivant.

La mise à jour provoque une courte indisponibilité du système : elle doit être faite sur des heures de faible affluence.

Déroulé en installation double (load-balancing)¶

S’agissant d’une installation double (load-balancing entre web1 et web2), la procédure générale à suivre est :

* arrêt du frontal nginx sur web2 ⇒ HAProxy envoie tout sur web1,
* vérifier que PostgreSQL est bien fonctionnel,
* mise à jour de web1 (procédure ci-dessous),
* vérification du fonctionnement du site (parcours de 3 ou 4 URLs),
* mise à jour de web2,
* relance du frontal nginx sur web2,
* vérification du fonctionnement du site (parcours de 3 ou 4 URLs).

Attention : si un service de Publik est redémarré alors que PostgreSQL n’est pas disponible, ce démarrage ne fonctionnera pas. Il faudra redemander le démarrage explicitement. Ceci signifie qu’il est très fortement conseillé de faire la mise à jour de Publik indépendamment de celle de PostgreSQL. Entr’ouvert conseille de faire la mise à jour de PostgreSQLavantles composants de Publik.

Les composants de Publik sont livrés sous forme de paquet Debian, leur mise à jour suit la procédure classique :

# apt update# apt full-upgrade

Mise à jour PostgreSQL¶

La mise à jour de PostgreSQL peut être faite à chaud selon les procédures Debian normales. Durant la mise à jour, les services ne fonctionneront pas (réponses 5xx) et HAProxy délivrera une erreur « maintenance ». Dès le redémarrage de PostgreSQL, les services Publik rétabliront les connexions vers le serveur SQL et le système sera à nouveau utilisable.

Attention : si un service de Publik est démarré ou redémarré alors que PostgreSQL n’est pas disponible, ce démarrage ne fonctionnera pas. Il faudra redemander le démarrage explicitement.

# Déploiement des instances¶

Déploiement des instances¶

Attention, le déploiement ne doit être lancé que si TOUS les services ont été testés et répondent des 404 aux adresses prévues.

Cela signifie notamment, niveau infrastructure, que les entrées DNS, le/les certificats et les frontaux HTTP (haproxy et/ou nginx) sont déjà en place.

Avant de déployer une instance, il faut préparer 2 fichiers de configuration :

- le fichier modele.zip pour la configuration spécifique wcs

- le fichier recipe.json pour la configuration des instances sur les différents services

Préparation, création du fichier «modele.zip»¶

Le fichier de déploiement ci-dessous mentionne un fichier template,modele.zip, nécessaire au paramétrage de W.C.S lors du déploiement. Ce fichier zip doit être placé dans /var/lib/wcs/skeletons, il doit contenir un fichiersite-options.cfget un fichierconfig.json, voir les exemples ci-dessous.

Pourconfig.json:

{"debug":{"error_email":"admin@yourdomain.com"},"emails":{"from":"noreply@yourdomain.com"},"language":{"language":"fr"},"misc":{"charset":"utf-8","homepage-redirect-url":"[portal_url]"},"postgresql":{"createdb-connection-params":{"database":"postgres","host":"your.postgres.db.host","port":"5432","user":"yourdbuser","password":"yourdbpassword"},"database-template-name":"wcs_%s","host":"your.postgres.db.host","port":"5432","user":"yourdbuser","password":"yourdbpassword"}}

L‘utilisateur postgres mentionné doit avoir le droit de créer une base de donnée.

Poursite-options.cfg:

[options]default-to-global-view = true
# remove/disable/hide deprecated elementsworkflow-functions-only=truesettings-disabled-screens = storage, identification, session, theme, template, users
disabled-workflow-actions = aggregationemail, jumponsubmit
disabled-fields = ranked-items, table, table-select, tablerows
disable-python-expressions = true
forbid-python-expressions = true
disable-jsonp-sources = true
disable-workflow-form-to-workflow-data = true
disable-internal-statistics = true

Préparation, création du fichier «recipe»¶

Création d’un fichier de déploiementrecipe-macollectivite-prod.json(note : fichier déjà disponible sur l’infra de pré-prod); la ligne « password » est à compléter.

{"variables":{"hobo":"hobo-moncompte.macollectivite.fr","authentic":"connexion-moncompte.macollectivite.fr","combo":"moncompte.macollectivite.fr","combo_agent":"agents-moncompte.macollectivite.fr","passerelle":"passerelle-moncompte.macollectivite.fr","wcs":"demarches-moncompte.macollectivite.fr"},"steps":[{"create-hobo":{"url":"https://${hobo}/"}},{"create-superuser":{"email":"admin+macollectivite@entrouvert.com","password":"..."}},{"create-authentic":{"url":"https://${authentic}/","title":"Connexion"}},{"set-idp":{}},{"create-combo":{"url":"https://${combo}/","title":"Compte citoyen","template_name":"portal-user"}},{"create-combo":{"url":"https://${combo_agent}/","slug":"portal-agent","title":"Portail agent","template_name":"portal-agent"}},{"create-wcs":{"url":"https://${wcs}/","title":"Démarches","template_name":"modele.zip"}},{"create-passerelle":{"url":"https://${passerelle}/","title":"Passerelle"}},{"set-theme":{"theme":"publik"}}]}

Lancement du déploiement¶

On utilise la commande «cook» proposée par le logiciel «hobo». Cette commande doit impérativement être exécutée par l’utilisateur «hobo», on utilise doncsudo -u hobo … :

# sudo -u hobo hobo-manage cook /chemin/vers/recipe-macollectivite-prod.json -v 2

Vérification du déploiement¶

A la fin du déploiement, les logiciels Publik Django packagés doivent avoir déployé les instances dans PostgreSQL (schémas visibles dans chaque base) mais surtout crée le répertoire contenant la configuration du site cible :

Ce qui est visible dans la plateforme de pré-production doit l’être sur la plate-forme de production, donc on doit voir ceci (en retirant lespreprod-) :

# ls -ld /var/lib/*/tenants/*drwxr-xr-x3authentic-multitenantauthentic-multitenant120Jul1215:19/var/lib/authentic2-multitenant/tenants/connexion-preprod-moncompte.macollectivite.frdrwxr-xr-x5combocombo156Jul2100:25/var/lib/combo/tenants/agents-preprod-moncompte.macollectivite.frdrwxr-xr-x5combocombo4096Jul2010:38/var/lib/combo/tenants/preprod-moncompte.macollectivite.frdrwxr-xr-x3fargofargo107Jul1018:19/var/lib/fargo/tenants/portedoc-preprod-moncompte.macollectivite.frdrwxr-xr-x3hobohobo81Apr1810:42/var/lib/hobo/tenants/hobo-preprod-moncompte.macollectivite.frdrwxr-xr-x3passerellepasserelle107Jul1018:19/var/lib/passerelle/tenants/passerelle-preprod-moncompte.macollectivite.frdrwxr-xr-x22wcswcs4096Jul1018:19/var/lib/wcs/demarches-preprod-moncompte.macollectivite.fr

w.c.s. créé directement une base de donnéeswcs_demarches_moncompte_macollectivite_fraccompagnée de son dossier dans/var/lib/wcs/tenants

Si les répertoires sont présents, alors :

* https://moncompte.macollectivite.fr : doit afficher une page « Votre installation de Combo fonctionne (…) Le site est actuellement vide (…) »,
* https://agents-moncompte.macollectivite.fr même chose,
* https://connexion-moncompte.macollectivite.fr : doit proposer une page de connexion avec un design proche de la pré-prod,
* https://passerelle-moncompte.macollectivite.fr : doit re-diriger vers le site connexion-moncompte précédent,
* https://hobo-moncompte.macollectivite.fr : même chose, redirection vers connexion-moncompte,
* https://portedoc-moncompte.macollectivite.fr : même chose, redirection vers connexion-moncompte,
* https://demarches-moncompte.macollectivite.fr : doit rediriger vers https://moncompte.macollectivite.fr/.

Configuration de la synchronisation automatique des rôles des comptes LDAP¶

Dans le fichier/var/lib/authentic2-multitenant/tenants/connexion-moncompte.macollectivite.fr/settings.json,pour l'annuaire des agents, rajouter les paramètresgroup_filteretgroup_to_role_mapping.

Le paramètregroup_filterliste recursivement les groupes LDAP dont le compte est membre:

"group_filter": "(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={user_dn})(sAMAccountName=*))"

Le paramètregroup_to_role_mappingcontient une liste de paramètres au format suivant:

["cn=Group1,ou=Groups,dc=maville,dc=fr", ["slug-du-rôle1", "slug-du-rôle2"]]

où le pemier paramètre est le DN du groupe dans l'annuaire et le deuxième paramètre est la liste des slugs des rôles à attribuer.

Ainsi, le fichier de configuration aurait la forme suivante:

{"LDAP_AUTH_SETTINGS":[{"realm":"mairie-macollectivite.fr","url":["ldap://v-dc1.vnan.intra/","ldap://v-dc2.vnan.intra/"],"basedn":"OU=macollectivite,DC=vnan,DC=intra","binddn":"xxxxx@vnan.intra","bindpw":"xxxxx","user_filter":"(&(objectClass=user)(sAMAccountType=805306368)(|(mail=%s)(samaccountname=%s))(|(memberOf=CN=.LD_Agents_BO,OU=macollectivite,DC=vnan,DC=intra)(memberOf=CN=.LD_Agents_Publik,OU=macollectivite,DC=vnan,DC=intra)))","username_template":"{samaccountname[0]}@{realm}","update_username":true,"active_directory":true,"attributes":["mail","sAMAccountName","cn","sn","givenName","userPrincipalName"],"external_id_tuples":[["samaccountname"],["dn:noquote"]],"shuffle_replicas":false,"require_cert":"never","use_tls":false,"set_mandatory_roles":["Agent"],"user_can_change_password":false,"group_filter": "(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={user_dn})(sAMAccountName=*))""group_to_role_mapping": [
                 ["cn=Group1,ou=Groups,dc=maville,dc=fr", ["slug-du-rôle1", "slug-du-rôle2"]],
            ]}]}

# Pilotage¶

Pilotage¶

Sans surprise, les commandes permettant la gestion des services demande qu'on soit formé à l'administration de système Debian.

Pilotage du frontal HTTP¶

C’est le service Nginx qui gère les requêtes HTTP, son pilotage se fait de façon classique :

# systemctl stop nginx# systemctl startnginx# systemctl restart nginx

À noter que lorsqu’un service Publik est coupé, Nginx renvoie des erreurs502 Bad Gateway. HAProxy réagit alors en tentant la requête sur l’autre machine. Si l’autre répond aussi 502, HAProxy peut afficher un message de maintenance.

Pilotage des services de Publik¶

Tous les services sont pilotables avec le systèmesystemdfourni par Debian.

Liste des services Publik en place :

* hobo: système de déploiement et de provisionning
* authentic2-multitenant: gestion d’identité et websso
* combo: CMS des portails usager et agent
* wcs: moteur de démarches (formulaires et workflows)
* passerelle: hub de webservices
* chrono: Module de gestion de rendez-vous et évènements
* lingo: Module de gestion de tarification et facturation
* supervisor(cas particulier pour le pilotage de hobo-agent)

Pour exemple, pilotage du service combo (portails) :

# systemctl stop combo# systemctl start combo# systemctl restart combo

S’agissant d’une installation dual, ces actions doivent être effectuées sur les deux machines.

# Installation des composants¶

Installation des composants¶

Publik est la somme de plusieurs composants qui communiquent entre eux via messages et webservices. Chaque composant est un paquet Debian qui s’installe depuis de dépôt Entr’ouvert.

Installation PostgreSQL¶

Lors de leur installation les briques s’attendent à trouver un service PostgreSQL fonctionnel, la configuration par défaut utilise un serveur local, dont l’installation a été vue dans la section précédente.

Vérifier que le service tourne :

# systemctl status postgresql@15-main.service
● postgresql@15-main.service - PostgreSQL Cluster 15-main
   Loaded: loaded (/lib/systemd/system/postgresql@.service; enabled-runtime; vendor preset: enabled)
   Active: active (running) since Tue 2021-01-12 16:01:30 CET; 7min ago
 Main PID: 22215 (postgres)
    Tasks: 7 (limit: 19660)
   Memory: 100.2M
   CGroup: /system.slice/system-postgresql.slice/postgresql@15-main.service
           ├─22215 /usr/lib/postgresql/11/bin/postgres -D […]
           ├─…

Installation RabbitMQ¶

RabbitMQ sera utilisé uniquement en local (127.0.0.1) et n’a besoin d’aucune configuration particulière.

# apt install rabbitmq-server

Il est utile ensuite de vérifier que le service tourne :

# systemctl status rabbitmq-server
● rabbitmq-server.service - RabbitMQ broker
  Loaded: loaded (/lib/systemd/system/rabbitmq-server.service; enabled)
  Active: active (running) since lun. 2017-07-17 10:09:57 CEST; 4 days ago
Main PID: 580 (beam.smp)
Status: "Initialized"

 CGroup: /system.slice/rabbitmq-server.service
 ├─ 580 /usr/lib/erlang/erts-6.2/bin/beam.smp [...]
 ├─ 897 /usr/lib/erlang/erts-6.2/bin/epmd -daemon
 ├─1780 inet_gethost 4
 └─1781 inet_gethost 4

Et que les journaux ne contiennent pas d’erreurs, ils doivent ressembler à :

# journalctl -u rabbitmq-server.service--Logsbeginatlun.2017-07-1710:09:46CEST,endatven.2017-07-2119:55:37CEST.--juil.1710:09:50web1-preprodsystemd[1]:StartingRabbitMQbroker...juil.1710:09:54web1-preprodrabbitmq-server[580]:RabbitMQ3.6.10.Copyright(C)2007-2017PivotalSoftware,Inc.juil.1710:09:54web1-preprodrabbitmq-server[580]:## ## Licensed under the MPL. See http://www.rabbitmq.com/juil.1710:09:54web1-preprodrabbitmq-server[580]:## ##juil.1710:09:54web1-preprodrabbitmq-server[580]:########## Logs: /var/log/rabbitmq/rabbit@web1-preprod.logjuil.1710:09:54web1-preprodrabbitmq-server[580]:###### ## /var/log/rabbitmq/rabbit@web1-preprod-sasl.logjuil.1710:09:54web1-preprodrabbitmq-server[580]:##########juil.1710:09:54web1-preprodrabbitmq-server[580]:Startingbroker...juil.1710:09:57web1-preprodrabbitmq-server[580]:systemdunitforactivationcheck:"rabbitmq-server.service"juil.1710:09:57web1-preprodsystemd[1]:StartedRabbitMQbroker.juil.1710:09:57web1-preprodrabbitmq-server[580]:completedwith0plugins.

Installation Combo¶

Dans/etc/combo/settings.d/database.pynous renseignons éventuellement les paramètres de connexion particuliers, par exemple le mot de passe ajouté à l’étape de création manuelle des bases :

DATABASES['default']['PASSWORD']="foobar"

Dans/etc/combo/settings.d/macollectivite.py, nous configurons l’envoi des traces d’erreur par l’ajout de ces lignes en fin de fichier :

ADMINS=(('Admin EO','admin+prod.macollectivite.combo@entrouvert.com'),)EMAIL_SUBJECT_PREFIX='[prod macollectivite combo] 'SERVER_EMAIL='admin+prod.macollectivite.passerelle@entrouvert.com'

On installe ensuite le logicielcombo:

# apt install combo

Vérification avecsystemctl status combo:

# systemctl status combo
● combo.service - Combo
   Loaded: loaded (/lib/systemd/system/combo.service; enabled)
   Active: active (running) since jeu. 2019-07-20 13:33:44 CEST; 19h ago
  Process: 16317 ExecStartPre=/usr/bin/combo-manage collectstatic --noinput (code=exited, status=0/SUCCESS)
  Process: 16319 ExecStartPre=/usr/bin/combo-manage migrate_schemas --noinput (code=exited, status=0/SUCCESS)
 Main PID: 16324 (uwsgi)
   Status: "uWSGI is ready"
   CGroup: /system.slice/combo.service
           ├─16429 combo uWSGI worker 1
           ├─16434 combo uWSGI worker 5
           ├─16436 combo uWSGI worker 3
           ├─16483 combo uWSGI worker 2
           ├─16421 combo uWSGI worker 4
           └─16324 combo uWSGI master

Installation Passerelle¶

La procédure est la même que pour Combo.

Dans/etc/combo/settings.d/database.pynous renseignons éventuellement les paramètres de connexion particuliers.

Dans/etc/passerelle/settings.d/macollectivite.py, configuration pour l’envoi des traces d’erreur par l’ajout de ces lignes en fin de fichier :

ADMINS=(('Admin EO','admin+prod.macollectivite.passerelle@entrouvert.com'),)EMAIL_SUBJECT_PREFIX='[prod macollectivite passerelle] 'SERVER_EMAIL='admin+prod.macollectivite.passerelle@entrouvert.com'

Nous pouvons ensuite installer le composant :

# apt install passerelle

Et vérification avecsystemctl is-active passerellequi doit montrer «active»

Installation Hobo serveur¶

Reprendre la même procédure que pour les autres composants, en adaptant le nom de la brique, c’est-à-dire :

* Éventuelle configuration des accès base de données
* Configuration du mail dans/etc/hobo/settings.d/macollectivite.py
* Installation du composant :# apt install hobo
* Vérification avecsystemctl is-active hoboqui doit retourner « active »

Installation Hobo agent¶

Il s’agit d’un composant qui va écouter les ordres de déploiement (ou provisionning) envoyés par le serveur Hobo et les exécuter sur les autres composants.

Installation :

# apt install hobo-agent

Ce démon est piloté par supervisor, ce dernier a parfois du mal à se lancer dès la première installation. On remet donc tout à plat avec :

systemctlstopsupervisorsystemctlstartsupervisor

Et on vérifie que hobo-agent est bien lancé par supervisor :

# systemctl status supervisor
● supervisor.service - LSB: Start/stop supervisor
 Loaded: loaded (/etc/init.d/supervisor)
 Active: active (running) since lun. 2017-07-17 10:09:52 CEST; 4 days ago
 CGroup: /system.slice/supervisor.service
 ├─1065 /usr/bin/python /usr/bin/supervisord -c /etc/supervisor/supervisord.conf
 ├─1208 python2.7 /usr/bin/celery worker --hostname=agent.%h --app=hobo.agent.worker --loglevel=INFO --concurrency=1
 └─1494 python2.7 /usr/bin/celery worker --hostname=agent.%h --app=hobo.agent.worker --loglevel=INFO --concurrency=1

Installation Authentic¶

Le système Authentic, un peu plus ancien que les autres composants, ne suit pas exactement les mêmes principes et les mêmes nommages.

Le nom du paquet à installer estauthentic2-multitenant:

* Configuration du mail dans/etc/authentic2-multitenant/settings.d/macollectivite.pyADMINS=(('Admin EO','admin+prod.macollectivite.authentic@entrouvert.com'),)EMAIL_SUBJECT_PREFIX='[prod macollectivite authentic] 'SERVER_EMAIL='admin+prod.macollectivite.authentic@entrouvert.com'
* Installation du composant :#apt install authentic2-multitenant
* Vérification avecsystemctl is-activeauthentic2-multitenantqui doit retourner « active »
* Vérification avecservice authentic2-multitenant status:

# systemctl status authentic2-multitenant
● authentic2-multitenant.service - Authentic 2 (multitenants)
   Loaded: loaded (/lib/systemd/system/authentic2-multitenant.service; enabled; vendor preset: enabled)
   Active: active (running) since Fri 2021-02-19 08:49:27 CET; 2 days ago
 Main PID: 11591 (uwsgi)
   CGroup: /system.slice/authentic2-multitenant.service
           ├─ 9944 authentic2-multitenant uWSGI worker 6
           ├─ 9946 authentic2-multitenant uWSGI worker 7
           ├─ 9949 authentic2-multitenant uWSGI worker 8
           ├─ 9950 authentic2-multitenant uWSGI worker 9
           ├─11083 authentic2-multitenant uWSGI worker 10
           └─11591 authentic2-multitenant uWSGI master

Installation w.c.s.¶

Comme noté précédemment le module w.c.s. est spécifique et n’a pas besoin de configuration initiale pour configurer ses mails, il y a donc simplement deux étapes :

* Installation du composant :# apt install wcs wcs-au-quotidien
* Vérification avecsystemctl is-active wcsqui doit retourner « active »

Installation de Nginx¶

# apt install nginx

… rien de plus. Nous installons la version de Debian 12 («bookworm»).

Configuration de base¶

L’installation de publik-commonn aura mis en place la configuration pour un format de log nginx avancé (qui affiche le tenant) dans/etc/nginx/conf.d/log_formats.conf:

# /etc/nginx/conf.d/log_formats.conflog_formatcombined_full'$remote_addr - $remote_user [$time_local] "$request" ''$status $body_bytes_sent "$http_referer" ''"$http_user_agent" "$host" [$request_time ms]';

Ainsi qu’un fichier/etc/nginx/conf.d/client-max-body-size.confpour contrôler la taille maximale des fichiers téléversables :

client_max_body_size200M;

Dans les installations où un serveur HAProxy serait posé en amont, il faudra adapter la configuration de celui-ci pour correspondre.

Mise en place des virtualhost (frontaux HTTP des tenants des composants Publik)¶

Le soin est laissé à l’installateur de décider comment poser les virtualhost ci-dessous dans nginx.

Au niveau de la preprod, le modèle classique a été adopté :

* un fichier par virtualhost dans/etc/nginx/sites-available/
* des liens symboliques dans/etc/nginx/sites-enabled/avec un préfixe *10_* permettant un éventuel classement d’autres services avant ou après.
* la terminaison SSL est assurée en amont et le traffic parvient non-chiffré à nginx.

A noter queces fichiersNginx de laplate-forme depré-productionpeuvent être copiéspour la plate-forme de production, il faudra cependant veiller à la modification du server_name du portail usagers dans le virtualhost « combo ».

Des fichiers type sont distribués dans le paquetpublik-common, dans le répertoire/usr/share/doc/publik-common/nginx/sites-available/. Ils peuvent être directement copiés dans/etc/nginx/sites-available/.

Combo¶

server {
    listen 80;
    server_name ~^moncompte.*; # portail usagers ; selon le nom du site
    # (attention, différent de la pré-prod)
    ~^agents-.*; # portail agents ; selon le nom du site

    access_log /var/log/nginx/combo-access.log combined_full;
    error_log /var/log/nginx/combo-error.log;

    location ~ ^/static/(.+)$ {
        root /;
        try_files /var/lib/combo/tenants/$host/static/$1
                  /var/lib/combo/tenants/$host/theme/static/$1
                  /var/lib/combo/collectstatic/$1
                  =404;
        add_header Access-Control-Allow-Origin *;
    }

    location ~ ^/media/(.+)$ {
       alias /var/lib/combo/tenants/$host/media/$1;
    }

    location / {
       proxy_pass http://unix:/run/combo/combo.sock;
       proxy_set_header Host $http_host;
       proxy_set_header X-Forwarded-SSL on;
       proxy_set_header X-Forwarded-Protocol ssl;
       proxy_set_header X-Forwarded-Proto https;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Hobo¶

Même modèle que Combo :

server {
    listen 80;

    server_name ~^hobo-.*;

    access_log /var/log/nginx/hobo-access.log combined_full;
    error_log /var/log/nginx/hobo-error.log;

        root /;
        try_files /var/lib/hobo/tenants/$host/static/$1
                  /var/lib/hobo/tenants/$host/theme/static/$1
                  /var/lib/hobo/collectstatic/$1
                  =404;
    }

        alias /var/lib/hobo/tenants/$host/media/$1;
    }

        proxy_pass http://unix:/run/hobo/hobo.sock;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-SSL on;
        proxy_set_header X-Forwarded-Protocol ssl;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

}

Passerelle¶

Même modèle que Combo, mais aucune diffusion de /media (il s’agit de données privées dans Passerelle).

server {
    listen 80;

    server_name ~^passerelle-.*;

    access_log /var/log/nginx/passerelle-access.log combined_full;
    error_log /var/log/nginx/passerelle-error.log;

        root /;
        try_files /var/lib/passerelle/tenants/$host/static/$1
                  /var/lib/passerelle/tenants/$host/theme/static/$1
                  /var/lib/passerelle/collectstatic/$1
                  =404;
    }

        proxy_pass http://unix:/run/passerelle/passerelle.sock;
    }
}

Fargo¶

Même modèle que Combo, mais aucune diffusion de /media (il s’agit des fichiers usagers privés dans Fargo).

server {
    listen 80;

    server_name ~^portedoc-.*;

    access_log /var/log/nginx/fargo-access.log combined_full;
    error_log /var/log/nginx/fargo-error.log;

        root /;
        try_files /var/lib/fargo/tenants/$host/static/$1
                  /var/lib/fargo/tenants/$host/theme/static/$1
                  /var/lib/fargo/collectstatic/$1
                  =404;
    }

        proxy_pass http://unix:/run/fargo/fargo.sock;
    }

}

Authentic¶

Comme Combo, sans diffusion des /media, et en utilisant le nom du serviceauthentic2-multitenant.

server {
    listen 80;

    server_name ~^connexion-.*;

    access_log /var/log/nginx/authentic2-multitenant-access.log combined_full;
    error_log /var/log/nginx/authentic2-multitenant-error.log;

        root /;
        try_files /var/lib/authentic2-multitenant/tenants/$host/static/$1
                  /var/lib/authentic2-multitenant/tenants/$host/theme/static/$1
                  /var/lib/authentic2-multitenant/collectstatic/$1
                  =404;
    }

        proxy_pass http://unix:/run/authentic2-multitenant/authentic2-multitenant.sock;
    }
}

w.c.s.¶

server {

    listen 80;

    server_name ~^demarches-.*;

    access_log /var/log/nginx/wcs-access.log combined_full;
    error_log /var/log/nginx/wcs-error.log;

        root /;
        try_files /var/lib/wcs/tenants/$host/static/$1
                  /var/lib/wcs/tenants/$host/theme/static/$1
                  /var/lib/wcs/$host/static/$1
                  /var/lib/wcs/$host/theme/static/$1
                  /var/lib/wcs/collectstatic/$1
                  =404;
    }

    location /qo { alias /usr/share/wcs/qommon/; }
    location /apache-errors { alias /usr/share/auquotidien/apache-errors/; }

    location /themes {
        root /;
        try_files /var/lib/wcs/tenants/$host$uri
                  /var/lib/wcs/$host$uri
                  /usr/share/wcs/$uri
                  =404;
    }

        proxy_pass http://unix:/var/run/wcs/wcs.sock;
    }
}

Vérification des réponses de Nginx¶

Une fois les virtualhost en place, les sites doivent répondre par des erreurs 404 : ce sont les applications de Publik qui répondent qu’elles n’ont pas encore d’instance liés aux noms prévus.

C’est tout de même déjà le temps de vérifier :

* que les certificats HTTPS sont ok,
* que haproxy envoie bien sur web1 (si vous l’avez déjà installé),
* que les requêtes arrivent sur les bons virtualhost, par exemple pour fargo on vérifiera que l’accès àhttps://portedoc-moncompte.macollectivite.frprovoque une 404 dans/var/log/nginx/fargo-access.loget aucun message dans/var/log/nginx/fargo-error.log; opération à répéter avec tous les autres sites installés.

# Enregistrements DNS : délégation de domaine

Enregistrements DNS : délégation de domaine

Une instance Publik requiert plusieurs enregistrement DNS, des certificats SSL correspondants, une gestion des systèmes anti-spam SPF/DKIM/DMARC, entre autres. Entr'ouvert s'occupe de toute cette gestion au moyen d'une délégation de domaine DNS.

La délégation doit être ajoutée dans le domaine « collectivite.fr » de la façon suivante :

demarches.collectivite.fr.  NS  ns1.entrouvert.org.
                             NS  ns2.entrouvert.org.

Une fois ces ajouts effectués dans la zone «collectivite.fr», il faut informer Entr'ouvert qui mettra en place la zone déléguée sur ses serveurs.

Avec cette délégation en place, Entr'ouvert assure la maintenance, la supervision et tous les aspects sécuritaires liés au nommage de l'instance hébergée.

Ajout d'un serveur secondaire sur site

Sur demande, Entr'ouvert peut ajouter un serveur de nom secondaire géré par la collectivité. Il recevra toutes les modifications sur la zone, qui pourront ainsi être auditées. La délégation suivra alors le modèle ci-dessous, ajoutant un NS supplémentaire (ns.collectivite.fr étant le nom du serveur) :

                             NS  ns.collectivite.fr.

# Configuration des dépôts logiciels¶

Configuration des dépôts logiciels¶

Les différents composants logiciels utilisés par Publik proviennent, par ordre de préférence :

* de la distribution Debian GNU/Linux 12 (« bookworm»)
* desbackportsofficiels Debian, disposant du suivi de sécurité par l’équipe Debian,
* des paquets Debian fournis et maintenus par les projetsupstream,
* de paquets Debian maintenus par Entr’ouvert qui en assure le suivi de sécurité.

Configurons le dépôtbookworm-backports:

echo'deb http://deb.debian.org/debian/ bookworm-backports main'>/etc/apt/sources.list.d/backports.list

Ajoutons aussi les dépôts Entr’ouvert:

echo'deb http://deb.entrouvert.org/ bookworm main'>/etc/apt/sources.list.d/entrouvert.list

Ajoutons la clé associée :

curlhttps://deb.entrouvert.org/entrouvert.gpg|sudotee-a/etc/apt/trusted.gpg.d/entrouvert.gpgaptupdate

Nous installons ensuite les configuration particulières de apt :

aptinstall-oDpkg::Options::="--force-confnew"entrouvert-repositoryaptinstallentrouvert-repository-hotfixaptupdate

Installation des paquets de base¶

Outillage utile pour l’installation et plus tard pour le support et la maintenance :

aptinstallpostgresql-client# pour création utilisateurs et bases de données dans postgresqlaptinstallbsd-mailx# pour test de l'envoi de mailsaptinstallzip# pour la création du squelette de site w.c.s.aptinstallcurlwget# pour les tests/debug locauxaptinstallltracestracepsmisctcpdumptshark# pour des debug applicatifsaptinstallca-certificates-entrouvert# connexion au LDAP EO

Composants additionnels nécessaires pour les applications :

aptinstalllibreoffice# pour génération de documents dans wcsaptinstallpublik-base-theme# système de thèmeaptinstallpublik-common# outils de gestion

# Procédure d’installation¶

Procédure d’installation¶

Ce document présente l’installation d’un système Publik standard. Des
adaptations sont naturellement à envisager en fonction des besoins
particuliers.

* Pré-requis
* Configuration des dépots
* Création des bases de données
* Installation des composants
* Déploiement des instances
* Haute disponibilité

# Journal des événements (logs)¶

Journal des événements (logs)¶

L’historique des événements applicatifs est accessible via l’outiljournalctl. Les fichiers de log des applications constituant l'application Publik sont tous présents dans/var/log.  Par exemple pour suivre les événements de combo :

# journalctl -fu combo

Pour suivre l’ensemble des composants :

# journalctl -f -u combo -u authentic2-multitenant -u wcs -u hobo -u chrono -u supervisor

Les logs HTTP sont ceux de nginx, fichiers textes rangés par service dans/var/log/nginx :

/var/log/nginx/authentic2-multitenant-access.log/var/log/nginx/authentic2-multitenant-error.log/var/log/nginx/bijoe-access.log/var/log/nginx/bijoe-error.log/var/log/nginx/combo-access.log/var/log/nginx/combo-error.log/var/log/nginx/hobo-access.log/var/log/nginx/hobo-error.log/var/log/nginx/passerelle-access.log/var/log/nginx/passerelle-error.log/var/log/nginx/wcs-access.log/var/log/nginx/wcs-error.log

Exemple pour suivre ce qui concerne combo :

# tail -f /var/log/nginx/combo-\*.log

# Haute disponibilité¶

Haute disponibilité¶

Lors d’installations critiques nous recommandons de doubler chacun des services, et la mise-en-place d’une interface de stockage distribuée. Un serveur proxy est en charge de la terminaison SSL, de la répartition de la charge et la tolérance aux pannes.

# Notice d'exploitation

Notice d'exploitation

Ce document constitue la notice l’exploitation d’un système Publik standard. Des adaptations sont naturellement à envisager en fonction des besoins particuliers.Le pré-requis pour exploiter un système Publik est qu'on soit formé à l'administration de système Debian.

# Architecture

Architecture

Publik est un ensemble de composants : on parle desbriquesde la solution. Elles sont représentées ci-dessous sous la forme de carrés. Elles sont accessibles par les humains via le web au travers d’interfacesfrontofficeoubackoffice.

Le composantpasserelleassure la connexion avec des systèmes tiers en traduisant les webservices de Publik au format des protocoles des logiciels cibles.

Liste des briques disponibles :

* Authentic : gestion des identités,identity provider
* Combo : portails usager et agent
* w.c.s. : formulaires et workflows
* Passerelle : connecteurs vers systèmes tiers
* Chrono : prise de rendez-vous
* Hobo : système de déploiement
* Lingo : gestion des paiements

Un système Publik installé ne comporte pas obligatoirement toutes les briques.

# Prérequis d’infrastructure¶

Prérequis d’infrastructure¶

Machine hôte¶

Les ressources nécessaires varient en fonction de la quantité de données à traiter. Une installation de développement peut aisément tenir sur une machine virtuelle.

Par exemple, voici les ressources d’une machine applicative standard :

* CPU 4 cœurs
* 16 Go de mémoire vive
* 200 Go d’espace disque
* Debian stable (ou old-stable) installé en architecture amd64 (installation minimale)

La brique w.c.s. (formulaires) doit disposer d’un volume plus important pour gérer les documents des usagers. Ceux-ci sont stockés sur le système de fichier, son volume est donc à évaluer en fonction de l’usage prévu.

Réseau¶

On ne traite que du cas ou tous les services sont sur un seul serveur. Les ports réseaux suivants doivent être ouverts, sans filtre (très important !) et sans proxy:

* en entrée :SSH (22/tcp)HTTPS (443/tcp)
* en sortie :SMTP (25/tcp)DNS (53/udp et 53/tcp)HTTPS (443/tcp)LDAP (389/tcp et 636/TCP)

Certificat X509¶

Publik utilise le protocole de transport chiffré HTTPS.

Un ou plusieurs certificats x509 valides et reconnus sont requis ; ceux-ci doivent couvrir tous les noms des briques qui seront installées. Pratiquement un certificatwildcardsuffit généralement (un certificatwildcardcouvrant *.eservices.macollectivite.fr et eservices.collectivite.fr). L’utilisation de certificats Let's Encrypt est possible et encouragée.

Résolution de noms¶

Avant l’installation de Publik, il faut vérifier que les enregistrements DNS sont fonctionnels ; Publik nécessite autant de domaines que de composants.

Typiquement :

* portail usager (composant combo) : eservices.macollectivite.fr,
* portail agents (composant combo) : agents.eservices.macollectivite.fr,
* démarches (composant wcs/wcs-au-quotidien) : demarches.eservices.macollectivite.fr,
* fournisseur d’identités (composant authentic) : connexion.eservices.macollectivite.fr,
* hub de webservice (composant passerelle) : passerelle.eservices.macollectivite.fr,
* gestion de rendez-vous et évènements (composant chrono) : agenda.eservices.macollectivite.fr,
* gestion de tarification et facturation (composant lingo) : paiement.eservices.macollectivite.fr

Par exemple, voici à quoi pourraient ressembler les entrées d’un serveur Bind:

publik         A     a.b.c.d   ; addresse IP de «publik»
hobo           CNAME publik    ; système de déploiement (brique : hobo)
portail        CNAME publik    ; portail usage (brique : combo)
backoffice     CNAME publik    ; portail agent (brique : combo)
connexion      CNAME publik    ; fournisseur d'identités (brique : authentic)
demarches      CNAME publik    ; téléservices (brique : wcs)
passerelle     CNAME publik    ; hub de webservices (brique : passerelle)
agenda         CNAME publik    ; gestion des événements et agenda (brique : chrono)
paiement       CNAME publik    ; gestion des tarifs et facture (brique : lingo)

Toutes ces entrées DNS doivent pointer vers le proxy de répartition de charge (dans le cas d’une installation avec répartition de charge).

Par ailleurs, les serveurs applicatifs doivent impérativement avoir un fichier/etc/hostsconsistant.

Horloges synchronisées

Il est indispensable que les machines soient exactement à la même heure. Les systèmes récents utilisentsystemd-timesyncdpar défaut.Ntpest également possible.

Envois des emails

Les serveurs applicatifs doivent disposer d’un MTA local (par exempleexim4-daemon-light) avec le port SMTP ouvert et capable d’expédier des mails vers tout Internet, en passant éventuellement par un relais. Les mails seront envoyés avec le domaine « @eservices.macollectivite.fr ». Nous recommandons vivement de les relayer via un smarthost officiel de votre réseau.

Pour davantage de détails sur l’envoi de courriel, se référer àhttps://dev.entrouvert.org/projects/publik/wiki/Envois_de_courriels.

Configuration de la localisation

Sur toutes les machines, il est nécessaire de reconfigurer la locale utilisée par défaut pour utiliserfr_FR.UTF-8:

dpkg-reconfigurelocales

# Les cellules - démarches

Les cellules - démarches

Brouillons en cours

A pour résultat de présenter à l'usager toutes ses démarches entamées et pouvoir ainsi les reprendre à sa convenance.

Catégories de démarches

Affiche l'intégralité des catégories disponibles sur la plate-forme (y compris celles ne contenant aucune démarche), un clic sur une catégorie ouvre dans une nouvelle page les démarches de celle-ci.

Demandes de l'usager

Affiche les demandes de l'usager, paramétrage possible sur démarches en cours et/ou démarches terminées. Il est possible de « sectoriser » l'affichage des demandes en le restreignant à une ou plusieurs catégories, pour choisir d'afficher uniquement cette/ces catégorie(s) de demandes à tel ou tel endroit du portail citoyen.

Un paramètre permet d'afficher également des demandes auxquelles l’usager peut accéder même si elles n'ont pas été remplies par lui.

Si la cellule est positionnée sur une page liée à un modèle de fiche, il devient possible d' « Afficher uniquement les demandes liées à la fiche liée à cette page » via la case à cocher qui apparaît alors. Cela va permettre par exemple pour une page exposant la 
fiche d'une association, de ne lister via la cellule que les demandes 
concernant cette association.

Démarches d'une catégorie

Permet de construire rapidement un sommaire avec l'ensemble des démarches d'une catégorie (pour une page d'accueil par exemple).Il s'agit du mode de construction d'une page de démarches le plus utilisé puisque cela permet d'afficher automatiquement et de façon ergonomique de nombreuses démarches sur une seule page.

Il est possible de paramétrer le nombre et l'ordre des démarches à afficher par catégorie (les sous-catégorie n'existent dans Publik). Il est également possible de rendre le contenu pliable / dépliable.Choisir le nombre de démarches affichées permet d'équilibrer la présentation, même si le nombre de démarches dans chaque catégorie varie fortement.

L'installation peut être livrée avec des éléments graphiques pré-installés et notamment des icônes pour illustrer les catégories, nous les mettons gracieusement à disposition, il suffit de nous demander gentiment ;-). Pour faire apparaître ces icônes, il suffit de renseigner dans Options / Slug l'un des 10 mots-clés suivants : dechets, famille, logement, papiers, sante, securite, signalements, sport, transport, travail. Et si vous souhaitez reverser à la communauté des utilisateurs des icônes que vous auriez créés, nous en serions ravis.

Lorsque l'on  donne un identifiant (slug) à la cellule (via le lien «  Options »), on a un accès direct à la gestion d'une image associée à la cellule - via le lien « Ressources » en bas de la cellule.

Entrée de code de suivi

Cette cellule est particulièrement importante pour les utilisateurs qui ont effectué une démarche sans compte. En saissisant le code de suivi de la demande, l'usager accède à l'historique de sa démarche.Pour simplifier le parcours usager, il est conseillé que cette cellule soit bien visible dès la page d'accueil du portail citoyen.

Lien vers une catégorie

Pour proposer un lien vers une catégorie donnée, les démarches de celle-ci étant alors accessible sur la page affichée au clic.

Lien vers une démarche

Affiche directement un lien vers une démarche en particulier.

* Studio
* Les tutos

# Les cellules - avancées

Les cellules - avancées

Carte

Combo dispose de fonctions de cartographie pour ajouter des cartes sur les portails en front et en backoffice. Afin que le choix « Carte » apparaisse parmi les cellules possibles en ajout, il faut qu'au moins une couche cartographique ait été définie dans lesparamètres du portail. L'ensemble des couches cartographiques définies au niveau du portail sont proposées (liste à choix multiples) dans les réglages de la cellule, pour affichage, ou pas.

Une case à cocher permet de choisir si l'on souhaite avoir un regroupement automatique des marqueurs sur les cartes. Lorsqu'on fait le choix de regrouper, on a des cercles indiquant le nombre de marqueur pour une zone. Quand on zoome ou qu'on clique sur les chiffres ainsi obtenus,  les marqueurs apparaissent à nouveau de façon individualisée.

Dernières pages modifiées

Cette cellule liste les pages ayant fait récemment l'objet de modifications.

Document récents

Cette cellule permet d'afficher les documents récemment ajoutés dans le porte-documents de l'usager, c'est donc un rappel de la page de porte-document en elle-même, celle-ci  devant être affichée par ailleurs.

Famille

La cellule famille va permettre d'afficher la composition de la famille et d'autres informations récupérées auprès du logiciel métier enfance connecté à Publik, cette cellule n'est disponible que si un connecteur avec un logiciel famille est activé sur votre installation.

Flux RSS/Atom

Pour intégration d'un flux RSS, il est possible de choisir le nombre d'actualités (par exemple) qui seront affichés grâce au réglage de « Nombre maximum d'entrées ».

Profil

Informations de profil de l'utilisateur (agent ou usager), non éditable.

* Studio
* Les tutos

# Les cellules - visualisation des données statistiques

Les cellules - visualisation des données statistiques

Graphe

Cette cellule permet de configurer et d'afficher des indicateurs statistiques divers. La configuration commence par le choix, dans la liste déroulante « Données », de ce qu'on souhaite afficher/configurer. Les données peuvent concerner :

* Les agendas
* Les connexions
* Les demandes
* Les fiches
* les SMS
* Desindicateurs construits sur mesuredans la brique dédiée (tout ce qui commence par « Statistiques : ») (déprécié)

La cellule autorise :

* plusieurs options d'affichage : barres horizontales et verticales, barres empilées, lignes, camemberts, points et tableaux,
* plusieurs tailles (« Hauteur »),
* la configuration d'un intervalle permettant de découper les statistiques (année, mois...)
* le choix d'une période donnée (année précédente, année en cours...)
* de connaître le temps écoulé entre deux statuts
* de limiter les statistiques au canal « backoffice »
* de limiter les statistiques aux 6 ou 12 derniers mois
* d'exporter/télécharger sous forme de tableau ou d'image les données statistiques

Un certain nombre de critères supplémentaires sont utilisables en fonction du type de données sélectionné. Lorsque l'on choisit « Démarches : nombre de demandes » par exemple, il est possible de sélectionner une démarche particulière ou une catégorie de démarches. Il est alors possible d'utiliser comme filtres les listes du formulaire pour lesquelles l'option « Statistiques » est cochée.

Petite vidéo explicative type="video/webm"

On peut juxtaposer plusieurs cellules graphes sur une page pour construire des rapports statistiques; grâce au réglage de visibilité des cellules et des pages, il sera possible d'afficher des rapports différents suivants les rôles.

Exemple en vidéo

La cellule graphe peut être utilisée en conjonction avec la cellule «

[Filtre](https://doc-publik.entrouvert.com/admin-fonctionnel/modifier-le-contenu-des-portails/les-cellules/#filtre)

» qui va permettre de faire varier, directement depuis la page du portail, les valeurs affichées en fonction de certain critères. Cela permet d'afficher des indicateurs statistiques dynamiques.

Filtre

Cette cellule doit être utilisée sur la même page qu'une cellule graphe et va permettre d'afficher, à côté du graphique, des listes déroulantes permettant de choisir des critères qui vont faire varier dynamiquement les statistiques affichées. On la positionne classiquement dans la barre latérale de la page alors que la cellule graphe occupera l'espace central.

La cellule Filtre va exposer plusieurs critères sur lesquels on pourra faire le filtrage :

* Une période concernée (libre - en diquant une date de début et une date de fin - ou prédéfinie, par exemple, « Année en cours »)
* Un intervalle permettant de découper les statistiques (année, mois, jours de la semaine, heures)
* Le canal utilisé pour faire les demandes
* Le ou les formulaires concernés
* Le nombre de mois à afficher
* Le regroupement à utiliser

Il faut noter que les filtres ne peuvent pas fonctionner sur des cellules graphe exposant desindicateurs construits sur mesuredans la brique dédiée (tout ce qui commence par « Statistiques : »)

* Studio
* Les tutos

# La cellule - Fiche(s)

La cellule - Fiche(s)

⚙️ Accès dans le BO :Édition « Portail » > 👉 une page

La celluleFiche(s)permet d'afficher dynamiquement des contenus issus de modèles de fiches, en proposant des options de personnalisation et de filtrage avancées.

Général

Modèle de fiche

Le menu déroulant « Modèle de fiche » permet de sélectionner un modèle de fiche ou une vue personnalisée comme source de données.

En optant pour une vue personnalisée, il est possible de restreindre les résultats en appliquant les critères définis dans cette vue (veillez à ce qu'aucun critère ne soit laissé vide).Le tri configuré dans la vue personnalisée sera également respecté, par contre la disposition des colonnes de cette vue n'influera pas sur le rendu final dans la cellule.

Fiche(s) à afficher

Le menu déroulant « Fiche(s) à afficher » permet de sélectionner, dans tous les cas :

* toutes les fiches: ensemble des fiches contenues dans le modèle de fiche sélectionné ;
* ungabaritqui produit une liste d'identifiants de fiches, séparés par des virgules.

En fonction des paramétrages, il peut aussi afficher :

* unefiche dont l'identifiant est dans l'URL: cet identifiant est transmis en paramètre dans l'URL, par exemple depuis une page qui permet la recherche dans les fiches ;
* lesfiches liéesà une autre fiche présente sur la même page (relation inverse).

Restreindre l'affichage

Deux options permettent de limiter l'affichage aux fiches pour lesquelles l'utilisateur connecté est concerné :

* soit en tant qu'usager : « Restreindre aux fiches liées à l’usager connecté » ;
* soit en tant qu'agent instructeur : « Restreindre aux fiches accessibles à l’usager connecté ».

Visibilité

Par défaut, la cellule Fiche(s) est visible de tous. Vous pouvez restreindre cette visibilité à des usagers connectés ou non connectés, ou a des usagers ayant des rôles spécifiques. Il est également possible de conditionner l'affichage de la cellule.

Apparence

Titre

Par défaut, le titre affiché est celui de la fiche, configuré dans le gabarit du résumé du modèle de fiche.Vous pouvez choisir de ne pas afficher de titre ou définir un titre personnalisé.

Slug

Ajouter un slug à une cellule Fiche(s) permet d'indiquer que cette cellule est la cellule principale.

Taille

Pour afficher le guide de taille comme sur la capture d’écran ci-dessus, sélectionnez une disposition de grille en colonne (une, deux ou trois) dans les Options, au lieu de l’option « Manuel ».

Classes supplémentaires pour le style par CSS

Il est possible d'ajouter desclasses CSS réutilisables.

Affichage

Nombre de fiches par page (par défaut : 10)

Afficher le champ de recherche

La case à cocher qui permet d'afficher un champ de recherche sur les fiches n'est visible que lorsque la cellule est paramétrée pour afficher toutes les fiches.

Filtres

Vous pouvez ajouter des filtres pour limiter l’affichage des fiches selon différents critères. Tous les champs listes (simples ou multiples) ainsi que le statut peuvent servir de filtres.

Le champ de filtrage s’affiche au-dessus des fiches et permet de sélectionner une ou plusieurs valeurs. Seules les fiches correspondant à ces choix seront affichées.

Paramétrage côté backoffice

Affichage en frontoffice

Mode d'affichage

Il existe plusieurs modes d’affichage pour les fiches :

* Carte: juxtapose les fiches à l’écran comme des cartes à jouer, avec une configuration possible de chaque carte.
* Tableau: affiche les fiches sous forme de tableau, avec une ligne par fiche, chaque ligne étant configurable.
* Liste: propose par défaut un lien vers chaque fiche, mais ce mode peut également être personnalisé.

Personnaliser l'affichage

L’option « Personnaliser l’affichage » offre une interface de composition graphique qui permet :

* de sélectionner uniquement les champs à afficher ;
* de personnaliser le contenu et l’agencement des éléments selon vos besoins.

Cette fonctionnalité est idéale pour créer des interfaces métier sur mesure, adaptées à des cas d’usage spécifiques.L’interface propose de nombreuses options avancées, parfois complexes, qui s’adressent principalement à des utilisateurs expérimentés. Elle permet d’afficher différents types de contenu pour les modes « Carte » et « Tableau » tels que :

Champ de la fiche

Lorsque le mode d'affichage est « Carte », il est possible de sélectionner un champ du modèle de fiche, de spécifier le contenu du champ (Libellé et valeur / Libellé uniquement / Valeur uniquement) et le mode d'affichage en cas de valeur absente (Inclure la case vide / Ne pas inclure la case / Inclure un texte personnalisé) et de déterminer la taille.

Lorsque le mode d'affichage est « Tableau », il est possible de sélectionner un champ du modèle de fiche, d'ajouter untexte personnalisé pour remplacer une valeur vide etde choisir la largeur de la colonne qui s'exprime en pourcentage, par exemple : 15%.

Il est possible de présenter les fichiers (PDF) sous forme de vignette. Une fois sélectionné le champ contenant le PDF, on peut choisir de lui appliquer le mode vignette.

Champ utilisateur

Lorsqu'un usager est associé à une fiche, il est possible de sélectionner un champ du profil usager.

Champ information de la fiche

* Des informations générales sur la fiche (date de création, de modification, statut, identifiant)

Personnalisé

* Des informations personnalisées (sous forme de gabarit dans lesquels on peut utiliser des variables du type {{ card.fields.IDENTIFIANT-DU-CHAMP }} pour afficher la valeur d'un champ de la fiche).

Lien

* Des liens (éventuellement affichés sous forme de bouton).

Lorsque le type de contenu est défini comme un lien, le libellé est affiché même si la destination du lien ne renvoie aucune valeur. Cela permet, via une condition d’affichage, de proposer soit un texte, soit un lien, selon la valeur retournée.

Action

* Une « Action » pour afficher un bouton d'action déclenchant une action globale du workflow de la fiche. Cette action globale doit être configurée avec un déclencheur externe.

Aller plus loin

Lier un modèle de fiche à une page

Dans le menu burger d'une page, il est possible delier cette dernière à un modèle de fiche. Ce sera utile en particulier pour une page dédiée à l'affichage d'une fiche donnée et qu'on souhaite pouvoir atteindre en mettant le numéro de fiche dans l'URL.

Lorsqu'une page du portail est liée à une cellule Fiche(s), le titre de la page (la balise <title>) devient désormais le titre (le display_label) de la fiche concernée. Par exemple si la page est utilisée pour afficher la fiche d'une école, le titre de la page sera le nom de cette école.

* Studio
* Les tutos

# Les cellules - contenu générique

Les cellules - contenu générique

Galerie d'images

Cette cellule permet de gérer un ensemble de photos sous forme de galerie avec des vignettes permettant de passer aisément d'une photo à l'autre.

Identique à la page parente

Permet de reproduire dans la zone concernée (par exemple « Pied de page », pour laquelle ce réglage est pré-selectionné par défaut) le contenu de la même zone dans la page supérieure de la hiérachie ; il est possible de combiner ce réglage avec l'ajout de cellules supplémentaires.

Lien

Permet d'insérer un lien externe ou interne (vers une page du portail).

Liste de liens

Cellule qui permet d'agréger de façon homogène dans une cellule unique des liens vers des démarches d'une part et des liens vers des pages d'autre part. Lorsque l'on  donne un identifiant (slug) à la cellule (via le lien «  Options »), on a un accès direct à la gestion d'une image associée à la cellule - via le lien « Ressources » en bas de la cellule.

Menu

Pour construire un menu (souvent en barre latérale), celui-ci pourra présenter 1 ou, au maximum, 2 niveaux de profondeur et une page racine, au choix.

Notification à l'usager

Les notifications à l'attention de l'usager (sur des actions liées à des démarches, sur la mise à disposition de factures, ...) seront affichées dans cette cellule.

Recherche

Le moteur de recherche permet de chercher dans une interface unique :

* des usagers (à réserver au portail Agents) ;
* des demandes (à réserver au portail Agents) ;
* un code de suivi ;
* du texte dans des pages et les démarches liées ;
* des démarches accessibles, c'est-à-dire les formulaires que l'utilisateur peut remplir (selon qu'il est connecté ou non, et si oui selon ses rôles) ;
* des formulaires en « Saisie backoffice ». C'est conçu pour trouver et démarrer rapidement une saisie backoffice : un clic dans la liste des résultats de la recherche permet d'initier une saisie backoffice.

Pour utiliser ou désactiver l'un de ces items, il suffit de cocher/décocher l'item. L'option « Focus automatique » force le positionnement du curseur à l'intérieur du champ recherche lorsque la page est affichée (plus utile dans le portail Agents).

Pour les usagers il est possible de préciser un gabarit définissant ce qui sera affiché dans les résultats de la recherche.

Pour les pages, on peut définir un titre personnalisé qui prendra dans les résultats la place du « vrai » titre et choisir d'afficher ou pas la description.

Il est également possible pour le moteur de

[chercher dans des fiches](https://doc-publik.entrouvert.com/admin-fonctionnel/developper-des-applications-simples-avec/parametrage-avance-des-fiches/#faire-un-moteur-de-recherche-sur-les-fiches)

.

L'ajout d'une cellule « Recherche » déclenche l'indexation du contenu. La recherche n'est donc pas effective immédiatement. Le contenu est réindexé chaque nuit.Actuellement, le fonctionnement repose sur une recherche en texte intégral dans la base de données.

Texte

Cette cellule présente un éditeur de texte permettant la mise en page, l'ajout de liens et d'images. Attention : éviter d'inclure trop d'images, celle-ci pouvant empêcher la bonne utilisation du site en mode responsive design.

* Studio
* Les tutos

# Les cellules - espace agents

Les cellules - espace agents

Demandes à traiter

Cette cellule permet d'afficher à l'agent les demandes en attente de traitement, en fonction de ses rôles. Elle peut être limitée à une ou plusieurs catégorie(s).

Initialement prévue pour une utilisation backoffice, elle peut aussi être utilisée en front office.

Si la cellule est positionnée sur une page de portail liée à un modèle de fiche, il devient possible d'« Afficher uniquement les demandes liées à la fiche liée à cette page » via la case à cocher qui apparaît alors.

Jauges

Un visualisation sous forme de jauge est possible pour de nombreuses valeurs (demandes en attente d'une action, demandes en attente de saisie, ...). Le paramétrage des jauges fait appel à des sources de données que pourra vous indiquer l'intégrateur de votre solution Publik.

Saisie backoffice

Affichage de la liste des formulaires disponibles pour une saisie par l'agent avec possibilité de la restreindre à une ou plusieurs catégories.

* Studio
* Les tutos

# Les cellules - paiement

Les cellules - paiement

Factures actives

Formulaire de paiement TIPI

Affichage d'un formulaire pour saisie libre d'une référence de facture en vue d'un paiement en ligne sur l'interface TIPI titredu Ministère des Finances, DGFIP (NB : il existe également la possibilité d'affichage des factures à l'usager si module correspondant activé, cf. infra). Après ajout d'une cellule de ce type, apparaît automatiquement une cellule « Formulaire de Paiement TIPI / Introduction » qui permet de saisir un texte libre, optionnel, au sein de la cellule «Formulaire de paiement TIPI ».

Historique des factures

Lien vers le panier

Panier

Transactions récentes

* Studio
* Les tutos

# Créer un menu personnalisé

Créer un menu personnalisé

Le menu qui s'affiche, en backoffice dans la barre latérale gauche, dépend des droits de l'utilisateur connecté, il est standard et lié aux différentes briques présentes dans Publik.

Il est possible de remplacer ce menu standard par un menu entièrement personnalisé en créant des pages spécifiques du portail agent qui deviendront des entrées du menu.

Créer les pages

Quand le menu personnalisé sera activé, toutes les pages du portail agent pour lesquelles :

* L'option « Incluse dans les menus » est à Oui
* Vous avez les droits (rôles) nécessaires permettant de les voir

vont apparaître comme des entrées du menu latéral.

Ces entrées seront des liens vers l'URL que vous allez spécifier dans l'option « URL de Redirection » de la page.

Des sous-pages seront des sous-entrées du menu.

Ajouter des icônes

Il est possible de donner des slugs spécifiques à certaines pages afin qu'elles se voient automatiquement attribuées dans le menu une icône adaptée, voici la liste des identifiants possibles, avec leur utilisation dans le menu par défaut :

* agendas, pour les agendas (module Chrono)
* announces
* book
* calendar
* cards, pour les modèles de fiches
* categories, pour les catégories
* clock
* counter
* data, pour les fiches
* facturier
* forms, pour les formulaires
* gis
* grid
* home, pour l’accueil
* identity-management, pour la gestion d’identités
* mail
* management, pour l’écran de traitement
* organizational-units
* passerelle, pour les services web (module Passerelle)
* password
* phone
* portal, pour l’édition du portail
* portal-agent, pour l’édition du portail agents
* porte-doc
* roles, pour la gestion des rôles
* security
* services
* settings
* statistics, pour les statistiques
* studio, pour l’écran d’accueil Publik Studio
* submission, pour la saisie
* system, pour la configuration système
* texts
* theme
* users, pour les utilisateurs
* workflows, pour les workflows

En dehors de ces noms particuliers, il reste possible d'ajouter une icône personnalisée à une page grâce à son option « Image ». L'image positionnée ici apparaîtra dans le menu à côté du titre de la page.

Le format des icônes « Standard » est d'environ 40x40 pixels

Positionner les rôles sur les pages

Il faut veiller à la cohérence entre les droits d'accès aux briques vers lesquelles pointent les entrées du menu et le ou les rôles positionnés sur les pages du portail agent dans l'option « Visibilité ». Sans cela, on pourrait afficher à l'usager une entrée de menu qui lui donnerait une erreur 403 ou au contraire ne pas lui afficher une entrée vers une brique à laquelle il peut accéder.

Ajouter une variable

Si vous ne pouvez pas accéder à la brique « Système » demandez à votre administrateur de faire l'ajout de la variable pour vous.

Pour que votre menu sur mesure vienne prendre la place du menu standard, il est nécessaire de définir une variable.

Allez dans « Système » puis choisissez « Services » dans le menu burger. Cherchez l'élément « Portail agent » dans la page, et cliquez sur « Variables personnalisées > » puis sur « Ajouter une variable ». Complétez la variable comme suit (le libellé est sans importance) :

Nom :SETTING_PUBLIK_EXPLICIT_MENU

Valeur :True

Attention, n'activez cette variable que lorsque vous avez déjà configuré les pages de votre portail agent pour qu'elle vous donne des entrées dans le menu, sinon votre menu sera vide, il ne vous permettra plus d'accéder aux différentes briques (notez toutefois que même lorsque les entrées du menu ont disparu, les différentes briques restent accessibles en utilisant directement leurs URLs).

Fichier JSON standard

Afin de faciliter la mise en place, nous avons réalisé ce

[fichier exemple](https://doc-publik.entrouvert.com/media/uploads/2020/12/24/site_export_20201224.json)

qui peut être importé dans votre portail agent sur vos plates-formes de test. Il faut impérativement que les rôles « Agent » et « Administrateur fonctionnel » existent sur votre plate-fome pour que l'import se fasse correctement.

Attention, il va venir prendre la place des pages éventuellement existantes et portant le même nom.

Après import du fichier dans votre portail agent, il faut penser à

[ajouter la variable](https://doc-publik.entrouvert.com/admin-fonctionnel/modifier-le-contenu-des-portails/creer-un-menu-personnalise/#ajouter-une-variable)

pour activer le menu personnalisé.

* Studio
* Les tutos

# Mettre en place un portail Agents

Mettre en place un portail Agents

Le portail Agents permet aux agents d'accueil de répondre efficacement aux usagers lorsque ceux-ci viennent au guichet ou appellent pour faire une démarche ou savoir où en est une démarche.Le portail peut également être l'endroit où se font les demandes internes, servir de base de connaissances, de documentation, on peut y placer des tableaux de bord statistiques...

Comment mettre en place un portail Agents

Aller dans « Edition du portail Agents » et commencer par ajouter une page (par exemple : « Accueil »).C'est cette page que les agents verront lorsqu'ils se connectent.Pour chaque page, il est possible de choisir la mise en forme, la visibilité (publique ou visible seulement par certains rôles) et le contenu, présenté sous la forme de « cellule ».

Pour en savoir plus sur les

[portails](http://doc-publik.entrouvert.com/admin-fonctionnel/modifier-le-contenu-des-portails)

.

[cellules](http://doc-publik.entrouvert.com/admin-fonctionnel/modifier-le-contenu-des-portails/les-cellules/)

.

Bonnes pratiques, idées et exemples de contenu

Selon les besoins des agents, voici quelques exemples de contenus à mettre dans le portail :

* code de suivi : si l'usager détient son code de suivi, la démarche peut être retrouvée par l'agent par ce moyen
* recherche d'usager, de demande (par nom ou code de suivi), ou d'une page
* ajouter un utilisateur : permet de créer une fiche usager si la personne se trouve devant l'agent (pour voir comment configurer les droits pour l'agent, voircette page).
* lien vers les agendas les plus utilisés
* tableaux de bord statistiques
* liste des démarches que l'agent peut réaliser pour le compte d'un usager (cellule « saisie backoffice »)
* liens vers les autres portails (famille...), vers le front-office, des ressources externes
* lien vers la vue des signalements sur une carte
* base de connaissances ou documentation

Page Usagers

Cette page est destinée à afficher les informations sur un usager, aussi les cellules suivantes y seront pertinentes :

* demandes de l'usager
* profil
* notifications à l'usager
* formulaire de paiement
* entrée de code de suivi
* brouillons en cours

La cellule « Saisie Backoffice » peut également avoir de l'intérêt car elle permet de préremplir les formulaires auquel l'agent a accès avec les données de profil de l'usager en question.

Pour être exploitée par la recherche d'usager, son slug doit être

fiche-usager

et il faut renseigner dans le champ « Expression de sous-page »

(?P<name_id>[a-z0-9]+)

Base de connaissances

Il est possible de mettre en place une base de connaissances de type « wiki ». Une bonne pratique consiste à créer une page parent dans Combo et les « fiches » comme sous-pages.Le moteur de recherchepeut être configuré de manière à ne chercher qu'au sein de ces sous-pages.

Centre d'appel

Publik est régulièrement utilisé par les téléconseillers des centres d'appel, il permet dans ce cadre :

* la consultation d'une base de connaissance faite avec Publik (et pouvant être directement intégrée aux démarches),
* la liaison d'une session agent avec une ligne téléphonique donnée,
* la saisie ou relance d'une demande à la place de l'usager, sous réserve que la saisie par les téléconseillers soit rendue possible,
* la consultation du profil usager,
* le suivi des demandes,
* l'affichage automatique de la fiche usager de l'appelant (avec ses demandes en cours),
* L'affichage automatique des demandes qui contiennent le numéro appelant,
* l'affichage d'indicateurs statistiques par canal.

Publik dispose d'un connecteur générique « Appels téléphoniques », pour la gestion des appels https://doc-publik.entrouvert.com/agent-accueil/telephone/

Tableaux de bord et statistiques

Pour créer un tableau de bord statistiques, il faut utiliser le style de cellule « graphe ». Le tableau de bord peut être réalisé sur la page d'accueil, où, si l'on souhaite avoir plusieurs graphes, dans une page à part.La statistique doit avoir été créée dans le module de stats (https://doc-publik.entrouvert.com/admin-fonctionnel/creer-des-rapports-statistiques/) pour apparaître dans le menu déroulant "URL".

* Studio
* Les tutos

# Les cellules

Les cellules

Les cellules sont de plusieurs types dans Publik (texte, lien, liste de liens, menu, démarches d’une catégorie…). Celles-ci sont personnalisables dans une certaine mesure. Alors la personnalisation choisie s’appliquera à toutes les cellules, systématiquement et uniformément.

Les cellules disponibles peuvent varier selon la configuration d'installation de Publik, par exemple les cellules relatives aux factures apparaitront uniquement quand Publik est relié à un système de facturation. Pour ajouter une nouvelle cellule à une zone de la page il suffit de cliquer sur "Ajouter une nouvelle cellule" puis de choisir le type de cellule souhaité.  La nouvelle cellule s'ajoutera alors au bas de la zone et pourra être déplacée où désiré (glisser-déposer). Pour certaines cellules des paramètres spécifiques sont possibles en plus des réglages génériques de chaque cellule.

Lors de l'édition d'une page, il est possible que vos modifications ne soient pas visibles immédiatement, en effet certaines informations sont conservées en cache sur le serveur. Après avoir travaillé durement pour construire votre portail, peut-être est-il temps de boire un café avant d'admirer le résultat.

Utilisation de |with_auth

Il est possible de mettre un lien vers une démarche ou un accès vers une fiche dont l'accès est restreint, en utilisant le filtre |with_auth.

{{eservices_url|with_auth:"username:password"}}

Réglages génériques pour chaque cellule

Deux icônes en bas à droite de la cellule, permettent respectivement de dupliquer (y compris sur une page différente) et de supprimer la cellule.

* Tout le monde
* Restreindre aux utilisateurs non connectés :seuls les utilisateurs non connectés visualiseront cette cellule
* Restreindre aux utilisateurs connectés :seuls les utilisateurs connectés visualiseront cette cellule
* Utilisateurs avec un de ces rôles (les rôles sont ensuite à déterminer)
* Utilisateurs avec aucun de ces rôles (les rôles sont ensuite à déterminer)

Options

* Slug : permet d'identifier en particulier une cellule au sein d'une page.
* Classes supplémentaires pour le style par CSS : pour ajuster la mise en page, par exemple le positionnement sur unegrilleest possible (quand il est utilisé sur toutes les cellules de la page), ainsi que d'autres mises en forme (voir la page spécifique :Classes CSS réutilisables)
* La plupart des cellules viennent avec la possibilité de paramétrer un « Titre personnalisé » (onglet «  Apparence) », ce dernier viendra prendre la place du titre par défaut.

Les différents types de cellules

* Cellules génériques
* Cellules démarches
* Cellules espace agents
* Cellules fiche(s)
* Cellules visualisation des données
* Cellules paiement
* Cellules avancées

* Studio
* Les tutos

# Créer un nouveau workflow

Créer un nouveau workflow

Pour créer un nouveau workflow, on peut choisir de partir d'une feuille vierge ou bien dupliquer un workflow existant qui servira de base à notre nouveau circuit de traitement.

Dupliquer un workflow existant

S'inspirer d'un modèle de workflow existant constitue la stratégie de fabrication d'un nouveau workflow la plus économe.

« Dupliquer » un workflow s'effectue depuisla barre latéralede lapage d'accueildu workflow à dupliquer.

L'administrateur fonctionnel peut puiser parmi les workflows disponibles sur la plate-forme, ou provenant d'ailleurs, et les adapter pour en fabriquer de nouveaux.

Si un workflow présent au sein de la liste desworkflowssemble constituer un modèle judicieux à imiter pour fabriquer un nouveau workflow, l'administrateur fonctionnel peut le dupliquer.

La mention « (copie) » ajoutée au titre d'un workflow indique qu'il s'agit d'une version dupliquée. Mais le titre peut-être modifié sans encombre.

Une fois le workflow dupliqué, il est alors temps de le personnaliser depuis lapage d'accueilde ce workflow.

Créer un Workflow from scratch

Pour les utilisateurs plus expérimentés, il est possible de créer un workflow ex nihilo en cliquant sur « Nouveau workfow » dans la barre latérale depuis la liste des workflows (la page à laquelle on accède quand on clique sur workflow dans le menu latéral).

Importer un workflow

Comme pour les formulaires, on peutimporterun workflow provenant de sources diverses.

* Studio
* Les tutos

# Gérer un workflow

Gérer un workflow

La page d'accueil d'un workflow offre la liste de ses :

* statuts
* fonctions
* variables (options)
* actions globales
* niveaux de criticité
* données de traitement

Et en bas de page, un schéma dynamique donne un aperçu du circuit de traitement. Il est cliquable et peut être utilisé en plein écran pour plus de clarté.

La liste des formulaires associés au workflow figure sous le schéma. Un clic 
sur un formulaire vous amène sur la page d'accueil du formulaire.

Les caractéristiques du workflow

L'administrateur fonctionnel a la possibilité de doter le workflow de :

* Statuts possibles:La progression d'une demande au sein d'un workflow se traduit par un cheminement d'un statut vers un autre, jusqu'à ce que la demande aboutisse à un statut final. La succession des statuts ajoutés à un workflow est listée verticalement dans cette section.L'ajout d'un statutdepuisla barre latéralese traduit par son ajout dans la liste des « Statuts possibles ».Les statuts qui ne sont pas visibles par le citoyens sont affichés « grisés » pour les distinguer des statuts visibles. Les icônes à droite des noms de statuts permettent de distinguer les statuts de transition, les statuts finaux, et les statuts d’action ou d’attente.Le passage d'un statut à un autre est tributaire de la réalisation d'actions que l'administrateur fonctionnel doit affecter à chaque statut pour déterminer les conditions de progression d'une future demande.En cliquant sur l'un des statuts, l'administrateur fonctionnel accède àla page d'édition d'un statut.
* Fonctions dans ce workflow: pour chaque workflow, il existe une fonction par défaut : « Destinataire » qui désigne l'agent traitant. Mais il est possible d'en créer d'autres et l'on pourra alors attribuer les actions du workflow à ces fonctions. On retrouve lesdites fonctions sur les pages d'accueil de chaque formulaire rattaché au workflow. C'est sur chaque formulaire que l'on fera la liaison entre une fonction et un rôle.
* Variables du workflow: il est possible d'utiliser des variables spécifiques au workflow. Les variables créées ici vont engendrer l'apparition dans le bloc « workflow » de chaque formulaire relié à ce workflow d'un lien « Options » dans lequel on va pouvoir donner une valeur aux variables en question. Le résultat est l'obtention d'une valeur qui sera différente d'un formulaire à l'autre alors même que ces derniers utilisent le même workflow.

La barre latéraleoffre plusieurs fonctionnalités :

* dupliquer:la duplication du workflow entraîne la création d'un workflow 
identique qui portera le titre du workflow d'origine avec en plus la 
mention « (copie) ».
* enregistrer une sauvegarde:Toutes les modifications sont enregistrées automatiquement dans 
l'historique du workflow. Mais on peut souhaiter donner une visibilité 
particulière à une version en la sauvegardant explicitement, elle sera 
alors mise en évidence dans l'historique.
* historique:accès aux différentes versions du workflow sauvegardées par ordre 
chronologique. Chaque version peut être restaurée en cliquant sur 
« Restaurer » et en choisissant «Écraser le contenu actuel». À l'inverse, choisir «Restaurer en tant que nouveau» créera un nouveau workflow à partir de la version concernée.
* inspecteur:accès lavue d'inspection d'un workflow

Menu Kebab

* supprimer :la
 suppression d'un workflow n'est possible que lorsqu'il n'est plus utilisé. Il faut donc au préalable modifier les formulaires qui l'utilisent pour les lier à un autre workflow (ou les supprimer).
* Exporter:génère un fichier xml contenant le workflow et pouvant être importé 
sur une autre plate-forme. Le fichier porte le suffixe .wcs.

* Studio
* Les tutos

# Variables de workflow (Options)

Variables de workflow (Options)

Depuis la page d'accueil d'un workflow, il est possible de définir des variables de workflow en cliquant sur le lien dédié.

Il permet de définir un champ et de lui donner un nom de variable du type :

form_option_IDENTIFIANT-DU-CHAMP

Une fois ce champ variable créé,  tous les formulaires associés au workflow afficheront cette nouvelle option : on la verra apparaître sur la page d'accueil d'un formulaire quand on clique sur « Options » au niveau du bloc « Workflow ». Elle pourra donc être différente pour chaque formulaire qui utilise le workflow, permettant de les distinguer.

Cette variable pour être utilisée ultérieurement dans le workflow comme n'importe quelle autre.

Dans quels cas utiliser ces variables ?

Certains formulaires proches utilisent le même workflow mais on a pourtant besoin de faire varier quelques éléments pour chacun d'entre eux comme par exemple un prix ou un délai de traitement.

Imaginons un workflow de signalement d'anomalies sur l'espace public, utilisé par une dizaine de formulaires différents (signalements voirie, espace verts, nuisance sonore...), on pourra avoir une variable de workflow « Durée de traitement » qui permettra de préciser au niveau de chaque formulaire quelle est la durée de traitement pour chaque démarche.

Et aussi...

Pour les champs de type Texte et Nombre, vous pouvez définir une valeur par défaut. Cette valeur sera utilisée si le champ est laissé vide. Vous pouvez alors décocher le caractère obligatoire du champ.

C'est très utile pour renseigner une durée de conservation des données qui par défaut serait de 90 jours et qui peut être personnalisée formulaire par formulaire.

* Studio
* Les tutos

# Niveaux de criticité

Niveaux de criticité

Des niveaux de criticité peuvent être définis depuis la page d'accueil du workflow. L'utilisation de ces niveaux permet de différencier les demandes en fonction de leur urgence.

À chaque niveau de criticité créé est automatiquement associée une couleur, entièrement personnalisable .Cette couleur sera visible sous la forme d'un liseret en début de ligne dans le listing des demandes.

Le choix du nombre de niveaux, de leurs libellés et de leurs couleurs est libre.

Une action supplémentaire de workflow «Niveaux de criticité» devient disponible une fois que l'on a configuré au moins un niveau de criticité.

* Studio
* Les tutos

# Générer un document et l’envoyer par courriel

Générer un document et l’envoyer par courriel

Vous souhaitez générer un document à partir des informations saisies par l’usager lors d’une démarche et envoyer ce document par courriel.

On y va

Téléchargez les objets nécessaires :

* Modèle de document :howto_03-generation-document_modele.odt
* Formulaire :howto_03-generation-de-document_formulaire.wcs
* Workflow :howto_03-generation-document_workflow.wcs

État initial

L’usager fait sa démarche. Le destinataire doit valider l’état avant de passer au statut suivant.  Aucun document n’est généré.

Modifications à apporter

* Ajoutez une action « création de document » dans le statut « génération document »
* Paramétrez cette action :dans le modèle, importez le fichier modèle howto_03-generation-document_modele.odtcochez « Convertir le fichier généré en PDF » : cela génèrera un pdf automatiquement à partir de l’odt. Si cette case n’est pas cochée, le fichier reste en odt. Cela peut être utile si l’usager doit le compléter par la suite.Cochez « Inclure le document généré dans l'historique du formulaire » pour que le fichier soit visible dans le suivi de la démarcheIndiquez un identifiant, par exemple « document_genere »Choisissez la méthode non-interactiveIndiquez un nom pour le fichier généré, par exemple « fichier_{{form_number}}.pdf »Validez
* Testez !

Explications

La génération du document a remplacé les champs personnalisés par la saisie de l’usager. Les champs « simples » ({{form_var_nom}}, {{form_var_prenom}}, …) ont été remplacés.

Pour la section « cadre de la déclaration », on a utilisé des conditions django :

{% if "Impôts sur le revenu" in form_var_impaye %}X{% endif %}

form_var_impayeest l’identifiant du champ de formulaire. Ce champ proposant une sélection multiple, la condition pour vérifier la présence d’une valeur estvaleur in form_var_champ(voir la documentation sur les listes à choix multiples).

On indique ici : « si cette valeur est sélectionnée, affiche un X ».

A votre tour

* Reprenez le modèle de document et ajoutez les champs personnalisés correspondant au courriel, au téléphone et à la date (tout en bas)
* dans l’action « création de document », changez le fichier modèle par celui modifié. Attention ! Décochez bien la case « Garder le fichier actuel »
* Validez
* Testez !

Aller plus loin : envoyer le document généré par courriel

* Créez une donnée de traitementde type fichierappelez-la « Déclaration de phobie administrative »donnez-lui un identifiant, par exemple « declaration »
* Allez dans l’action de création de document :Un nouveau champ est apparu : « Enregistrer dans les données de traitement ». Sélectionnez « Déclaration de phobie administrative »Validez
* Dans le statut « génération de document », ajoutez une action « courriel » :Assurez-vous que l’action est bien positionnée après la création de documentA : sélectionnez « usager »Sujet : indiquez le sujet du courriel, par exemple « Votre déclaratation a été acceptée »Corps : indiquez le corps du message, par exemple :Bonjour,Votre déclaration a été acceptée. Veuillez la trouver ci-joint.Cordialement,Fichier attaché : choisissez la donnée de traitement créée, par exemple « déclaration de phobie administrative »Validez
* Testez !

Téléchargez le modèle de document final :howto_03-generation-document_modele_final.odt

Téléchargez le workflow final :howto_03-generation-document_workflow_final.wcs

Vous pouvez retrouver la documentation complète ici :Création de document,Utiliser les conditions, lesdonnées de traitement.

Les tutos

* Paiement

* Studio
* Les tutos

# Workflow par défaut

Workflow par défaut

Le workflow par défaut est le seul qui n'est pas éditable.

Il s'agit donc d'un point de repère intangible qui peut

* Suffire si on a pas besoin de construire un circuit de traitement élaboré pour une démarche particulière
* Servir de base à l'élaboration de circuits de traitement plus complexes : il suffit alors de le dupliquer et de travailler sur la copie après l'avoir renommée.

* Studio
* Les tutos

# Actions globales

Actions globales

Contrairement aux actions classiques qui sont toujours liées à un statut particulier, les actions globales sont disponibles quel que soit le statut du workflow.

Par ailleurs, les actions globales vont permettre les «Actions en masse», c'est à dire des actions s'appliquant à plusieurs demandes/fiches en même temps.

L'action globale à déclenchement manuel est visible dans la liste des demandes/fiches, uniquement lorsqu'au moins un élément est sélectionné.

Cas d'usage

Une action globale « Retour au début du traitement », réservée à une fonction « Testeur », permettra de tester indéfiniment son workflow avec la même demande (plutôt que de devoir en saisir une nouvelle à chaque test). Quelle que soit l'étape dans laquelle se trouve le traitement de la demande on peut ainsi la renvoyer à l'étape de la soumission et re-travailler son workflow.

Une action globale « Suppression », réservée à une fonction « Testeur », permettra de supprimer en un geste toutes les demandes créées lors de tests.

Création

Sur la page d'accueil du workflow, cliquez sur « Ajouter une action globale » et choisissez un nom pour votre action.

Actions

Indiquer la ou les actions que doit produire l'action globale. Toutes les actions sont disponibles sauf l'action d'édition.

Déclencheur

Il y a 3 types de déclencheurs :

* Automatique : Le déclenchement de l'action sera lié à un délai en jours relatif à un évènement particulier. Par exemple « n jours après création » ou « n jours après passage dans un statut spécifique », etc. Pour indiquer une date de référence, deux formats sont acceptés : jj/mm/yyyy ou yyyy-mm-dd. Les dates de référence à partir desquelles il est possible de fixer un délai sont :Création (la date de création de la demande)Premier passage dans le statut (la date de première arrivée dans un statut qu'il faut sélectionner)Dernier passage dans le statut (la dernière date d'arrivée dans un statut qu'il faut sélectionner)Arrivée dans un statut final (la première date d'arrivée dans un des statuts finaux)Anonymisation (la date de l'anonymisation de la demande)Texte - Gabarit (le texte ou le gabarit doivent donner une date)

Les actions globales avec déclencheur automatique sont exécutées une seule fois. Pour avoir une exécution régulière, il faut plutôt passer par un saut automatique avec expiration.

Les déclenchements automatiques ne sont pas actionnés pour les demandes positionnées dans un statut avec caractère « final » sauf si on prend explicitement ces statuts comme référence (via les choix « Premier/Dernier passage dans le statut » ou « Arrivée dans un statut final »).

* Manuel : Le déclenchement de l'action sera lié au clic sur un bouton. Ce bouton apparaîtra sur la page listant les fiches/demandes concernées par ce workflow (avec comme libellé le nom de l'action globale). Dans le listing, il faut cocher les cases en face de chaque fiche/demande pour sélectionner celles sur lesquelles l'action sera appliquée.
* Appel externe : Le déclenchement de l'action sera lié au fait qu'elle est appelée par une application tierce ou par une action « Workflow externe ». Si aucun rôle n'est spécifié au niveau de «Rôles requis pour déclencher via un appel HTTP», l'appel est ouvert à tous. Sélectionner « Appels signés aux API » permet de le réserver à un usage interne à Publik (un appel fait depuis un agenda ou un autre workflow).

Limiter le déclencheur à certains statuts

Par défaut, une action globale est disponible dans tous les statuts. Il est toutefois possible de limiter la présence d'un déclencheur à un ou plusieurs statuts en les sélectionnant explicitement dans la partie « Afficher uniquement pour les statuts suivants ».

Ne pas afficher le déclencheur pour les actions en masse

Les actions en masse sont disponibles lorsqu'on sélectionne une ou plusieurs demande dans le tableau de traitement des demandes. Par défaut les déclencheur manuel des actions globales apparaissent. Il suffit de décocher « Proposer en action de masse » si on ne souhaite pas les voir à cet endroit.

* Studio
* Les tutos

# Données de traitement (champs)

Données de traitement (champs)

Les données de traitement sont des champs définisdans le workflow. Une fois configurés, ils pourront apparaître (libellé et valeur) dans l'interface de traitement d'une demande.

Cas d'usage :

* ces champs peuvent être utilisés comme l'équivalent d'un « cadre réservé à l'administration » dans un formulaire papier, offrant des données disponibles uniquement pour les agents,
* ils permettent aussi de stocker des informations intermédiaires, telles qu'un résultat de calcul un peu complexe et réutilisé par la suite.

Ils peuvent être créés / modifiés en cliquant sur « (Changer) » en face de « Données de traitement » sur la page d'accueil du workflow.

Les types de champs de traitement sont exactement les mêmes que les types de champs de formulaires, on peut tous les utiliser. Il suffit donc de choisir un libellé et un type de champ pour avoir créé un champ de traitement.

Une action supplémentaire de workflow «Données de traitement» devient disponible une fois que l'on a configuré au moins un champ de traitement. Cette action va permettre d'initialiser ou de faire varier la valeur de la donnée de traitement.

Si une donnée de traitement est configurée pour être optionnelle (case « Obligatoire » non cochée), elle ne sera affichée dans l'écran de traitement que si elle contient quelque chose. Si elle est vide, elle ne sera pas affichée.

* Studio
* Les tutos

# Les actions de workflow

Les actions de workflow

Le workflow d'une démarche permet aux demandes issues des usagers engagés dans cette démarche d'être traitées conformément au processus « métier » dont elles relèvent.

La progression d'une demande au sein d'un workflow se traduit par un cheminement d'un statut vers un autre, jusqu'à ce que la demande soit instruite.

Le passage d'un statut à un autre est tributaire d'actions affectées à un statut par l'administrateur fonctionnel.

Une action est quelque chose qui doit être réalisée. Si plusieurs actions sont affectées à un statut, elles vont être éxécuté de façon séquentielle. Ainsi si une des actions produit un changement de statut, les actions qui se situent après elle ne seront pas exécutées.

L'ajout d'actions dans un statut s'effectue depuisla barre latéralede la paged'édition d'unstatut.

Les types d'actions

Trois types d'actions sont affectables à un statut.

Les transitions (changer de statut)

Le passage d'un statut à un autre peut s'effectuer selon plusieurs modalités, automatiquement en fonction d'une réponse de l'usager ou d'un délai, ou bien suite à une intervention manuelle.

* Saut à la soumission(obsolète, à ne plus utiliser)
* Saut automatique
* Saut manuel

Les actions de saut affichent une icône flèche qui est un lien vers le statut de destination du saut.

Les interactions avec les usagers (échanger)

Pour affiner la relation entre une collectivité et ses usagers, Publik favorise les occasions d'interactions humaines entre agents et usagers.

* Alerte
* Commentaire(obsolète, à ne plus utiliser)
* Courriel
* Courriel récapitulatif quotidien
* Fichier joint(obsolète, à ne plus utiliser)
* Formulaire
* Message dans l'historique
* Notification au demandeur
* SMS
* Webservice

Agir sur la demande

Un nombre conséquent d'actions sont disponibles pour faire évoluer la demande dans son traitement.

* Anonymisation
* Création de document
* Création d'une demande
* Création d'une fiche
* Données de traitement
* Édition
* Géolocalisation
* Liaisonfonction/rôle
* Modification d'une fiche
* Rattachement d'un usager à une fiche
* Redirection web
* Suppression
* Suppression du code de suivi
* Workflow externe

Agir sur le demandeur

3 actions permettent de modifier les informations liées au demandeur.

* Ajout d'un rôle
* Modification du profil
* Retrait d'un rôle

Conditionner une action

Lorsqu'on édité une action et que l'on clique sur le '+' pour voir les paramètres avancées on peut définir uneconditiondans la zone « Condition ». L'action ne sera exécutée que si la condition est satisfaite.

Dupliquer une action

Afin déviter une reconfiguration parfois fastidieuse, il est possible de dupliquer une action, y compris sur un statut différent du statut dans lequel elle a été créée

* Studio
* Les tutos

# Les statuts de workflow

Les statuts de workflow

La progression d'une demande au sein d'un workflow se traduit par un cheminement d'un statut vers un autre, jusqu'à ce que la demande aboutisse à un statut final.

Les statuts marquent les étapes de progression d'une demande. Le changement de statut d'une demande est tributaire d'actionsaffectées à chaque statut par l'administrateur fonctionnel.

L'administrateur fonctionnel peut consulter les statuts existants au sein du workflow depuis lapage d'accueilde ce dernier.

Création des statuts

L'ajout d'unstatutau sein d'un workflow s'effectue depuis lapage d'accueilde ce workflow en cliquant sur « Nouveau statut » en haut de la liste des statuts.

* Saisir le nom du statut à ajouter.Le champ « Nom » est obligatoire.Choisir un nom explicite compréhensible pour les gestionnaires, usagers et agents d'accueil qui auraient à prendre connaissance de l'état d'avancement, autrement dit du statut, d'une demande.Quand le « Nom » du statut est « ajouté », le statut est créé.
* Répéter cette opération autant de fois que de statuts sont nécessaires pour constituer un workflow.

L'ordre d'apparition des statuts sur lapage d'accueildu workflow en cours de fabrication correspond à l'ordre d'enchaînement des statuts au sein de ce workflow. Cet ordre peut être modifié par « glisser-déposer ».

Propriété d'un statut

Une fois un statut créé, l'administrateur fonctionnel dispose de la possibilité de configurer un certain nombre de ses propriétés.

L'édition des propriétés d'un statut s'effectue depuisla barre latéraledela page d'éditionde ce statut.

Le nom

Le nom du statut identifie le statut. Il permet d'indiquer l'étape du traitement dans lequel se trouve une demande au gestionnaire en charge de son traitement, à l'agent d'accueil qui aurait à renseigner l'usager sur l'état de progression de sa demande et à l'usager lui-même lorsqu'il consulte sa demande.

Le « nom d'un statut » doit donc être choisi afin de rendre immédiatement compréhensible la signification de ce statut, ceci pour l'agent ou pour l'usager et l'agent (cas des statuts visibles par l'usager, cf. infra)

Exemples de noms de statut:« Demande reçue », « En attente de pièce complémentaire », « Demande refusée », « Validé », « Terminé ».

Le caractère final d'un statut

Par défaut, un statut a un caractère final s'il ne débouche sur aucun autre statut. Mais ce caractère final peut aussi être forcé sur un statut particulier même si d'autres statuts le suivent.

Imaginons un statut « Demande clôturée » suivi d'un statut « Demande supprimée ». Il sera utile de donner un caractère final au statut « Demande clôturée » pour que les demandes qui s'y trouvent ne soient pas considérées comme devant être traitées.

En effet dans les listings de traitement, les demandes qui se trouvent dans un statut final n'apparaissent plus dans « Demandes en cours » mais dans « Demandes terminées ».

La visibilité d'un statut

Par défaut, tous les statuts qu'atteint une demande sont visibles dans l'historique de la demande, sur le portail citoyen ou sur le portail agent.

Il est toutefois possible de masquer un statut à l'usager (« Affiché uniquement en backoffice ») ou à tout le monde (« Jamais affiché »), c'est utile pour des statuts technique répétés plusieurs fois et dont on ne souhaite pas qu'ils puissent allonger indûment l'historique de la demande.

Pour masquer un statut, il suffit de cliquer sur « Options » depuis la page du statut et de sélectionner le mode d'affichage souhaité.

Les statuts cachés au demandeur apparaissent grisés dans la liste des statuts.

La couleur d'affichage d'un statut

Pour changer la couleur d'un statut, il faut cliquer sur « Changer l'affichage du statut », puis cliquer sur « ... » sous « Couleur dans le backoffice ».

Attribuer une couleur à un statut permet de discriminer les statuts entre eux visuellement, autrement dit de discriminer les demandes entre elles en fonction de leur état de progression, plus ou moins avancé.

C'est particulièrement utile aux gestionnaires qui travaillent à partir duTableau de borddes demandesd'un formulaire ou depuis leurliste des tâches.

Pour aider les gestionnaires dans leur mission de traitement des demandes, l'administrateur fonctionnel doit penser le choix de couleur d'un statut en ayant en tête qu'elle est censée faciliter l'identification des statuts des demandes, un critère décisif pour le gestionnaire dans son choix d'une demande à instruire. En effet, parmi toutes les demandes à instruire, le gestionnaire doit évaluer lesquelles sont, d'un point de vue stratégique, les plus pertinentes. Parmi ses impératifs figure celui de traiter les demandes dans un temps le plus court possible.

Il est donc fortement conseillé de prévoir un code couleur plutôt que d'opter pour une couleur arbitrairement. Un code couleur permet en effet de distinguer entre eux les statuts selon une logique :

Attribuer une couleur froide ou une couleur chaude peut aider le gestionnaire à distinguer les demandes en début de traitement de celles qui approchent du terme de leur instruction.

Attribuer une même couleur à des statuts de noms différents mais qui ont tous uncaractère finalpeut aider le gestionnaire à visualiser les demandes instruites.

Le texte d'information backoffice

Un éditeur de texte riche permet de rédiger une description de la finalité du statut.

Il est destiné au gestionnaire qui s'apprête à faire évoluer le statut d'une demande depuis lavue détailléede cette demande en cliquant sur le bouton du statut que ce texte décrit.

Il est fortement conseillé d'accompagner chaque statut d'un texte d'information pour éviter les erreurs d'interprétation d'un statut.

La répétition d'un statut

Dans l'onglet "répétition", il est possible de définir un gabarit permettant

[la répétition des actions d'un statut de workflow](https://doc-publik.entrouvert.com/admin-fonctionnel/fabrique-de-workflows/repetition-des-actions-d-un-statut/)

.

* Studio
* Les tutos

# Actions en masse

Actions en masse

Une action en masse permet de déclencher une action sur plusieurs fiches ou demandes simultanément. C'est une action qui se déclenche manuellement depuis la liste des fiches/demandes et après qu'au moins l'une d'entre elle ait été sélectionnée.

Il existe deux façons de mettre en place une action en masse :

* En utilisant une action globale
* Avec une action ayant un identifiant et en limitant la liste des demandes/fiches au statut dans lequel se trouve l'action en question

* supprimer un lot de fiches/demandes (plutôt que de les supprimer une à une),
* passer toutes les demandes qui se trouvent dans un statut donné vers un autre statut : par exemple de « Traitée » à « Clôturée ».

Avec une action globale

Dans le cas où une action globale est définie dans le workflow lié aux demandes à traiter, elle est déclenchable manuellement en masse depuis la page de traitement de ces demandes spécifiques. Il n'y a rien à configurer. Si on sélectionne plusieurs demandes dans le listing de traitement, des boutons relatifs à ces actions apparaissent et permettent d'appliquer l'action à toutes les demandes sélectionnées.

Avec un saut manuel

Les sauts manuels permettent de disposer d'une action en masse de changement de statuts sans passer par une action globale :

* Créer l'action de saut manuel dans un statut donné
* donner un identifiant à cette action de saut manuel

L'action sera disponible comme action en masse dès qu'on sélectionne une ou plusieurs demandes dans le listing (si l'on dispose du rôle nécessaire pour l'utiliser).

* Studio
* Les tutos

# Fonctions de workflow

Fonctions de workflow

Par défaut, tous les workflows comportent deux fonctions :

* Usager : désigne la personne qui remplit le formulaire
* Destinataire : désigne la personne qui traite le formulaire

Pour en définir de nouvelles  (« Élu », « Chef de service », « Superviseur »), il suffit de cliquer sur « Fonctions » sur la page d'accueil du workflow et de choisir un libellé.

La nouvelle fonction peut alors être utilisée dans les actions du workflow.

Fonction et rôles

Tous les formulaires associés au workflow afficheront cette nouvelle fonction : on la verra apparaître sur la page de définition d'un formulaire à côté de «Rôle de Utilisateur» et « Destinataire ». C'est à cet endroit qu'il est possible d'associer initialement un rôle à la fonction nouvellement créée.

Le rôle associé à la fonction peut ensuite varier en cours de workflow grâce à l'actionLiaison fonction/rôle

La fonction est dotée d'un accès en lecture à toutes les étapes du traitement. Si bien qu'une personne pourvue d'un rôle associé à une fonction quelconque, aura accès en lecture à la demande même s'il n'y a aucune action spécifiquement attribuée à la fonction.

Pourquoi attribuer une fonction plutôt qu'un rôle à une action ?

Cette section décrit une méthode obsolète. Les instances récentes ne permettent plus d'associer des rôles aux actions de workflow.

Les actions de workflow peuvent faire référence, indifféremment, à des rôles ou à des fonctions. Il est toujours préférable d'utiliser les secondes, c'est le gage d'une plus grande généricité, cela facilite l'utilisation d'un même workflow par plusieurs formulaires différents.

Pour prendre un exemple il est assez classique d'avoir un traitement où peut intervenir un agent traitant, un service technique, et occasionnellement une supervision (un « chef »); le workflow peut être commun aux demandes traitées par le service « voiries » d'un côté, le service « archives » de l'autre.

Dans le workflow, il peut y avoir des transitions qui sont « envoi au service technique », ou « arbitrage par la supervision », et celles-ci peuvent être associées aux fonctions (liées aux rôles adéquats dans les formulaires respectifs), plutôt qu'avoir en dur « service voiries » dans un premier workflow, puis dans un autre workflow  « service archives ».

Utiliser les fonctions plutôt que les rôles permet aussi, dans un même workflow, d'éviter la répétition de statuts et actions. Par exemple, en imaginant le territoire de la commune divisé entre différentes équipes pour les travaux, plutôt que de multiplier les statuts, « pris en charge par l'équipe A », « pris en charge par l'équipe B », etc., avec chaque fois les mêmes actions (courriel vers rôle A, courriel vers rôle B, commentaire par rôle A, commentaire par rôle B, etc.), on pourra utiliser l'actionliaison fonction/rôlepour dire « voilà le job est pris en charge par l'équipe A, ou l'équipe B », et la suite du workflow ne comptera qu'une action courriel vers la fonction, une action commentaire, etc.

* Studio
* Les tutos

# Vue graphique du workflow

Vue graphique du workflow

Une vue graphique, construite dynamiquement, est présente sur la page d'accueil de chaque workflow.

Dans cette vue, un statut se formalise sous forme de cadre, relié au suivant par une flèche, qui indique le sens de progression de l'un vers l'autre.

Les actions affectées à chacun des statuts sont indiqués sous forme de boucles fléchées signalant le type de l'action, et éventuellement les fonctions associées.

Les cadres et les boucles fléchées sont cliquables.

Ils permettent respectivement d'accéder à :

* La page d'édition d'un statut, en cliquant sur le libellé qui figure dans la vue graphique du workflow.
* La page d'édition d'une action, en cliquant sur le libellé qui figure dans la vue graphique du workflow.

Pour passer la vue graphique en plein écran, il faut aller sur la page d'accueil du workflow et cliquer sur plein écran tout en bas à droite.

* Studio
* Les tutos

# Les tests de workflows

Les tests de workflows

Il est possible d'associer un test de workflow à untest de formulaire. Un test de workflow simule le traitement de la demande (par exemple un clic sur un bouton d'action par le demandeur) tout en vérifiant que les actions attendues ont bien lieu (par exemple l'envoi d'une notification par mail). Le fait que le traitement soit simulé signifie bien qu'aucun mail ou SMS n’est réellement envoyé et qu'aucune demande ou fiche n’est créée.

Créer un test

À partir d'un test de formulaire existant, il faut se rendre sur la page qui présente les données du test. Un lien « Tests de workflow » se trouve en haut à droite.

Il est également possible, à la création d'un nouveau test, d'initialiser la structure des tests de workflow à partir de l'historique d'une demande réelle. Les actions de test correspondant seront alors créées, mais il sera nécessaire, pour la plupart, de compléter manuellement leur configuration.

* Studio
* Les tutos

# Fiche usager

Fiche usager

On arrive sur la fiche usager après sélection d'un usager dans la liste des résultats du moteur de recherche sur le portail agents. La fiche permet de voir en général (les cellules suivantes sont paramétrables) :

* Le profil de l'usager i.e. tous les champs qu'il a complétés (nom, prénom, mail, téléphone, adresse...).
* Les demandes en cours de l'usager (N.B. : certaines demandes peuvent ne jamais être affichées dans cette vue si l'option "Ne pas afficher dans la vue par usager" a été activée au moment du paramétrage de la démarche).
* La possibilité d'initier une nouvelle demandepour le comptede l'usager, « pour le compte » veut bien dire que la demande est rattachée à l'usager exactement comme si il avait saisi lui-même cette demande en étant connecté : il la verra dans la liste de ses demandes en cours.

Pour chaque demande, apparaît :

* le nom de la démarche
* l'étape (statut) du traitement

Si le rôle de l'agent consultant cet écran le permet, en cliquant sur une demande, il peut accéder au contenu (détail, historique) de cette demande.

* Guichet
* Courrier

# Utilisation du code de suivi

Utilisation du code de suivi

La cellule "code de suivi" permet à un agent de retrouver une démarche grâce au code de suivi que peut lui transmettre un usager.

L'agent entre le code et accède à la démarche telle que la verrait l'usager. Il convient donc de faire attention aux champs de coordonnées et vérifier que ceux-ci contiennent bien les informations de l'usager et non celles de l'agent.

Il est possible d'indiquer un ou plusieurs champs qui viennent renforcer la sécurité du code de suivi. Si l'on choisit par exemple le champ « Téléphone », l'usager devra indiquer le numéro de téléphone qu'il a utilisé dans sa demande, en plus du code de suivi, pour pouvoir y accéder.

Les blocs de champs ne sont pas directement utilisables comme champs de contrôle. Il est possible de passer par un champ de type donnée calculées alimenté par un champ du bloc. Pour que cela fonctionne, la donnée calculée doit être positionnée sur la page suivant celle du bloc.

* Il existe une balise{% temporary_access_url %}pour obtenir une adresse d’accès temporaire à une demande, sans authentification. Cette balise peut s'accompagner de paramètres du type{% temporary_access_url minutes=15 bypass_checks=True %}pour définir une durée de validité (30 minute par défaut) et s'affranchir des validations supplémentaires (champs) demandées avec le code de suivi. Cette balise pourra avantageusement remplacer le code de suivi lorsqu'il est utilisé pour de courtes durées.
* Il existe également une balise {% temporary_access_button %}. Ce tag fonctionne de la même manière que {% temporary_access_url %} ajouté récemment, sauf qu'il est utilisé exclusivement pour afficher un bouton dans un courriel.

* Guichet
* Courrier

# Saisie pour le citoyen (saisie backoffice)

Saisie pour le citoyen (saisie backoffice)

Il est possible de permettre à l'agent de saisir une démarche pour le compte d'un citoyen. L'agent peut soit initier sa saisie puis sélectionner l'usager dans la barre latérale, soitrechercher le citoyenoului créer un compte, et une fois sur sa fiche, choisir la démarche à remplir. Les champs de l'usager seront préremplis (si configuré dans le formulaire) avec les informations issues du profil de l'usager.

De plus, dans la barre latérale, l'agent peut également saisir le canal de la demande (guichet, courriel, téléphone...)

Pour être accessible dans le portail Agents, la démarche doit avoir été configurée pour permettre la saisie backoffice.

La barre latérale va permettre d'afficher des informations sur mesure, configurée par l'administrateur. Il est possible de demander à l'administrateur l'affichage de telle ou telle information manquante.

Par ailleurs, cette barre permet de chercher dans la base des utilisateurs pour associer en cours de saisie, la demande à un utilisateur présent dans la base.

La barre latérale permet enfin de choisir le canal d'entrée de la demande.

Entrée de menu "Saisie"

Dans le menu de gauche du backoffice, une entrée "Saisie" envoie vers une page « Saisies entamées » pour séparer la saisie d'une nouvelle demande des saisies en cours.

* Guichet
* Courrier

# Créer un compte pour le citoyen

Créer un compte pour le citoyen

Si les droits d'accès ont bien été configurés, il est possible pour l'agent d'accueil de créer une fiche pour un usager. Cette démarche, accessible depuis le portail Agents, permet de renseigner les informations de l'usager tel quel l'usager l'aurait fait.

Exemple de bouton :

Ajouter un utilisateur

L'interface d'ajout d'utilisateur se présente ainsi (les champs obligatoires sont notés avec un * rouge) :

Le mot de passe

Il est conseillé de cocher la case « Envoyer un courriel à l'utilisateur pour qu'il choisisse son mot de passe ». Il est également possible de choisir « Générer un mot de passe », dans ce cas, il faut penser à cocher la case « Envoyer les informations à l’utilisateur ».

En aucun cas il ne faut indiquer un mot de passe manuellement.

Ensuite, l'agent est redirigé vers la fiche de l'usager et peut créer une démarche pour son compte.

La connexion avec FranceConnect

Avec une connexion FranceConnect, des informations usager sont récupérées et automatiquement renseignées par défaut dans le profil utilisateur de Publik. Par exemple, le nom par défaut du profil est alors le nom de naissance.

Ces informations validées par FranceConnect, source de confiance, doivent rester verrouillées et ne pas être modifiées. De la même façon, les champs des formulaires préremplis par les champs du compte utilisateur (uniquement les champs renseignés par FranceConnect) seront également verrouillés.

Dans le besoin particulier et justifié d'un nom d'usage, ou d'époux, il convient de créer un champ facultatif à cet effet.

Des situations peuvent nécessiter des actions particulières :

* le cas des agents qui fédèrent leur compte agent avec une identité FranceConnect d'un usager. Une opération d'administration (réalisé via le support) nécessite de supprimer la liaison, et permettre le retour à la "normal" du compte.
* le cas d'un usager qui souhaite délier son compte FranceConnect. La dé-liaison d'un compte FranceConnect peut être faite par l'usager ou par une opération d'administration (réalisé via le support), mais ne déverrouille pas les informations du compte prérenseignées.
* le cas d'un usager qui souhaite modifier ses informations verrouillées. Cette action n'est pas possible, et remet en cause le principe de source de confiance de FranceConnect.

* Guichet
* Courrier

# Guichet

Guichet

La page d'accueil du portail agents est habituellement configurée pour afficher en premier un champ de recherche qui permettra de trouver

* unedemandeen particulier (par son numéro, par son code de suivi et/ou une chaîne de caractères présente dans la demande),
* et/ou un usager.

Cette cellule de recherche peut être affichée à tous les agents accédant au back-office ou restreinte en visibilité à un rôle en particulier, tel « Agent d'accueil », par exemple.

Il est également possible (suivant configuration du portail agents) d'afficher à la suite toutes les démarches qui peuvent être saisies en back-office par l'agent connecté. Sont affichées à l'agent, dans un cadre intitulé « Nouvelle demande », toutes les démarches pour lesquelles il a un rôle lui permettant d'en faire la saisie backoffice (paramétrage via Studio > Formulaires > Rôle pour la saisie backoffice). Il est important de noter que les demandes saisies de cette façon sont équivalentes à des demandes saisies par un usagernon connecté: l'usager recevra des courriels mais cette demande ne sera pas lié à son compte ; si l'usager possède un compte, il est bien sûr préférable de saisir la demande en son nom, cf.Fiche usager.

* Guichet
* Courrier

# Courrier

Courrier

L'accueil courrier est particulier en ce qu'il est un canal de communication asynchrone : quand le courrier de l'usager est traité, l'usager n'est pas présent et ne peut être interrogé pour qualifier sa demande.

Un autre point majeur à garder à l'esprit est qu'un courrier papier, tout comme un courriel électronique,n'est pasune demande ; en effet, dans un courrier l'usager ne veut peut-être pas exprimer une demande mais juste transmettre une information ou, au contraire, exprimer de multiples demandes et alors peut-être de manière partielle. Pour plus d'informations, veuillez vous référer à «Une GRU n'est pas un logiciel de gestion de courrier».

Il est possible d'associer un courrier, reçu de la part d'un usager, à une demande lors de la saisie en mode guichet (back-office), si le formulaire a été construit pour ce faire ; une fois cette association réalisée, il sera encore nécessaire de compléter la (ou les) demandes avec les informations présentes dans le courrier ; cette opération est possible via copier-coller si les courriers remontés ont été préalablement traités par reconnaissance optique de caractères.

* Guichet
* Courrier

# Téléphone

Téléphone

L'accueil téléphonique n'est pas fondamentalement différent de l'accueil au guichet puisqu'il s'agit, dans les deux cas, d'une communication synchrone. Dans les deux cas, la page de l'agent d'accueil lui permet de trouver une demande, un usager, saisir une nouvelle demande en mode libre ou en mode « pour le compte de ». Il est d'ailleurs possible aux agents d'accueil du guichet d'effectuer en même temps un accueil téléphonique avec ce même écran.

Néanmoins, en cas de couplage téléphonie-informatique (liaison entre Publik et votre système de téléphonie), il est possible d'ajouter des fonctionnalités propres à l'accueil téléphonique (si votre système est supporté par Publik et si le paramétrage adéquat a été effectué).

Dans ce cas, au début de l'appel, Publik sera notifié du numéro entrant et une recherche d'usager sera automatiquement lancé sur la base de celui-ci ; si unefiche usagerexiste avec ce numéro dans la base utilisateurs alors cet usager sera automatiquement affiché sur l'écran d'accueil de l'agent ; l'agent pourra donc renseigner très précisément, et rapidement, l'usager.

* Guichet
* Courrier

# Chercher une demande

Chercher une demande

Dans certaines situations, le gestionnaire sait exactement quelle(s) demande(s) il souhaite pointer.

Publik permet au gestionnaire de rechercher explicitement une demande selon les caractéristiques suivantes :

Le code de suivi d'une demande

Si la démarche est prévue pour ça, chaque demande d'usager introduite s'accompagne d'une référence, appelléecode de suivi.

La barre latérale de droite de l'écran « Traitement » met à disposition un champ de recherche que le gestionnaire peut renseigner en saisissant le code de suivi attribué à une demande.

Le champ de recherche « Code de suivi » est configuré pour n'accepter que les données respectant la syntaxe d'un code de suivi, à savoir une série de huit caractères majuscules.

Le nom de l'usager qui a introduit une demande

Lafiche usagermet à disposition du gestionnaire un champ à saisir du nom d'un usager.

De cette manière, le gestionnaire peut visualiser toutes les demandes effectuées par un même usager, qu'elles soient clôturées ou non, et ce quelque soit la démarche associée à ses demandes.

* Guichet
* Courrier

# Créer un formulaire conditionnel

Créer un formulaire conditionnel

Les formulaires conditionnels permettent de rendre un formulaire dynamique, d'afficher ou non certaines pages en fonction des réponses de l'utilisateur à certaines questions. L'affichage des pages peut en effet être soumis à des « conditions ». Ces conditions sont remplies, ou non, en fonction des réponses de l'utilisateur.

Exemple de formulaire conditionnel : si l'usager répond « non » à la question « Possédez-vous un véhicule ? », je ne vais pas lui afficher la page de formulaire concernant la description du véhicule.

Nom de variables

Champs d'un formulaire

Lesvariablessont construites sur la base des identifiants que l'on peut donner à chaque champ. Attribuer un identifiant est indispensable s'agissant d'un champ qui va être utilisé pour conditionner l'affichage d'une page. On utilisera en effet la variable (de la forme form_var_identifiant) pour écrire la condition décidant de l'affichage de la page en question.

Les intitulés desvariablessont soumis à des règles, ils peuvent contenir des chiffres ou des lettres, sans caractères spéciaux à l'exception du caractère underscore (on remplace généralement les espaces par le caractère underscore : "_").

Hors champs

En dehors des champs des formulaires utilisés pour créer des démarches, il existe un grand nombre devariables(qui peuvent aussi être utilisées dans les conditions), comme par exemple les données du profil d'un usager. Elles sont d'un maniement souvent plus complexe que les simples variables de champs et réservées à un usage avancé.

Pages conditionnelles

Les champs de type «Nouvelle page» sont les seuls à posséder une option particulière - accessible lorsqu'on les édite - « Condition » . C'est dans ce champ que l'on va écrire la règle décidant si cette page doit être affichée ou non.

Nous avons vu que l'on pouvait attribuer un identifiant à un champ, lavariable, construite sur la base de l'identifiant, peut être utilisée pour écrire la condition d'affichage de la page. La condition s'écrira alors selon la forme suivante :form_var_identifiant == "libellé du choix"

Respectez la casse !

La casse est importante (majuscule / minuscule). Si vous ne la respectez pas dans l'écriture de la condition, cela ne fonctionnera pas.

Il est nécessaire d'ajouter, avant l'identifiant, le préfixe« form_var_» et d'utiliser un opérateur comme==(qui signifie « égal à »). Enfin il faut faire figurer, entre guillemets, la valeur exacte (respect de la casse et de l'accentuation) de la réponse attendue pour que la condition soit respectée.

Si la réponse de l'utilisateur correspond à celle qui figure dans la condition, la page est affichée, dans le cas inverse elle ne l'est pas.

Exemple : si l'identifiant du champ « Possédez-vous un véhicule ? » est « vehicule » et que je veux que la page s'affiche quand la réponse est « Oui », la condition s'écriraform_var_vehicule == "Oui"

Remarque : si plusieurs lignes de condition sont complétées alors chacune des lignes doit être vérifiée.

Cases à cocher

Ce qui précède s'applique aux champs de type liste. Concernant les champs de type case à cocher, ils ne prennent que deux valeurs « True » (quand la case est cochée) et « False » (quand la case est décochée).

En reprenant l'exemple de la page concernant un véhicule mais avec une case à cocher ayant comme identifiant « vehicule », la condition s'écriraform_var_vehicule == "True"

Liste à choix multiples

Dans ce cas, la condition s'écrira"bleu" in form_var_vehicule; si besoin de plus d'informations, référez-vous àutiliser les conditions.

Utilisation d'opérateur avancés

Nous avons vu des conditions simples, permettant de tester une réponse unique. Mais il est possible d'aller plus loin.

Nous nous basons, dans les exemples qui suivent, sur la syntaxe Django, qui est celle qui devra être utilisée par défaut. Historiquement, les conditions étaient écrites en langage Python. Vérifiez que c'est bien la syntaxe Djanqo qui est sélectionnée dans votre condition (à côté de l'engrenage), si vous souhaitez utiliser ces exemples.

Les opérateurs avancés permettent de faire des conditions plus subtiles telle, « je veux cette réponse ET cette réponse » ou encore, « je veux cette réponse OU cette réponse » pour déclencher l'affichage de la page :

* and: permet d'écrire une condition dans laquelle les deux propositions liées par leanddoivent être vraies pour déclencher l'affichage de la page.
* or: permet d'écrire une condition dans laquelle une, au moins, des deux propositions liées par leordoit être vraie pour déclencher l'affichage de la page.
* not: permet d'écrire une condition dans laquelle la proposition qui suit lenotne doit pas être vraie pour déclencher l'affichage de la page
* in"ELEMENT1 ELEMENT2"|split: permet d'écrire une condition dans laquelle la variable doit contenir un des éléments de la liste pour que la condition soit vraie et déclenche l'affichage de la page.
* !=: signifie "différent de", permet d'écrire une condition dans laquelle les propositions de part et d'autre de l'opérateur ne doivent pas être égales pour que la condition soit vraie et déclenche l'affichage de la page.
* <, >, <=, >=: opérateurs de comparaison numériques. Inférieur, supérieur, inférieur ou égal, supérieur ou égal. Pour pouvoir utiliser ces opérateurs, il faut transformer sa variable en nombre grâce aufiltre|decimal.

Exemples

* form_var_vehicule == "Oui" or form_var_achat_vehicule == "Oui"va déclencher l'affichage de la page consacrée aux véhicules si l'utilisateur a indiqué qu'il avait un véhicule ou s'il a dit qu'il allait en acheter un (identifiant : « achat_vehicule »).
* form_var_jour != "jeudi" : signifie «différent de ». Le jour ne doit pas être jeudi pour que la condition soit vérifiée.
* form_var_couleur in "Bleu Rose Vert"|split:  si la réponse est une des valeurs entre guillemets, la condition sera vérifiée.
* form_var_nombre_de_reservations|decimal > 1: À partir de deux réservations, la condition sera vérifiée.
* form_var_inscription_newsletter == "False" or  form_var_courriel: si on souhaite s'inscrire à la newsletter, le champ courriel devient obligatoire

Conditions en sortie de page

Les conditions évoquées jusqu'alors permettent de provoquer l'affichage ou non d'une page. Mais les champs de type «Nouvelle page» permettent également d'écrire des conditions « en sortie de page », c'est-à-dire des conditions qui si elles ne sont pas vérifiées empêcheront le passage à la page suivante. Lorsque l'on écrit une condition de sortie de page, il faut impérativement l'accompagner d'un message d'erreur significatif pour l'usager, ce message d'erreur sera affiché lorsque la condition ou les conditions ne sont pas satisfaites (et il est alors impossible pour l'usager de passer à l'étape suivante de la démarche, jusqu'à ce qu'il apporte les corrections nécessaires).

* Exemple 1 : avec une condition de sortie de page ainsi rédigée « form_var_courriel1 == form_var_courriel2 », la page concernée ne pourra être validée que si les adresses électroniques saisies dans les deux champs portant ces identifiants sont identiques.
* Exemple 2 : une condition de sortie de page « form_var_tel1 or form_var_tel2 », vérifiera qu'au moins un des deux champs a été complété. Le message d'erreur à associer si la condition n'est pas remplie pourrait être : « Veuillez saisir au moins un n° de téléphone », par exemple.
* Exemple 3 : une condition de sortie de page « "fontenay" in form_var_ville|lower » sera vraie si la chaîne de caractères « fontenay » ou « Fontenay-Sous-Bois » ou « FONTENAY » est saisie dans le champ « form_var_ville ». Lefiltre|lower transforme en effet le contenu de la variable en minuscules. Le message d'erreur à associer si la condition n'est pas remplie pourrait être par exemple : « Votre signalement doit nécessairement concerner le territoire de la commune de Fontenay ».

Plusieurs conditions de sorties sont possibles cumulativement via « Ajouter une ligne », dans ce cas toutes les conditions doivent être respectées (équivalent d'un « and» si l'expression était rédigée sur une seule ligne). Tous les exemples donnés sur cette page utilisent des variables issues d'un formulaire et les conditions uniquement dans les champs page. Mais il y a d'autres endroits ou l'on peututiliser les conditionset d'autres variablesdisponibles.

* Studio
* Les tutos

# Les tests de formulaires et modèles de fiches

Les tests de formulaires et modèles de fiches

Les tests permettent d’automatiser les vérifications du bon fonctionnement d’un formulaire ou d'un modèle de fiche, après chaque modification. Ils peuvent ensuite être complétés par lestests de workflow.

Par exemple, si l’on veut simplifier la condition d’affichage d’un champ sur la cinquième page d’un formulaire, il peut s’avérer fastidieux de ressaisir le formulaire jusqu’à cette page pour s’assurer du bon affichage du champ. Avoir préalablement créé un test pour ce cas permet d’éviter ces vérifications fastidieuses : l’exécution réussie du test suite aux modifications donnera, en un clic, l’assurance que rien n’est cassé.

Pour accéder aux tests liés à un formulaire, il faut se rendre sur la page d’édition de celui-ci. Le lien se trouve en barre latérale.

Un test est un simple enregistrement des données d’une demande. Lors de la création d’un nouveau test, il est possible de démarrer une saisie manuelle, ou de gagner du temps en important les données d’une demande réelle. Dans les deux cas, les données pourront ensuite être modifiées librement.

Exécuter les tests

L’exécution d’un test consiste à jouer la saisie d’une demande à partir des données enregistrées. Si la saisie arrive à son terme sans rencontrer d’erreur, le test est réussi.

Les tests peuvent être lancés manuellement. Ils sont également exécutés de manière automatique à chaque modification du formulaire. Si l'exécution automatique donne un résultat différent du dernier résultat connu, par exemple si une nouvelle erreur s'est produite, ce dernier apparaîtra attaché à la modification qui a déclenché l’exécution, visible dans l’historique du formulaire.

Tester une erreur

Il est également possible de tester les cas où un formulaire doit afficher une erreur. Pour cela il faut saisir manuellement un nouveau test, puis compléter le formulaire jusqu’à rencontrer l’erreur attendue. Un bouton apparaît en barre latérale, qui permet d’enregistrer le test, alors même que la saisie n’est pas terminée.

Le principe est alors inversé : le test est considéré comme réussi tant que la saisie des données enregistrées provoque l’erreur attendue.

Tester un appel webservice

Lorsqu’un formulaire contient une condition basée sur un appel webservice utilisant la méthode GET, cet appel sera effectué à chaque exécution du test. En plus de ralentir l'exécution du test, son succès sera dépendant du bon fonctionnement du service distant. Pour éviter cela, il est possible de simuler la réponse du service distant : aucune requête réelle ne sera effectuée, mais tout se passera comme si le service avait renvoyé la réponse prévue.

L’ajout d’une réponse s’effectue depuis la page d’un test, via le lien en barre latérale « Réponses webservice ». On doit renseigner à minima l’adresse exacte qui sera appelée, et le contenu de la réponse au format JSON. Il est possible de restreindre une réponse à certains paramètres, pour par exemple renvoyer une réponse différente en fonction de la valeur d’un paramètre de requête.

Lorsqu’un formulaire contient une condition basée sur un appel webservice utilisant une méthode différente de GET, cet appel sera bloqué afin d’éviter le déclenchement d’une modification dans un service distant à chaque exécution du test. Il est alors obligatoire de définir une réponse webservice à utiliser.

Utilisateurs de test

Pour tester la saisie d’une demande en mode connecté, il est nécessaire de renseigner un utilisateur dans les options du test.

Ces utilisateurs ne sont pas des comptes réels, gérés dans la brique « Connexion », mais des utilisateurs internes à la brique « Démarches », à l’usage exclusif des tests. On peut accéder à la liste des utilisateurs de test à partir de la page listant les tests d’un formulaire, le lien se trouve en barre latérale.

À noter que lors de la création depuis une demande existante, soumise en mode connecté, un utilisateur de test correspondant au demandeur est créé automatiquement.

Dépendances entre les tests

Cette fonctionnalité est particulièrement utile dans le cadre d'une application, car elle permet de tester des formulaires et des modèles de fiche qui dépendent les uns des autres.

Exemple

Prenons un formulaire qui ne doit être soumis qu'une seule fois par un même usager. Pour cela on peut imaginer une condition de sortie de page du typeform_objects|current_user|count == 0. Par défaut, quand on crée un test et qu'on l'exécute, cette condition est toujours vraie, car l'utilisateur rattaché au test n'est pas un utilisateur réel et ne peut donc pas avoir de demandes qui lui sont rattachées.

Pour vérifier que cette condition fonctionne, il faut pouvoir provoquer la situation où l'utilisateur de test aurait déjà soumis une demande. C'est possible en ajoutant une dépendance :

* Créer un test passant classique.
* Lancer les tests.
* Créer un deuxième test. Lors de l'édition des données, en barre latérale, cliquer sur « Modifier les dépendances », et sélectionner le test précédent.
* Tenter de passer à la page suivante, l’erreur apparaît, cliquer sur « Marquer le test comme devant échouer ».

Détails de fonctionnement

Quand un test a des dépendances, son exécution déclenche l'exécution préalable de ces dernières. Tous les objets créés par ces dépendances, que ce soit le formulaire soumis en lui-même ou des fiches créées par le workflow, seront disponibles dans le contexte du test.

Pour que l'édition d'un test dépendant d'autres tests soit possible, il est nécessaire que ces tests aient été exécutés au moins une fois (étape 2 de l’exemple ci-dessus). En effet, si à l'exécution du test les objets sont créés, à l'édition ils n’existent pas encore : c'est alors les derniers résultats connus des dépendances qui sont disponibles dans le contexte d'édition.

* Studio
* Les tutos

# Les champs d’un formulaire

Les champs d’un formulaire

Les différents types de champs

On peut différencier les champs en deux grands types :

* ceux qui permettent de récupérer une information fournie par l’usager : les champs à renseigner,
* ceux qui servent à afficher et structurer les informations que l’on présente à l’usager : les champs de mise en forme.

Champs de mise en forme

Publik met à disposition quatre types de champs de mise en page :

* Titre: structure sous forme de paragraphes les champs à saisir d’un formulaire.
* Sous-titre: structure en sous-paragraphes les champs à saisir d’un formulaire.
* Commentaire: intègre au sein d’un formulaire un texte à l’attention des usagers.
* Nouvelle page: structure en pages les champs à saisir d’un formulaire.

Champs à renseigner (données)

* Carte: affiche à l’usager une carte géographique dans laquelle il peut pointer une localisation.
* Case à cocher (choix unique): permet à l’usager de valider une affirmation soumise par le formulaire.
* Courriel: sollicite auprès de l’usager une adresse électronique.
* Date: destiné à la saisie d’une date.
* Donnée calculée
* Fichier: permet à l’usager de joindre un document à un formulaire.
* Liste: affiche une liste déroulante d’éléments au sein de laquelle l’usager peut en sélectionner un.
* Liste à choix multiple: soumet une liste déroulante d’éléments au sein de laquelle l’usager peut en sélectionner plusieurs.
* Mot de passe: permet la saisie d’un texte qui ne sera pas affiché à l’écran.
* Nombre: permet la saisie d'un nombre.
* Texte (ligne): permet à l’usager de saisir du texte libre tenant sur une seule ligne.
* Texte long: permet à l’usager de saisir un texte libre.

Selon la configuration du site certainschamps dépréciéspeuvent également apparaître :

* Tableau: affiche un tableau dont les cellules peuvent être renseignées par l’usager.
* Tableau de listes: affiche un tableau dont les cellules sont composées de listes déroulantes d’éléments à sélectionner.
* Tableau de longueur libre: affiche un tableau dans lequel l’usager peut ajouter des lignes en fonction des données qu’il a à encoder.
* Élements classés: affiche à l’usager une liste d’éléments précédés d’une zone de saisie permettant de les numéroter pour les ordonner.

L’ordre des champs

Les champs peuvent être déplacés (un par un) par drag-and-drop, en « attrapant » la poignée à la gauche de la ligne. Remarque : un champ peut être basculé d’une page à l’autre par le même procédé.

Le paramétrage des champs

Tous les champs offrent des options accessibles lorsqu’on les édite. Les options spécifiques à un type de champs particulier sont décrites dans la page du champ lui-même.

Il existe aussi desparamètres génériques, communs à tous les champs

Le préremplissage

Pour faciliter le remplissage d’un formulaire par le citoyen, il est indispensable depréremplir les champsà chaque fois que c’est possible. Il est possible de préremplir des listes ou des champs texte.

* Studio
* Les tutos

# Paramètres des champs

Paramètres des champs

Paramètres génériques

Il y a un certain nombre de paramètres communs à tous les types de champ :

* Libellé: Il s'agit du texte tel qu'il sera affiché à l'usager qui remplit le formulaire
* Obligatoire(oui/non) : si un champ est coché « obligatoire », ce dernier doit obligatoirement être renseigné par l'usager. Il n'est pas possible de valider le formulaire (ou de passer à la page suivante en cas de questionnaire multi-pages) sans cela, un message explicite est affiché à l'usager lorsque le champs n'est pas renseigné, NB : ce paramètre est actif par défaut (sauf pour « Case à cocher (choix unique) ».
* Remarque: texte d'aide qui sera affiché à l'usager (en général sous le champ à remplir)
* Identifiant: pour ré-utiliser par ailleurs (affichage, calcul, transmission via webservice, ...) la valeur saisie par l'usager, il est impératif d'attribuer un nom de variable qui est au choix de l'administrateur (en savoir plus sur les variables)
* Affichage:Page de récapitulatif : le champ sera affiché sur le page de confirmation, avant que l'usager ne valide sa demandeRésumé de la demande : le champ sera affiché sur le résumé de la demande dans le back-office, à l'agentTableaux de traitement (anciennement nommé "Affichage dans les listings") : le champ sera affiché dans les tableaux de résultats accessibles via l'onglet traitement, NB : ce paramètre est désactivé par défaut.Pour les champs fermés (listes, listes à choix multiple et case à cocher) une case à cocher supplémentaire « Statistiques » permet de rendre ces champs disponibles dans lacellule Grapheet dans lerequêteur statistique.

* Classes supplémentaires pour les styles CSS: permet d'utiliser un style particulier défini par une classe dans la feuille de style, en dérogation au thème général déclaré pour le formulaire dans son ensemble. Utile par exemple pour aligner plusieurs champs grâce à unsystème de grille (grid).
* Condition d'affichage: permet de déclarer une condition suivant laquelle s'affichera ou non le champ en fonction d'une réponse apportée à un champ précédent, NB : il est important qu'un champ conditionné vienneaprèsles champs mentionnés dans la condition d'affichage.
* Préremplir: valeur par défaut attribuée au champ, la liste des valeurs possibles varie suivant le type de champ (en savoir plus sur le préremplissage). Un champ prérempli peut être verrouillé (c'est-à-dire rendu non modifiable) en cochant la case prévue à cet effet.
* Anonymisation: Elle peut être finale ou intermédiaire (cela fait référence à l'action d'anonymisationqui peut elle-même être finale ou intermédiaire). Pour chaque champ il est possible d'indiquer s'il est concerné par un type d'anonymisation et/ou l'autre.

Focus sur les grilles CSS

Un système de grille adaptative sur douze colonnes est proposé pour le formatage des formulaires.

Attention

Lorsque l'on utilise grid sur un champ ou une cellule, il devient obligatoire de l'utiliser sur tous les champs (ou toutes les cellules) de la même page. Sans cela on peut avoir des comportements erratiques et en particulier des différences d'affichage entre front et backoffice.

Système de grille

Chaque classe CSS pour un élément de la grille est décrit numériquement par sa largeur. Par exemple,grid-1-2pour un élément faisant la moitié de la largeur,grid-2-3pour un élément en faisant les deux-tiers. Les dénominateurs possibles sont 2, 3, 4, 6 et 12.

Pour forcer un retour en début de ligne, ou pour assurer un rendu correct quand les éléments d'une ligne n'ont pas tous la même hauteur, une classe supplémentaire,newlinepeut être posée sur le premier élément de la nouvelle ligne.

Sur des écrans de petite dimension, la grille est automatiquement adaptée pour ne pas rétrécir outre mesure les éléments, la largeur de ceux-ci est doublée, par exemple un élément configuré pour une largeur d'un quart d'écran prendra non pas un quart d'écran mais un demi écran.

Sur les très petits écrans, la mécanique de grille est totalement annulée et tous les éléments de grille sont affichés sur toute la largeur disponible. Il est cependant possible d'empêcher ce comportement en accompagnant la classegrid-x-yde la classenever-alone.

* Studio
* Les tutos

# Écrans de traitement

Écrans de traitement

Plusieurs écrans de traitement sont à la disposition de l'agent et il est important de savoir les distinguer pour éviter toute confusion.

Liste des tâches: il s'agit de la liste regroupant les demandes sur lesquelles une action de l'agent est attendue.

Liste des démarches: c'est la liste de toutes les démarches (formulaires) qui sont à la charge de l'agent.

Tableau de bord: c'est la liste, pour une démarche particulière, des demandes qui ont été remplies.

Détails d'une demande: c'est l'écran permettant de traiter une demande particulière.

L'écran d'accueil sur lequel on arrive en cliquant sur l'icône "traitement", dépend de la configuration de Publik, il s'agira soit :

* De la liste des tâches (la liste des démarches est alors accessible en cliquant sur "vue par formulaires" dans la colonne de droite sur cet écran).
* De la liste des démarches (la liste des tâches est alors accessible en cliquant sur "vue globale" dans la colonne de droite sur cet écran).

* Exports

# La page d’édition des champs d'un formulaire

La page d’édition des champs d'un formulaire

Le contenu d'un formulaire, autrement dit l'ensemble des informations à obtenir de la part d'un usager pour formaliser une demande est constitué de champs que l'administrateur fonctionnel doit mettre en place.

Liste des champs du formulaire

Cette liste est vide si le formulaire ne contient aucun champ. Pour chaque champ elle permet de voir :

* le libellé
* le type de champ
* le caractère optionnel d'un champs (s'il est obligatoire, rien n'est affiché)
* le nom de variable du champ entre {{ }}

Par ailleurs, chaque champ est accompagné de trois boutons permettant  de :

* Paramétrer un champ(«Modifier», au survol)
* Dupliquer un champ
* Supprimer un champ

La barre latéraleoffre deux fonctionnalités :

* Ajouter un « Nouveau champ»
* Importer les champs depuis (un formulaire)

* Studio
* Les tutos

# Liste des demandes

Liste des demandes

La liste des démarches n'affiche que les démarches dont le traitement a été explicitement assigné aux agents qui la consultent.

Classement suivant l'action attendue de votre part

Les demandes sont classées en deux blocs :

* "Formulaires à votre charge", sont rangées ici les demandes, par formulaires, pour lesquelles une action est attendue de votre part,
* "Autres formulaires", sont rangées ici les demandes, par formulaires, pour lesquelles aucune action n'est attendue de votre part.

Un formulaire (ou démarche) pourra donc être à un moment dans le premier bloc (vous devez traiter au moins une demande au sein de la démarche) et à un autre moment dans le deuxième bloc (aucune demande n'attend de traitement de votre part à cet instant précis).

Catégorie d'appartenance des démarches

Le deuxième critère de classement des démarches est la catégorie. Lors de la création d'un formulaire, le formulaire doit être associé à une catégorie (correspondant en général à une thématique claire pour l'usager), si aucune catégorie n'a été attribuée, la démarche est rangée dans la catégorie "Divers".

Libellé des démarches

Le libellé d'une démarche permet de l'identifier.

Le libellé d'une démarche est un lien qui pointe vers letableau de bordde la démarche dont le libellé aura été sélectionné, détaillant les demandes associées à cette démarche.

Nombre de demandes

Pour chaque démarche, un badge affiche le rapport "Nombre de demandes à instruire/Nombre de demandes instruites" pour chaque démarche listée.

Barre latérale droite

Depuisla barre latérale à droite de l'écran, le gestionnaire a la possibilité d'affiner l'affichage des demandes selon trois critères :

Statistiques globales

Le module de "Statistiques globales"permet de quantifier le volume des demandes, toutes démarches confondues, selon la catégorie d'appartenance des démarches dont elles sont issues, le libellé des démarches dont elles sont issues, ainsi que leur date d'émission.

Cette vuepermet d'afficher les demandes d'un usager, toutes démarches confondues, dont l'identité aura été renseignée dans le champ de saisie "Recherche" prévu à cet effet.

Liste des tâches

Cette vue permet d'afficher dans un tableau les demandes associées à une démarche en fonction des variables suivantes :

* Le libellé de la démarche.
* La date et l'heure de création de chaque demande.
* La date et l'heure de la dernière modification de chaque demande.
* Le nom de l'usager à l'origine de la demande.
* Le statut actuel de la demande.

Code de suivi

Le champ "Code de suivi" permet de retrouver une demande particulière en saisissant soncode de suividans le champ de recherche.

* Exports

# Liste des formulaires

Liste des formulaires

La liste des formulaires offre une vue générale, structurée par catégorie, des formulaires existants. La liste autorise un accès audétailde chacun des formulaires, en cliquant sur leur titre.

Zone principale

Les formulaires y sont classés par catégories

* La catégorie du formulaireLa catégorie est attribuée au formulaire lors dela création du formulaireet peut être modifiée après sa création depuis la vuedétail du formulaire. Si aucune catégorie ne lui a été attribuée, le formulaire sera classé dans la catégorie « Divers ».Exemples : « Emploi », « Signalement », « Famille », « État-civil ».
* Le titre du formulaireDéfini au moment dela création du formulaire, le titre d'un formulaire, si l'on clique sur celui-ci, donne accès à la pagedétailde celui-ci.
* L'état d'activation du formulaireLes formulaires activés sont en bleu et les formulaires désactivés se distinguent par un titre gris.Un usager ne peut saisir un formulaire (engager une démarche) qu'à la condition que le formulaire ait été activé.Un formulaire est désactivable depuis la pagedétaildes formulaires, à laquelle l'administrateur fonctionnel accède en cliquant sur le libellé du formulaire à désactiver.

L'administrateur fonctionnel dispose de deux possibilités pour ajouter un formulaire à la liste :

* Ajouter un«Nouveau formulaire»
* Importer (un formulaire)

Il est également possible de dupliquer un formulaire existant pour l'adapter et en fabriquer un nouveau, ceci se fait depuis le détail d'un formulaire (action « Export »).

* Studio
* Les tutos

# Création d'un formulaire

Création d'un formulaire

Si l'administrateur fonctionnel n'a pas à sa disposition un formulaire existant, proche de celui qu'il souhaite créer, à adapter, il peut le créerex nihilo.

La création d'un nouveau formulaire se se fait via le lien « Nouveau formulaire » situé dans labarre latéraledela liste des formulaires, accessible depuisla brique«Fabrique de formulaires» duportail agent.

* Saisir le Titredu formulaire à créer.Le champ « Titre » est obligatoire.Choisir un libellé concis et sans ambiguïté afin de faciliter l'identification par l'usager de l'objet de la démarche.Le titre d'un formulaire (et donc de la démarche) peut être modifié, après création du formulaire, depuis la vuedétailde ce formulaire.
* Choisir, dans la liste déroulante,le workflow(circuit de traitement) qu'intégreront les formulaires lorsqu'ils auront été saisis par un usager ou unagent d'accueil.Cette liste comprendle workflow par défautlivré avec Publik ainsi que les workflows fabriqués par l'administrateur fonctionnel.Le workflow attribué au formulaire peut être modifié après création de ce dernier, dans la vuedétail d'un formulaire.Si aucun des workflows existants dansla liste des workflowsque la liste déroulante présente ne convient au formulaire, il sera toujours temps, après création du formulaire, deFabriquer un workflow, puis de l'attribuer au formulaire depuis la vuedétailde ce dernier.
* Choisir, dans la liste déroulante,la catégoried'appartenance du formulaire.La démarche associée au « Nouveau » formulaire hérite de sa catégorie.Par défaut, le formulaire (et donc la démarche) n'est pas classé.La catégorie d'un formulaire peut être modifiée depuisle détail d'un formulaire.Si aucune des catégories suggérées ne convient au formulaire, il s'agira alors, après création du formulaire, de créer une catégorie depuisla brique catégorie, puis de l'attribuer au formulaire depuisle détail d'un formulaire.

En validant ces trois champs, le formulaire est créé.

Le formulaire nouvellement créé apparaît désormais au sein de laliste des formulaires, dans la catégorie qui lui aura été attribuée. Une fois le formulaire créé, il est alors temps de le personnaliser depuis la pagedétailde ce formulaire.

Deux autres options s'offrent à l'administrateur fonctionnel pourDématérialiser un formulaire:

* Importerun formulaire.
* Dupliquerun formulaire existant au préalable depuis laliste des formulaires.

* Studio
* Les tutos

# Préremplissage des champs

Préremplissage des champs

Préremplir un champ ordinaire

Pour éviter aux usagers d'avoir à remplir des champs dont la collectivité peut maîtriser le contenu sans leur aide, Publik permet à l'administrateur fonctionnel de préremplir un champ.

Un champ peut être prérempli de quatre manières différentes, à choisir au sein d'une liste déroulante :

* Texte/Gabarits: en préremplissant avec du « Texte », l'administrateur fonctionnel peut fixer le contenu d'un champ de formulaire sous forme de texte. Ce texte sera affiché indifféremment à tous les usagers. Il est possible d'indiquer des tags Django.Préremplir un champ à partir d'une URLIl est possible depréremplir un champ à partir d'une URL.Préremplir un champ liste issu d'une source de donnéesPour les listes issues des sources de données fiches, il faut préremplir avec l'identifiant de la fiche.
* Champ utilisateur: La collectivité dispose des informations du profil de l'usager. Si le formulaire s'adresse aux usagers connectés, l'administrateur fonctionnel peut alimenter un champ de formulaire d'une démarche avec l'une des informations stockées et accessibles depuis le profil usager. Il aura à choisir au sein d'une liste déroulante quelle information issue du profil des usagers doit préremplir le champ du formulaire.
* Géolocalisation: Lorsque l'utilisateur accepte de partager sa localisation, les coordonnées GPS de la position de l'usager en cours de saisie peuvent être extraites pour alimenter un champ. Les informations pouvant être récupérées sont :NuméroRueNuméro et rueCode postalVilleRégion

Les mêmes informations de géolocalisation peuvent être récupérées à partir d'un

[champ carte](https://doc-publik.entrouvert.com/admin-fonctionnel/fabrique-formulaires/form-champs/champ_carte/)

dans lequel le demandeur devra cliquer. Cela permet au demandeur de spécifier explicitement un endroit et de récupérer une position qui n'est pas nécessairement sa position actuelle.

Préremplir une liste à choix multiple

Si on a une liste à choix multiple contenant les éléments a, b, c, et que l'on veut avoir a et c de cochés, il faut la préremplir aveca|c

Si on a une liste à choix multiple que l'on souhaite utiliser pour préremplir une autre liste à choix multiple, il suffit d'utiliser {{ form_var_malistemultiple_raw }}.

Il est possible de verrouiller un champ uniquement quand celui-ci est prérempli.

Le préremplissage d'un bloc de champ est

[documenté sur la page dediée](https://doc-publik.entrouvert.com/admin-fonctionnel/fabrique-formulaires/bloc-de-champs/#remplir-un-bloc-de-champ)

.

* Studio
* Les tutos

# Ajouter des champs dans un formulaire

Ajouter des champs dans un formulaire

Ajout Manuel

L'ajout d'un champ au sein d'un formulaire s'effectue depuisla barre latéraledela page d'édition des champs, accessible en cliquant sur le lien « éditer » situé sur le plan de travail de la pagedétaildu formulaire en cours de fabrication.

* Saisirle libellédu champ à ajouter: Le libellé d'un champ indique aux futurs usagers destinés à remplir le formulaire ce qui leur est demandé de saisir. Il est donc décisif de rendre compréhensible à travers ce libellé, ce que la collectivité attend d'eux en termes d'informations.Le champ « Libellé » est obligatoire.Le champ « Libellé » est modifiable après création depuisla page d'édition des champsdu formulaire concerné.Choisir un libellé compréhensible : une démarche suscite d'autant plus de demandes d'usagers que le formulaire qui lui est associé est « facile » à remplir. Un formulaire qui comporte des champs dont le libellé est difficile à interpréter réduit le nombre et la qualité des demandes d'usagers transmises à la collectivité.
* Choisir letype du champà ajouter: Pour uniformiser la nature et le format des données saisies dans un champ d'un usager à un autre, Publik met à disposition une liste déroulante detypes de champs à saisir. Pour optimiser la lisibilité et l'utilisabilité d'un formulaire, plusieurstypes de champs de mise en pagesont également sélectionnables pour structurer le formulaire.Le choix dutype de champ à saisiret dutype de champ de mise en pageest irréversible, on ne peut changer le type d'un champ une fois  qu'il a été créé. Lorsqu'on s'est trompé concernant le type de champ, il faut donc créer un nouveau champ (éventuellement en copiant - collant le libellé) et supprimer l'ancien.

Quand le « Libellé » et le « Type » du champ sont « ajoutés », le champ est créé et l'on peut répéter ces opérations autant de fois que de champs sont nécessaires.

Les champs nouvellement créés apparaissent dansla page d'édition des champsdu formulaire en cours de fabrication, ainsi que dansl'aperçude ce formulaire, visualisable sur le plan de travail de la pagedétailde ce formulaire.

Import des champs d'un autre formulaire

L'importation de champs à partir d'un formulaire s'applique à tous les champs de ce dernier

Il est donc décisif de choisir un formulaire dont le contenu, constitué dechamps à saisiret dechamps de mise en page, s'apparente à celui que l'administrateur fonctionnel souhaite imiter, sous peine d'avoir une multitude d'adaptations à effectuer.

Un tour d'horizon des champs des formulaires existants au sein de laliste de formulairesou de ceux stockés ailleurs (par exemple surle catalogue des démarches) permet à l'administrateur fonctionnel d'identifier un formulaire dont les champs sont susceptibles de servir de modèles pour définir ceux d'un nouveau formulaire.

Un champ importé conserve tous lesparamètresdu champ initial et en particulier son nom de variable, si le champ original en avait un. Il faut penser, le cas échéant, à changer ce nom dans le champ créé.

L'importation des champs d'un formulaire s'effectue depuisla barre latéraledela page d'édition des champs, accessible en cliquant sur le lien « éditer » situé sur la pagedétaildu formulaire en cours de fabrication.

* Sélectionner, au sein de la liste déroulante, le formulaire depuis lequel importer les champs.
* Cliquer sur « Valider ».

Les champs importés sont désormais visibles surla page d'édition des champset sur la pagedétaildu formulaire.

* Studio
* Les tutos

# Configuration de l’option "Envoi de SMS"

Configuration de l’option "Envoi de SMS"

Pour pouvoirenvoyer un SMS dans un statut, il faut créer un connecteur et configurer les options.

Création d'un connecteur

Pour créer un connecteur, allez dans les services web ("passerelle") et cliquez sur "ajouter un connecteur". Choisissez votre fournisseur de SMS parmi ceux disponibles.

Le tutoriel qui suit se base sur le connecteur d'OVH.

Remplissez les champs du formulaire :

* Titre: indiquez le nom de votre connecteur (par ex. SMS Tatooine)
* Description: mettez un descriptif du connecteur (par ex. Compte OVH SMS Tatooine)
* Préfixe de pays par défaut: 33 pour la France
* Préfixe téléphonique local: pour convertir les numéros au format international ; laissez 0 sauf si vous savez ce que vous faites
* Taille maximale de message: tronquer les messages dépassant cette limite. Cela permet d'assurer qu'un seul envoi ne consomme pas plusieurs crédits SMS, cependant la limite à appliquer est très variable (de 70 à 160 en fonction des caractères spéciaux utilisés). De plus, un message tronqué risque d'être inintelligible pour son destinataire.
* Pays autorisés: indiquez quels préfixes sont acceptés pour l'envoi
* Autoriser les numéros surtaxés: comme son nom l'indique
* Compte: indiquez le compte OVH (par ex. sms-sl12345-1)
* Clé d’application (« application key »): indiquez la clé fournie par OVHselon cette procédure.
* Secret de l’application: indiquez le secret fourni par OVH
* Clé client (« consumer key »): laissez vide, vous aurez une alerte pour la renseigner après avoir fini la configuration.
* [OBSOLETE] Identifiant utilisateur: indiquez l'utilisateur créé dans votre interface OVH pour envoyer les SMS. N'utilisez plus cette option et laissez vide.
* [OBSOLETE] Mot de passe: indiquez le mot de passe de l'utilisateur créé dans votre interface OVH. N'utilisez plus cette option et laissez vide.
* Classe de message: choisissez une option dans la liste ; tous les opérateurs ne prennent pas en charge toutes les options"Le message est affiché directement sur l'écran des utilisateurs au moment de la réception. Le message n'est jamais enregistré, ni dans la mémoire du téléphone ni dans la carte SIM. Il est effacé dès que l'utilisateur valide l'affichage" : à préférer pour envoyer un mot de passe"Le message est enregistré dans la mémoire du téléphone ou dans la carte SIM si la mémoire est pleine""Le message est enregistré sur la carte SIM""Le message est enregistré sur un support externe, comme un PDA ou un PC"
* Niveau d'alerte du crédit d'appel: il s'agit du crédit restant en-deça duquel vous êtes prévenus. Selon la fréquence à laquelle vous envoyez des SMS, choisissez un niveau d'alerte qui vous permet d'avoir le temps de réagir
* Adresses de courriel où envoyer les alertes de crédit: indiquez ici les adresses email qui doivent recevoir l'alerte quand le niveau d'alerte configuré ci-dessus est atteint.

Une fois la configuration terminée, vous avez le message suivant :

Cliquez sur le lien. Sur la page de paramétrage d'OVH, veillez à indiquer "Validity : unlimited" (à moins que vous ne vouliez limiter volontairement dans le temps).

En revenant dans Publik, si votre crédit s'affiche à zéro, envoyez un message de test, le crédit se mettra à jour.

Configurer les options d'envoi

Pour finaliser la configuration, il faut activer la prise en charge des SMS. Cela se fait dans Hobo (Système) > SMS (nota bene : les utilisateurs hébergés sur le SaaS Entr'ouvert n'ont pas accès à cet onglet).

* URL d'envoi des SMS : mettez l’adresse indiquée dans le connecteur (faites un clic droit > "copier le lien" pour récupérer l’adresse) suffixé de /send ou un raccourci du type {{passerelle_url}}ovh/sms/send?nostop=1 (nostop=1 empêche l'envoi d'un texte du type "tapez STOP pour ne plus recevoir de SMS").
* Expéditeur : indiquez un des expéditeurs déclarés sur votre compte SMS

Une fois les paramètres enregistrés, vous pouvez faire un test d'envoi en cliquant sur "test sms" dans le connecteur dans Passerelle.

* À : renseignez votre numéro de portable
* De : indiquez un des expéditeurs déclarés sur votre compte SMS
* Message : entrez le message qui compose le SMS

Validez : si le connecteur est correctement configuré, le message arrive sur le numéro renseigné.

Remarque sur l'expéditeur personnalisé

L’opérateur NRJ Mobile ne prend pas en compte les expéditeurs personnalisés,

Les tutos

* Paiement

* Studio
* Les tutos

# Envoyer une invitation ics par courriel

Envoyer une invitation ics par courriel

Lors d’une démarche, l’usager a pris rendez-vous avec la collectivité (utilisation de l’agenda). Vous souhaitez qu’il puisse ajouter ce rendez-vous à son agenda personnel.

Pour permettre une meilleure compréhension, le formulaire et le workflow ont été simplifiés et sont incomplets : le formulaire contient les informations minimales pour fonctionner, et le workflow ne gère pas le circuit complet (annulation, déplacement de rendez-vous, etc).

On y va

* Agenda :howto_01-ics_agenda.json
* Formulaire :howto_01-ics_formulaire.wcs
* Workflow :howto_01-ics_workflow.wcs

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.

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

* 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 : fichieridentifiant : par exemple « fichierics » ({{ form_var_fichierics }})

* On génère l’ics à partir du statut « Enregistrement du rendez-vous ». Pour cela, on ajoute une action « webservice » :Nom : génération icsurl :{{reservation_response_api_ics_url}}; quelques explications :reservationest l’identifiant de l’appel webservice de l’agenda ; peut varier selon les workflowsresponseest le retour de l’appel au webservice (ce nom est statique et ne change jamais)api_ics_urlest le nom de la donnée générée par le webservice ; ce nom ne change jamaisDonné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 moinsdescriptionetlocation.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 »

* 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 ».

* Testez !Remplissez la démarche avec une adresse courriel existantele courriel reçu contient l’invitation :affichage du rendez-vous dans l’agenda :

Le titre du rendez-vous (title, ou summary) reprend par défaut la valeur du champ « label » paramétré lors de l’appel précédent au webservice (voir section suivante pour modifier cela). Le nom de la personne qui a rendez-vous (« attendee ») utilise, lui, la valeur du champ « user_name ».

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 » :

* dans le statut « Enregistrement du rendez-vous », allez dans la première action « webservice », nommée dans l’exemple « Réservation ».
* 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 »
* testez !

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

* 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. »
* testez !

<p>T&eacute;l&eacute;chargez le workflow modifi&eacute;&nbsp;: <a href="/media/uploads/2019/08/05/howto_01-ics_workflow_final.wcs">howto_01-ics_workflow_final.wcs</a></p>

Vous pouvez retrouverla documentation complète de l'agenda ici.

Les tutos

* Paiement

* Studio
* Les tutos

# Créer un référentiel avec un modèle de fiche

Créer un référentiel avec un modèle de fiche

Dans ce tutoriel nous allons voir comment créer un référentiel utilisable dans plusieurs formulaires grâce aux fiches.

Dans un formulaire donné, on souhaite permettre à l’usager de sélectionner une commune dans la liste des villes composant l’agglomération. Pour ce faire, nous allons créer un champ de type "Liste" dans le formulaire, mais plutôt que de renseigner une liste de valeurs dans le paramétrage du champ, nous allons récupérer l’information disponible dans unesource de donnéescomposée de fiches.

Le référentiel ainsi créé pourra être réutilisé dans tous les formulaires où une commune de l'agglomération devra être sélectionnée.

Si une nouvelle commune intègre l'agglomération, il suffira d'ajouter une nouvelle fiche. Nul besoin d'entrer dans les paramétrages du formulaire, tout agent disposant des droits de création des fiches pourra s'en charger.

Première étape : créer le modèle de fiches

📋Documentation spécifique

⚙️ Accès dans le BO :Studio > Modèle de fiche > action "Nouveau modèle de fiche" dans la colonne de droite.

Création du modèle

On commence par nommer le modèle (ici "Communes"), lui associer éventuellement une catégorie, et sélectionnerle workflow associé.

Champs

Ce modèle de fiche ne contiendra qu’un seul champ de type "Texte", intitulé "Nom de la commune", avec pour identifiant "nom". Il nous permettra ensuite de créer autant de fiches qu’il y a de communes dans l’agglomération.

Droits et rôles associés

Afin que les agents puissent créer les fiches, il est indispensable d’indiquer dans le paramétrage du modèle le ou les rôles disposant des droits de création. On renseignera également les rôles pouvant visualiser ou éditer les fiches.

Gabarit

Dans les options du modèle, le gabarit doit obligatoirement être renseigné. Si cette étape est omise, le modèle de fiche existera mais ne sera pas disponible en tant que source de données d’un champ de formulaire.

Seul le champ "Résumé" est indispensable pour disposer du modèle en tant que source de données. Nous allons y indiquer un champ de référence, ici notre unique champ, {{ form_var_nom }}.

Le modèle est terminé.

Deuxième étape : créer les fiches

⚙️ Accès dans le BO :via le modèle, bouton "Liste des fiches" dans la colonne de droite, ou entrée "Fiches" du menu principal puis sélectionner le modèle "Communes".

Si vous disposez des droits de création des fiches de ce modèle, vous pouvezcréer manuellement les fichesou bienles importer.

On crée donc autant de fiches qu'il y a de communes dans l'agglomération.

Troisième étape : utiliser la source de données dans le formulaire

Dans le formulaire concerné, on crée un champ de type "Liste" intitulé "Commune". Dans le paramétrage du champ, on sélectionne "Source de données" puis la source "Communes" dans la liste déroulante.

C’est terminé ! Vous pouvez maintenant visualiser le résultat en testant votre formulaire.

* Le modèle de fiche;
* les données csvà importer dans le modèle de fiche ;
* un formulaireavec un champ unique utilisant ce modèle de fiche comme référentiel.

Les tutos

* Paiement

* Studio
* Les tutos

# Configuration des droits pour l'agent d'accueil

Configuration des droits pour l'agent d'accueil

Pour que l'agent d'accueil puisse accéder à la création d'usager, il convient de créer son rôle avec des permissions particulières.

Créez un rôle « Agent d'accueil » (ou tout intitulé qui correspond à vos usages). Une fois cela fait, cliquez sur «Editer » dans la section « Contient les permissions des rôles » :

Cochez  « Afficher les rôles internes » dans la barre latérale et cochez  « Administrateur des utilisateurs » :

Ajouter cet accès aux agents leur permet d'ajouter, de modifier et de supprimer un utilisateur.

Dans le portail Agents, ajoutez un bouton d'accès pour que les agents puissent créer un utilisateur :

* Ajoutez par exemple une cellule « Lien »
* Titre : «Ajouter un utilisateur»
* URL :{{idp_url}}manage/users/add/?next={{portal_agent_url}}fiche-usager/$UUID&cancel={{portal_agent_url}}
* Enregistrez
* Ajoutez éventuellement un style css sur la cellule pour la transformer en bouton : dans les options de la cellule, dans «Classes supplémentaires pour le style par CSS :», indiquez :pk-button

Les tutos

* Paiement

* Studio
* Les tutos

# Mettre en place un champ « adresse » unique en autocomplétion

Mettre en place un champ « adresse » unique en autocomplétion

La saisie d'une adresse peut être simplifiée grâce à un champ de saisie avec autocomplétion. Les champs d'adresse sont automatiquement remplis une fois l'adresse sélectionnée dans le champ autocomplété. On utilise le connecteur de la BAN pour trouver les adresses.

Créer la source de données

Paramétrer le connecteur BAN. Créer ensuite la source de données (rubrique Studio, pavé Sources de données) :

* Indiquer le nom de la source de données
* Source de données : indiquer json et mettre l'url du connecteur de la BAN (par exemple : {{passerelle_url}}base-adresse/ban/addresses)

Le formulaire

* Créer un champ adresse de type listeavec comme classes CSS :template-address grid-1-1le champ doit être optionnelsélectionner l'affichage en autocomplétionsource de données : sélectionner la source de données créée plus hautdans l’onglet « Affichage », décocher les cases « Page de récapitulatif » et « Résumé de la demande »dans l’onglet « Avancé », configurer le préremplissage avec « géolocalisation » et « identifiant d’adresse »
* Sous le champ adresse, ajouter des champs de type texte : numéro, rue, code postal, communedans l'onglet « Avancé » configurer le préremplissage avec « géolocalisation » et le libellé correspondant au contenu de votre champpour le champ rue, décocher la case « Obligatoire »

Testez !

La classe CSStemplate-addresspermet d'afficher la case à cocher"Si l'adresse est introuvable ci-dessus, cochez cette case pour la saisir manuellement"(pour le cas où l'adresse n'est pas trouvée dans la BAN).

Lorsque vous sélectionnez une adresse parmi celles proposées, les champs numéro, rue, code postal et commune se remplissent automatiquement.

Il est possible de ne pas afficher les champs numéro, rue, code postal et commune par défaut, mais seulement quand la case "Si l'adresse est introuvable ci-dessus, cochez cette case pour la saisir manuellement" est cochée. Pour faire cela, ajoutez la classe "hide-address-parts" au champ liste en auto-complétion.

Téléchargez la source de données.

Téléchargez le formulaire fonctionnel.

Les tutos

* Paiement

* Studio
* Les tutos

# Mettre en place la création d'une demande avec préremplissage des données et des pièces justificatives

Mettre en place la création d'une demande avec préremplissage des données et des pièces justificatives

Nous allons voir comment utiliser l'action du workflowCréation d'une demande.

Tout d'abord, voyons à quoi cela peut servir. Il existe plusieurs cas d'usage, notamment concernant des demandes qui sont à renouveler régulièrement (chaque année, à chaque vacances ou à la fin d'une période déterminée), par exemple :

* Association : demande de subvention ;
* Commerce : demande d'occupation temporaire du domaine public ;
* Famille : inscription à la restauration scolaire, au centre aéré, à des activités, etc. ;
* Stationnement : achat d'un abonnement.

Objectif pour l'usager : lui rendre la démarche la plus simple et rapide à remplir.Prenons l'exemple de la demande de subvention annuelle. Il s'agit bien souvent d'une demande contenant de nombreuses informations à remplir et plusieurs pièces justificatives.Imaginez que l'usager ayant effectué une demande l'année dernière soit informé par courrier électronique de l'ouverture de la nouvelle campagne de demande de subvention. Il clique sur un lien qui le renvoie vers le nouveau formulaire dont les informations et pièces justificatives sont déjà préremplies avec les informations saisies l'année précédente et qui sont toujours valables. Il ne lui reste plus qu'à vérifier les informations, les compléter et valider sa demande.

On y va

* Formulaire :form-demande-de-subvention.wcs
* Workflow :workflow-tuto-creation-d-une-demande.wcs

Le formulaire et le workflow ont été simplifiés au maximum afin de permettre une meilleure compréhension.

Modifications à apporter au workflow

* Ajoutez un nouveau statut Renouveler votre demande, que vous placez après le statut Accepté.
* Dans le statut Renouveler votre demande, ajoutez une nouvelle action Création d'une demande, dans le menu déroulant Agir sur une demande ou une fiche.
* Cliquez sur Création d'une demande (non configurée) pour configurer l'action en question.dans l'onglet Général : cochez la case Créer en tant que brouillon ;sélectionnez Demande de subvention dans le menu déroulant Formulaire ;dans l'onglet Avancé : cliquez sur Garder l'utilisateur actuel pour Utilisateur associé à la demande ;cochez la case Conserver les infos de soumission ;indiquez renouvellement dans le champ Identifiant ;validez ;dans l'onglet Avancé : cochez la case Correspondance automatique des champs par leurs identifiants ;cliquez sur le bouton Valider.

À ce stade, nous venons de faire en sorte que toutes les données soient automatiquement préremplies.

Mais il est également possible de remettre à zéro des champs ou de les préremplir avec une autre donnée.

Remettre à zéro un champ est utile notamment quand on demande des pièces justificatives qui ne sont plus valables d'une demande à l'autre. Dans notre exemple de demande de subvention annuelle, le compte-rendu de la dernière assemblée générale doit être à nouveau renseigné par l'usager.

Préremplir avec une autre donnée est utile notamment quand on anticipe la réponse de l'usager. Dans notre exemple, il est demandé à l'usager s'il s'agit d'une première demande. De fait, la réponse sera non puisqu'il s'agit d'une ressoumission d'une demande précédente.

* Cliquez sur Création d'une demande (Demande de subvention) pour configurer l'action en question. Dans les Correspondances vers les champs de la nouvelle demande :sélectionnez le champ S'agit-il d'une première demande ? et dans le champ Expression écrivez non, en conservant le format Texte ;cliquez sur le bouton Ajouter une ligne ;sélectionnez le champ Nombre de bénévoles et laissez le champ Expression vide, cela supprimera le contenu du champ  ;cliquez sur le bouton Ajouter une ligne ;sélectionnez le champ Compte-rendu de la dernière assemblée générale et laissez le champ Expression vide, cela supprimera le fichier ;cliquez sur le bouton Valider.
* Ajoutez une nouvelle action Message dans l'historique, dans le menu déroulant Échanger.écrivez un message qui sera affiché à l'usager et ajoutez un lien vers la nouvelle demande du type :<a class="icon-management pk-button" href="">{{ form_name }} dès maintenant</a>
* Testez !

En image

Votre navigateur ne supporte pas les vidéos embarquées.

Les tutos

* Paiement

* Studio
* Les tutos

# Pré-réservation d'un rendez-vous ou d'un évènement

Pré-réservation d'un rendez-vous ou d'un évènement

Il s'agit de réserver temporairement un créneau horaire ou un évènement, laissant ainsi le temps pour l'usager (ou l'agent lors de la saisie backoffice) de compléter le formulaire sans que le rendez-vous ou l'évènement ne soit réservé par une autre personne entre temps.

Paramétrage (exemple pour les rendez-vous)

Pour permettre la pré-réservation temporaire, il faut :

* Créer unappel de webservice(dans Studio / Appels de webservices / Nouvel appel webservice) qui utilise la méthode POST (JSON) avec la même URL que le webservice de réservation  dans le workflow. Dans les « Données à envoyer dans le corps de la requête » indiquez « lock_code » comme variable avec le gabarit{% firstof form_submission_context_lock_code session_hash_id %}.Dans cet exemple, l'identifiant de l'appel webservice est « rdv_fillslot_preblocage ».

* Côté formulaire, ajouter unecondition de sortie de pagesur la page qui permet de choisir le créneau du rendez-vous (ou de l'évènement), et les suivantes.Condition : webservice.rdv_fillslot_preblocage.err == 0Message d'erreur si condition non statisfaite : Veuillez choisir un nouveau créneau, le pré-blocaque de votre réservation n'a pas pu aboutir.
* Toujours côté formulaire, dans le champ qui permet d'afficher les créneaux de l'agenda,ajouter le paramètre lock_code à la source de donnée :soit à la fin de l'URL du JSON, exemple :{{ agendas_url }}api/agenda/agenda-de-type-rdv/meetings/{{ form_var_meeting_type_raw }}/datetimes/?lock_code={% firstof form_submission_context_lock_code session_hash_id %}soit en sélectionnant directement la source de donnée de l'agenda (la donnée à envoyer en paramètres de l'URL : lock_code : {% firstof form_submission_context_lock_code session_hash_id %} étant déjà intégrée)
* Côté workflow, dans le webservice de réservation,ajouter des données à envoyer dans le corps de la requête.lock_code : {% firstof form_submission_context_lock_code session_hash_id %}confirm_after_lock : true

Explication

Le paramètre « lock_code » permet deux choses :

* de valider la disponibilité du créneau : il vérifie que le créneau est toujours accessible à chaque sortie de page ;
* de poser un verrou temporaire : le créneau sera bloqué 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.

Chaque fois que ce paramètre est appelé, le verrouillage existant est prolongé de 10 minutes. Il est donc important de maintenir la condition de sortie de page jusqu'à la fin du formulaire.Ce nouveau paramètre est également utilisable pour la réservation multiple (réservation de plusieurs places à un évènement + réservation d'une place à plusieurs évènements).

Affichage côté agenda en backoffice

Côté agenda, la pré-réservation indique comme libellé « En cours de réservation ».

Les tutos

* Paiement

* Studio
* Les tutos

# Utiliser l’autocomplétion (pour un champ liste)

Utiliser l’autocomplétion (pour un champ liste)

L'aide à la saisie (autocomplétion) permet de voir la liste des éléments sélectionnables s'affiner au fur et à mesure que l'on tape des caractères au clavier. L'aide à la saisie se base sur un référentiel de données.

Référentiel de données

Un webservice externe ou une source de données interne peuvent servir de référentiel de données :

Voir :

* Accès à des référentiels externe

<p>Nous utiliserons ici un fichier tableur comme r&eacute;f&eacute;rentiel de donn&eacute;es (au format ODS - OpenDocument Spreadsheet). Pour une description compl&egrave;te de la cr&eacute;ation du r&eacute;f&eacute;rentiel de donn&eacute;s par fichier tableur, se r&eacute;f&eacute;rer &agrave; <a href="https://doc-publik.entrouvert.com/admin-fonctionnel/parametrage-avance/source-de-donnees-csv/">ce document</a> .</p>

<p>Pour l&#39;exercice, nous utiliserons un&nbsp;fichier ods structur&eacute; comme suit&nbsp;:</p>

<table border="1">
	<tbody>
		<tr>
			<th>Identifiant</th>
			<th>Rue</th>
			<th>Code Postal</th>
			<th>Commune</th>
		</tr>
		<tr>
			<td>1</td>
			<td>Rue de Lut&egrave;ce</td>
			<td>75001</td>
			<td>Paris</td>
		</tr>
		<tr>
			<td>2</td>
			<td>Rue Nationale</td>
			<td>75013</td>
		</tr>
		<tr>
			<td>3</td>
			<td>Rue d&#39;Avron</td>
			<td>75020</td>
		</tr>
	</tbody>
</table>

<h3>Cr&eacute;ation du connecteur tableur</h3>

<p>Nous devons d&#39;abord cr&eacute;er un connecteur avec ce fichier tableur.</p>

<p>Se rendre dans le menu <em>Services web</em>, puis cliquer sur <em>Ajouter un connecteur</em> (en haut &agrave; droite). Dans la ligne <em>Sources des donn&eacute;es</em>, cliquer sur <em>Fichier tableur, </em>puis renseigner&nbsp;:</p>

<ul>
	<li><strong>Ma ville</strong>&nbsp; dans le champ <em>titre</em>.</li>
	<li><strong>id, text, code_postal, ville</strong> dans le champ <em>Noms des cl&eacute;s pour les colonnes</em></li>
	<li>cocher la case <em>Passer la premi&egrave;re ligne </em>(puisqu&#39;elle contient des titres de colonne et pas des donn&eacute;es)</li>
	<li>dans<em> fichier tableur, </em>s&eacute;lectionnez votre fichier</li>
</ul>

<p>Une fois le connecteur cr&eacute;&eacute;, vous disposez d&eacute;sormais d&#39;un webservice d&#39;acc&egrave;s aux donn&eacute;es, dont l&#39;adresse est <strong>{{passerelle_url}}csvdatasource/ma-ville/data</strong></p>

<h3>Cr&eacute;ation de la source la donn&eacute;e associ&eacute;e</h3>

<p>Dans la fabrique de formulaires utiliser le lien <em>Sources de donn&eacute;es</em> en haut &agrave; droite. Cliquez sur <em>Nouvelle source de donn&eacute;es</em>, toujours dans la colonne de droite, puis renseigner&nbsp;:</p>

<ul>
	<li>Au niveau de <em>Source de donn&eacute;es</em>, choisir le type &laquo;URL du JSON&raquo;, puis renseigner tel quel l&#39;url du point d&#39;acc&egrave;s aux donn&eacute;es&nbsp;: <strong>{{passerelle_url}}csvdatasource/ma-ville/data</strong></li>
</ul>

<p>Si le r&eacute;f&eacute;rentiel utilis&eacute; &eacute;tait un webservice externe, on renseignerait son URL dans ce champ&nbsp; <em>Source de donn&eacute;es (</em>le webservice externe serait utilis&eacute; &agrave; la place du webservice du connecteur tableur).</p>

Création du champ de formulaire

Supposons que notre formulaire appelle un champ « Adresse » associé à un référenciel nommé « Ma Ville » :

L'aide à la saisie se paramètre sur un champ de typelisteetliste à choix multiple.

Dans la fabrique de formulaire, sur le formulaire de votre choix, créer un champ de typeliste,puis renseigner:

* adressedans le champidentifiant
* autocomplétiondans le champmode d'affichage
* sélectionnerMa Villedans le champ source de données

Essayez maintenant de remplir une demande correspondant à ce formulaire, vous constaterez que l'aide à la saisie fonctionne sur le champadresse.

<p>On notera que seule l&#39;information pr&eacute;sente dans la deuxi&egrave;me colonne du r&eacute;f&eacute;rentiel de donn&eacute;es est vue par l&#39;usager lorsqu&#39;il remplit le champ <em>adresse</em>. En effet seule&nbsp;la colonne qui correspond &agrave; la cl&eacute; &laquo; text &raquo; dans notre&nbsp;connecteur est affich&eacute;e.</p>

Exploitation des données

Supposons qu'un usager ait rempli ce formulaire, et qu'il ait choisi la première l'entrée suivante dans le référentiel :

1 | Rue de Lutèce | 75001 | Paris

Voici les variables qui seront associées à cette demande :

* form_var_adressequi prendra la valeurRue de Lutèce
* form_var_adresse_rawqui prendra la valeur1
* form_var_adresse_code_postalqui prendra la valeur75001
* form_var_adresse_villequi prendra la valeurParis

Dans cette convention de nommage des variables,adressevient de l'identifiant du champ liste. Une fois qu'un champ permettant de récupérer la liste existe (le champ dont l'identifiant estform_var_adresseici), les autres colonnes peuvent donc être récupérée en ajoutant _clé_de_la_colonne, par exempleform_var_adresse_ville.

Les tutos

* Paiement

* Studio
* Les tutos

# Conditionner la durée du rendez-vous au contenu d’un autre champ

Conditionner la durée du rendez-vous au contenu d’un autre champ

Cas d’usage

Rendez-vous CNI/Passeport : Conditionner la durée du rendez-vous à la présentation du numéro de prédemande en ligne

Procédure 1

Procédure la plus simple dans le cas où les conditions sont simples.

* Créer un agenda (identifiantagenda_cni) avecntypes de rendez-vous. Ici :« J'ai rempli une pré-demande », indentifiantrdv_courtet« Je n'ai pas rempli de pré-demande », indentifiantrdv_long
* Insérer un champ Texte obligatoire intitulé « Mon numéro de pré-demande » dont l'identifiant estnum_ANTS
* Créer 2 champs Liste liés chacun à l'un de vos agenda-type-de-RDV. Conditionner ces champs à l'existence ou non denum_ANTS

Procédure 2

Procédure plus complexe, qui utilise pour lier les agendas l'URL Json dépréciée, mais qui permet de répondre à des conditions plus complexes au besoin.

* Dans le formulaire insérer un champ Liste faisant appel à une source de données.intitulé de la liste : Choisir un type de rendez-vousidentifiant de la liste : type_rdvsource de données, URL du Json : {{agendas_url}}api/agenda/agenda-cni/meetings/

-> La liste présentera les deux intitulés des types de rendez-vous créés dans l'agenda : « J'ai rempli une pré-demande », « Je n'ai pas rempli de pré-demande »

Si l'on remplit le formulaire jusque-là de nouvelles données sont à disposition, parmi lesquelles :

* form_var_type_rdv : dont la valeur sera l'intitulé du type de rendez-vous, défini dans l'agenda : « J'ai rempli une pré-demande », « Je n'ai pas rempli de pré-demande »
* form_var_type_rdv_raw : dont la valeur sera l'identifiant du type de rendez-vous, défini dans l'agenda :rdv_courtourdv_long
* form_var_type_rdv_duration :va permettre par exemple d'indiquer à l'usager la durée estimée de son rendez-vous
* Insérer un champ Texte obligatoire intitulé « Mon numéro de pré-demande » dont l'affichage est conditionnel àform_var_type_rdv == "J'ai rempli une pré-demande " ouform_var_type_rdv_raw == "rdv_court"
* Insérer un champ Commentaire avec pour contenu :La durée de votre rendez-vous est estimée à {{form_var_type_rdv_duration}} minutes
* Pour afficher les créneaux de rendez-vous, insérer un champ Liste :intitulé de la liste : Je choisis un créneau de rendez-vousidentifiant de la liste : rdv_creneaumode d'affichage : Horaireschoisir comme source de donnée URL du Json :{{agendas_url}}api/agenda/agenda-cni/meetings/{{form_var_type_rdv_raw}}/datetimes/ ou{{agendas_url}}api/agenda/agenda-cni/meetings/{% if form_var_type_rdv == "J'ai rempli une pré-demande "}rdv_court{elif form_var_type_rdv == "Je n'ai pas rempli une pré-demande "}rdv_long{endif}/datetimes/

Les tutos

* Paiement

* Studio
* Les tutos

# Mettre en place une enquête de satisfaction

Mettre en place une enquête de satisfaction

Dans ce tutoriel, vous allez apprendre à utiliser un formulaire de workflow et les données de traitement.

Sur un ou plusieurs formulaires, vous souhaitez mettre en place un questionnaire de satisfaction pour connaître l’avis des usagers ayant eu recours à cette/ces démarches et en tirer des statistiques.

Le formulaire n’ayant aucune incidence sur le traitement, n’importe quel formulaire peut être utilisé. Ici, on a retenu un formulaire de contact.

Le workflow a été simplifié afin de permettre une meilleure compréhension.

On y va

* Formulaire :howto_04-enquete_formulaire.wcs
* Workflow :howto_04-enquete_workflow.wcs

Le workflow permet d’apporter une réponse et de cloturer la demande.

* On commence par ajouter un statut « questionnaire de satisfaction », que l’on place entre les statuts « répondu » et « terminé ».
* sur le statut « questionnaire de satisfaction », ajoutez une action « formulaire »Sur le champ « A : » indiquez : « usager »indiquez un identifiant, par exemple « enquete »éditez les champs de ce formulaire :Ajoutez un premier champ « Je suis satisfait(e) de la réponse qui m'a été apportée » de type liste. En identifiant, mettez « satisfaction_niveau ». Indiquez comme éléments : Tout à fait / Plutôt oui / Pas vraiment / Pas du toutAjoutez un champ « Le délai de réponse est satisfaisant » de type liste. En identifiant, mettez « satisfaction_delai ». Indiquez comme éléments : Tout à fait / Plutôt oui / Pas vraiment / Pas du tout
* Ajoutez un saut à la soumission vers le statut « Terminé ».
* Allez sur le statut « Répondu » :supprimez le saut manuel vers « Terminé »ajoutez un saut automatique vers « Questionnaire de satisfaction »modifiez le courriel vers l’usager pour y ajouter l’invitation à répondre au questionnaire. Par exemple :« Nous aimerions connaître votre avis ! Cliquez ici pour répondre à notre questionnaire de satisfaction : {{ form_url }} ou en entrant votre code de suivi {{ form_tracking_code }} sur cette page : {{ portal_url }}. ».
* Sur le statut « Questionnaire de satisfaction », ajoutez un saut automatique vers « Terminé » avec une expiration de 10 jours. Si l’usager ne remplit pas le questionnaire, le workflow ne reste pas bloqué sur le statut et la démarche se cloture automatiquement.
* Testez !

Le questionnaire est en place, mais les réponses au questionnaire de satisfaction ne sont pas utilisées. Pour cela, il faut les mettre dans des données de traitement.

* Dans le workflow, ajoutez deux données de traitement de type liste :appelez la première « Satisfaction - niveau de satisfaction »ajoutez les éléments Tout à fait / Plutôt oui / Pas vraiment / Pas du toutmettez comme identifiant « satisfaction_niveau »appelez la seconde « Satisfaction - délai de réponse »ajoutez les éléments Tout à fait / Plutôt oui / Pas vraiment / Pas du toutmettez comme identifiant « satisfaction_delai »
* Dans le statut « Terminé », ajoutez l’action « données de traitement » :pour « Satisfaction - niveau de satisfaction », indiquez la valeur {{enquete_var_satisfaction_niveau}}pour « Satisfaction - délai de réponse », indiquez la valeur {{enquete_var_satisfaction_delai}}

{{enquete_var_satisfaction_niveau}} et {{enquete_var_satisfaction_delai}} sont les identifiants des champs du formulaire de satisfaction.

« enquete » est l’identifiant du formulaire, et «  satisfaction_niveau » et «  satisfaction_delai » sont les identifiants des champs de ce formulaire.

Testez !

Les données de traitement sont apparues dans les statistiques. Vous pouvez changer les critères par défaut pour filtrer par niveau de satisfaction.

Vous pourriez vouloir être alerté si la personne n’est pas satisfaite. Dans ce cas, on ajoute une condition sur les valeurs des réponses à l’enquête, ce qui permet de rediriger, soit vers le statut « Terminé », soit vers un nouveau statut qui envoie une alerte.

* Créez un nouveau statut « Pas content » et positionnez-le entre « Questionnaire de statisfaction » et « Terminé »
* Sur ce statut, ajoutez une action courriel :A : indiquez « destinataire »Sujet : par exemple « Un usager n'est pas satisfait »Corps : par exemple« Un usager a fait part de son insatisfaction concernant le traitement de sa demande. Vous pouvez retrouver la démarche ici : {{ form_url_backoffice }} »
* Ajoutez un saut automatique vers le statut « Terminé »
* Sur le statut « Questionnaire de statisfaction », ajoutez une condition sur le saut à la soumission vers « Terminé » : si vous souhaitez être averti si l’usager a indiqué « Pas du tout » à la question « Je suis satisfait(e) de la réponse qui m'a été apportée », mettez :enquete_var_satisfaction_niveau != "Pas du tout"
* Ajoutez un saut automatique vers le statut « Pas content » avec la condition enquete_var_satisfaction_niveau == "Pas du tout"
* Testez !

Téléchargez le workflow modifié :howto_04_enquete_workflow_final.wcs

Vous pouvez retrouver la documentation complète ici :Formulaire BO,Données de traitements,Conditions

Les tutos

* Paiement

* Studio
* Les tutos

# Paiement

Paiement

Le paiement s'appuie sur la configuration de régie de paiement, la création d'éléments de paiement par les démarches, la remontée de factures d'applications tierces et des interfaces graphiques dédiées au paiement dans le portail usager.

Préambule

Publik permet :

* Le pré-paiement : affichage d'une démarche en ligne à l'issue de laquelle l'usager réalise un paiement.
* Le post-paiement : remontée de factures d'une application métier, affichage sur le portail de l'usager des factures, paiement des factures.

Publik prend en charge la quasi-totalité des opérateurs de paiements :

* ATOS/SIPSBNP sous le nom Mercanet,Banque Populaire (avant 2010/2011) sous le nom Cyberplus,CCF sous le nom Elysnet,HSBC sous le nom Elysnet,Crédit Agricole sous le nom e-Transactions,La Banque Postale sous le nom ScelliusNet,LCL sous le nom Sherlocks,Société Générale sous le nom Sogenactif,Crédit du Nord sous le nom Webaffaires.

* Ingenico (anciennement Ogone)
* Paybox – Verifone
* SPPlus – Caisse d’Épargne avant 2012
* SystemPayBanque Populaire (depuis 2010/2011)Caisse d'Épargne (depuis 2012)CICPayZen

* PayFiP Régie Web-Service

Une régie est un compte en banque géré par un agent de la collectivité, le régisseur.

Les systèmes de paiement sont de deux types :

* TIPI (« TIPI Titres ») : nécessite que la collectivité ait préalablement relié son système comptable à HELIOS et ait converti les factures en titre trésor. Les titres sont payés par CB. Ne permet pas le pré-paiement.

* Le paiement par opérateur (Paybox, PayZen, TIPI Régie / PayFiP Régie Web-Service, etc.) : paiement par CB et encaissement sur un compte de régie ou n'importe quel compte en banque (TIPI Régie ne permet que l'encaissement sur un compte de régie).

Ces deux types de systèmes n'ont pas la même couverture fonctionnelle : impossible de payer une facture trésor public (un titre) avec un opérateur (tel que PayFiP Régie Web-Service, paybox, payzen) et impossible d'encaisser sur un compte de régie avec TIPI (Titres).

Pour le paiement par opérateur, nous recommandons un autre système que Tipi Régie même si le service est gratuit - donc plutôt un service payant comme PayZen, Paybox, etc. - car avec TIPI Régie :

* Il n'y a pas d'authentification des requêtes de paiement donc un usager pourrait payer un montant non contrôlé (il suffit que l'usager modifie l'URL de redirection), avec Payzen, Paybox, etc., les URLs sont signées.
* Il n'y a pas de backoffice, il est donc très difficile de rapprocher de dettes et les paiements (difficile de renseigner un usager sur un paiement effectif ou pas, par exemple).
* Il n'y a pas vraiment de support.
* Il y a de plus un risque de délit de concussion puisqu'un internaute pourrait payer n'importe quel montant pour n'importe quoi, sans pouvoir relier cela à une dette particulière.

Les plateformes de paiement et les régies

Les plateformes de paiement font l'objet d’une configuration technique qui permet le raccordement à un sytème de paiement (Paybox, Payzen, etc).

Les régies sont liées à une plateforme de paiement. On peut y affiner les caractéristiques des paiements qui seront pris en charge par la plateforme de paiement (montant minimum, mode de validation). On peut également y déclarer l’url d'un web service de remontée de facture, un texte affiché à l'usager de retour sur le portail après un paiement si cela s'avère nécessaire.

Afin de réaliser la conception d'une démarche donnant lieu à un paiement, une plateforme de paiement et une régie factice peuvent être utilisés.

Paramétrage d'une plateforme de paiement et d'une régie « Factice »

Rendez-vous dans le back-office dans l'onglet d'édition du portail citoyen (CMS).Cliquez en haut à droite sur l'icône de menuSélectionnez « paiement en ligne ».Sur la page suivante cliquez sur le bouton  « Plateformes de paiement ».

Vous avez maintenant la possibilité de créer une nouvelle plateforme de paiement. Si aucune n'existe déjà, cliquez en haut à droite sur « nouvelle ».

Saisissez ensuite un libellé et un identifiant (l’identifiant est destiné à la création des urls, il ne doit contenir ni caractères accentués, ni espaces, ni caractères spéciaux autres que « _ » ou « - »). Pour cet exemple l'identifiant de la régie sera « plateforme-factice ». Pour le service de paiement choisissez « Factice ».

Validez, la plateforme de paiement est créée. La page qui s'affiche ensuite permet son paramétrage : dans le cas d'une plateforme reliée à un système de paiement, c'est ici que seront entrées les informations d'authentification requises. Pour cette plateforme factice, les champs nécessaires sont déjà préremplis, il n'y a donc rien de particulier à faire.

Retournez sur la page « paiement en ligne » et cliquez sur le bouton  « Régies ».

Vous avez maintenant la possibilité de créer une nouvelle régie. Si aucune régie factice n’existe déjà, cliquez en haut à droite sur « nouvelle ».

Saisissez ensuite un libellé de régie et un identifiant, pour cette exemple l’identifiant de la régie sera « regie-factice ».

Saisissez  une description pour la régie (ce texte vous permet plus tard de vous souvenir l'objectif de chaque régie mise en place).Pour la plateforme de paiement, choisissez la plateforme de paiement factice que vous avez créée à l'étape précédente.

Nous n’avons pas besoin de fournir un webservice de récupération de factures dans notre exemple.Le montant minimum est laissé à 0.

Saisissez un texte à afficher à l’usager lors du retour, suite à la validation du paiement.

Validez : la régie est maintenant créée.

Le paiement en frontoffice

Le panier est l'élément principal du frontoffice. Il présente les éléments à payer créés lors des démarches. Les transactions passées présentent à l'usager l’historique des paiements.

Le bloc « factures actives » présente à l'usager les factures remontées des applications tierces à payer. L’historique des factures présente à l'usager l’historique des paiements de factures.

Ces éléments sont des cellules du CMS.

Dans la partieÉdition des portails, choisissez la page sur laquelle vous souhaitez exposer ces blocs. Dans la zone choisie, ajoutez une nouvelle cellule du type souhaité.

Vous pouvez en régler la visibilité suivant le besoin. Tant qu'aucun élément n'y est présent ces blocs ne sont pas visibles par l'usager.

Il est également possible de ne pas passer par un panier pour un paiement. Cela se paramètre dans le workflow.

Ajouter la gestion du paiement à une démarche

Les étapes de paiement dans le workflow.

Pour plus de détails sur le paramétrage de cette API de paiement, il existe une page dédiée «

[API Combo](https://doc-publik.entrouvert.com/dev/api-combo/)

».

Création du paiement

Créez un nouveau workflow paiement.Le moment de la création du panier de l'usager dépend de vos règles de gestion, le plus simple pour l'usager est de pouvoir payer instantanément après validation du formulaire et donc le panier doit être créé dès cet instant ; dans d'autres cas une intervention par un agent sera nécessaire avant de lui permettre de payer (pour des tarifs liés à des quotients par exemple), l'affichage dans le panier sera alors différé.

Ici nous déclenchons la création des éléments de panier à la soumission du formulaire, nous créons donc le panier dans le premier statut du workflow.

Créez un statut « création du panier » et un statut « En attente de paiement ».

Conseil

Pour optimiser l'utilisation de votre workflow et le relier éventuellement à plusieurs formulaires de paiements différents, il est conseillé de créer des variables de workflows afin de rendre votre paramétrage le plus flexible possible.

Par exemple, une variable « Régie » vous permettra de définir une régie différente suivant le formulaire en utilisant un seul workflow ; une variable tarif unitaire, vous permettra de définir un tarif au niveau du formulaire...

# Paiement

Dans le statut « création du panier » ajoutez une action de type « Webservice ». C'est lui qui nous permet de communiquer avec le module de paiement et donc de créer un panier.Donnez lui un libellé (facultatif) et founissez lui l'url d'appel :

{{portal_url}}api/lingo/add-basket-item?NameId={{form_user_name_identifier_0}}&regie_id={{form_option_regie}}

ici {{form_option_regie}} correspond à une variable de workflow ; si vous préférez, vous pouvez saisir ici directement l'identifiant de la régie (dans notre cas « regie-factice »).

Assurez-vous que l'option "Envoyer les données du formulaire" est bien décochée (c'est le cas par défaut).

Attention, dans le cas de paiement autorisé sans que l'usager soit connecté, il faut prévoir de ne passer que la régie dans l'url d'appel :

{{portal_url}}api/lingo/add-basket-item?regie_id={{form_option_regie}}mais parmi les « données à envoyer dans le corps de la requête » (cf. infra), il faut ajouter la donnéeemailavec la valeur adéquate ({{form_var_courriel}}ou autre, suivant votre formulaire).

Dans la zone « envoyer les données » vous devez préciser le montant du panier qui va être créé ainsi que le libellé de la transaction et l'url du formulaire. Ces valeurs sont envoyées respectivement dans via les noms de données :

* amount
* display_name, qui sera typiquement{{form_display_name}}
* url, qui sera typiquement{{form_url}}

Le montant peut être un montant fixe lié à un tarif défini dans le formulaire, il peut également être calculé préalablement dansune donnée de traitement.

Montant fixe :

Montant fixe issu d'une variable de workflow :

Montant calculé à partir d'une ou plusieurs variables (par exemple achats de plusieurs activités) :

Choisissez ensuite un identifiant pour cet appel webservice, dont découleront les variables de l'appel. Une de ces variables est importante car elle nous permettra ensuite l'annulation du panier, si besoin.

Nous ne détaillons pas ici toutes les options de l'appel webservice (vous pouvez gérer les erreurs comme vous le souhaitez et les afficher si besoin). Pour plus d'information voir l'actionWebservice.

À la suite de cette action d'appel webservice, ajoutez une action de changement de statut automatique qui pointe vers le statut en attente de paiement.

Dans le statut en attente de paiement créez une action « afficher un message » dans lequel vous pouvez expliquer à l'usager qu'il doit régler sa commande pour la valider définitivement et lui afficher un lien vers le panier (page du CMS qui contient le panier).

Dans un mode sans panier, vous pouvez envoyer l'usager directement sur l'url de paiement, après l'appel au webservice, qui renvoie cette url sous la forme {{form_workflow_data_IDENTIFIANT_WEBSERVICE_response_payment_url }} (remplacezIDENTIFIANT_WEBSERVICEpar l'identifiant que vous avez mis pour votre webservice, ex. panier). Utilisez cette url avec l'action redirection ou dans un courriel.

Validation du paiement

Habituellement l'usager doit payer sa commande pour finaliser la procédure d'achat, il faut donc pouvoir faire avancer la demande dans le workflow en parallèle de la réception du paiement.

Commencez par créer un statut « paiement reçu ».

Nous allons maintenant placer dans le statut « en attente de paiement » un changement de statut automatique basé sur un déclencheur.

Dans le statut « en attente de paiement », ajoutez une action « changer de statut automatiquement ». Cette action pointe vers le statut paiement reçu et possède dans le champ déclencheur « Identifiant d’appel webservice » la valeur suivante :paid

Lorsque l'élément du panier correspondant sera payé, la demande liée basculera automatiquement dans le statut « paiement reçu ».

Annulation du paiement / de la commande depuis une action de workflow

Créez un statut « Annulation du panier ». Dans le statut en attente de paiement créez une action de changement de statut manuel intitulée « Annuler ma commande » qui sera affichée à l'usager et lui permettra de basculer vers le statut « Annulation du panier ».

Dans le statut Annulation du panier, déclarez une action « Webservice ».

L'url d'annulation d'un panier est la suivante :

{{portal_url}}api/lingo/remove-basket-item?NameId={{form_user_name_identifier_0}}

Il faut ensuite décocher la case « Envoyer les données du formulaire ».

Et renseigner manuellement l'envoi des données :

La variable {{paiement_response_id}} correspond à l'identifiant de création du panier renvoyé lors de l'appel webservice de création dans le statut correspondant. La racine « paiement » variera donc en fonction du nommage que vous aurez choisi.

Suite à l'annulation, il est possible de prévoir l'affichage d'un message à l'usager via l'action «Alerte».

Attention : l'annulation d'un objet du panier n'est pas possible, actuellement, dans le cas d'un usager non connecté.

Annulation du paiement depuis le panier

Lors de la création d'un élément dans le panier, l'usager à la possibilité de supprimer celui-ci depuis le panier, il faut donc pouvoir annuler en parallèle la demande correspondante.Nous allons donc placer dans le statut « en attente de paiement » un changement de statut automatique basé sur un déclencheur.

Dans le statut « en attente de paiement », ajoutez une action « changer de statut automatiquement ». Cette action pointe vers le statut annulation du panier et possède dans le champ déclencheur la valeur suivante : cancelled

Annuler un paiement à l'issue d'un délai

Vous pouvez également annuler un paiement à l'issue d'un délai d'inaction de l'usager (s'il n'a pas validé son panier au bout de 24 heures par exemple).

Pour cela, placez dans le statut en attente de paiement une action de changement de statut automatique vers le statut « annulation du panier » en donnant un délai d'expiration, par exemple « 24 heures ».

À l'issue de ce délai, la demande sera annulée et la commande supprimée du panier.

Télécharger les exemples

sur le cataloguePublik.love

* formulaires
* workflows

Les tutos

* Paiement

* Studio
* Les tutos

# Personnaliser son compte

Personnaliser son compte

La gestion du profil d'utilisateur s'effectue depuis l'onglet « Profil » du portail citoyen, généralement situé dans le coin supérieur droit de la page d'accueil.

La page « Profil » est composée des trois blocs suivants :

* ProfilCe bloc délivre une vue des informations du profil saisies au cours de l'étape «S'inscrire».
* Moyens d'authentificationCe bloc permet de « Modifier votre mot de passe ».
* Gestion de votre compteCe bloc permet de:Modifierl'adresse courriel associéeÉditer son profilCe lien donne accès à un formulaire qui permet de renseigner des informations facultatives (adresse, code postal, téléphone, etc).Supprimer son profilCe lien permet deSe désinscrire.

# Connexion

Connexion

Se connecter

Connexion par login et mot de passe

La connexion au compte s'effectue depuis la page d'accueil du portail citoyen.

* Cliquer sur « Connexion » dans le coin supérieur droit de la page d'accueil.
* Entrer le courriel associé au compte auquel vous tentez de vous connecter.
* Entrer le mot de passe saisi au moment de l'étapeS'inscrire.En cas deMot de passe perdu, un lien permet de ré-initialiser celui-ci.
* Cliquer sur « Connexion »

Votre identifiant est désormais visible dans le coin droit du portail citoyen.

Connexion avec FranceConnect

Les déploiements de Publik à partir de 2017 sont presque toujours raccordés à FranceConnect. Les usagers peuvent donc utiliser leur identité FranceConnect pour se connecter et bénéficier ainsi d'une identité certifiée. On pourra choisir de réserver certaines démarches à cette identité certifiée.

Connexion avec une carte d'identité belge

Les déploiements de Publik en Belgique utilisent souvent le service fédéral permettant de s'authentifier avec une carte d'identité électronique. On pourra choisir de réserver certaines démarches à cette identité certifiée.

Se déconnecter

La déconnexion du compte s'effectue depuis la page d'accueil du portail citoyen ou du portail agent.

Il suffit de cliquer sur « Déconnexion » dans le coin supérieur droit de votre interface (sur le portail citoyen ou sur le portail agent).

# Portail agent

Portail agent

Le  « Portail agent » est la page d'accueil du back-office, il est accessible à tout compte ayant un rôle « agent ».

Le portail est adaptatif. Autrement dit, l'environnement de travail desagents connectéssur le Portail, diffère selon leurs missions respectives. En effet, différentes briques et modules logiciels composent Publik pour répondre à des besoins fonctionnels spécifiques : dématérialiser une démarche, traiter une demande d'usager, personnaliser les droits d'accès des utilisateurs, modifier l'apparence du portail citoyen, entre autres exemples.

Plusieurs profils d'utilisateurs « Agent » sont donc ainsi définis en fonction de leurs missions, profils qui conditionnent, sous forme de permissions, l'accès aux briques logicielles du portail agent.

La partie principale de la page d'accueil présente, au moyen d'icônes, l'ensemble des modules auquel l'agent a accès, en fonction des droits (rôles spếcifiques) qui lui sont alloués. Le contenu de cette page étant personnalisable par l'administrateur technique, il peut être très différent d'une collectivité à l'autre.

La marge droite est souvent utilisée pour présenter des liens vers des fonctionnalités spécifiques à la collectivité.

Pour en savoir plus sur la mise en place d'un portail Agents, consulter la page

[https://doc-publik.entrouvert.com/admin-fonctionnel/modifier-le-contenu-des-portails/mettre-en-place-portail-agents/](https://doc-publik.entrouvert.com/admin-fonctionnel/modifier-le-contenu-des-portails/mettre-en-place-portail-agents/)

Les différents profils

Il y a différents profils qui accèdent au portail agent :

Les agents d'accueil: accueillent le public au guichet ou au téléphone, saisissent des demandes pour le compte des usagers.

Les agents traitants:  traitent les demandes soumises sur la plate-forme par les citoyens.

Les administrateurs fonctionnels: fabriquent les démarches en lignes (formulaires et workflows), attribuent des droits (rôles) aux utilisateurs, gèrent les contenus des portails, génèrent des rapports statistiques.

Les administrateurs techniques: gèrent l'ensemble des paramètres techniques de la plate-forme et la connexion aux applications tierces.

# S’inscrire

S’inscrire

L'inscription s'effectue depuis la page d'accueil du portail citoyen.

* Cliquer sur « Inscription », généralement situé dans le coin supérieur droit de la page d'accueil.
* Saisir votre adresse courrielCette adresse courriel est requise au moment deSe connecter.Si vous êtes susceptible de vous inscrire à double titre sur le portail citoyen - en tant qu'usager et en tant qu'agent de collectivité -préférez le recours à deux adresses courriels différentespour créer deux comptes distincts: un compte professionnel et un compte usager.
* Si le courriel est accepté, le message suivant s'affiche :« Vous êtes maintenant enregistré. Un courriel d'activation vient de vous être envoyé. ».Si un message d'erreur s'affiche,vérifiez que l'adresse courriel saisie soit correcte. Si le problème persiste, contactez l'administrateur technique de Publik.
* Ouvrez le mail d'activation depuis la boîte mail associée au courriel saisi et cliquez sur le lien d'activation.
* Ce lien vous redirige vers le portail citoyen.Attention, le lien d'activation n'est valide que deux jours.
* Terminer l'inscription en saisissant les informations obligatoires suivantes :PrénomNomMot de passe: ce mot de passe est requis au moment deSe connecter.Le mot de passe doit être tenu secret pour éviter qu'un tiers non autorisé accède au compte.Qu'il s'agisse d'un compte usager ou d'un compte agent, les données accessibles depuis ce compte doivent impérativement demeurer confidentielles, conformément au respect de la vie privé et auRéférentiel Général de Sécurité (RGS).Pour sécuriser un mot de passe, Publik contraint les usagers et les utilisateurs à choisir un mot de passe composé d'au moins 3 types de caractères parmi les caractères suivants: minuscules, majuscules, chiffres et signes de ponctuation.Confirmation du mot de passePour garantir aux usagers et aux utilisateurs la validité de leur mot de passe, ce dernier doit être saisi une deuxième fois.Cliquer sur « Valider ».

L'inscription est achevée.

Un lien « Gestion de votre compte » suggère deGérer son profil d'utilisateur

# Éléments de base de l'interface

Éléments de base de l'interface

Le menu principal

Situé à gauche des écrans, le menu de Publik permet d'accéder auxbriques logiciellesde Publik, listées verticalement, en fonction des droits d'accès de l'utilisateur connecté.

Le menu principal se rétracte ou se développe, lorsque l'utilisateur clique sur le titre du menu. De cette manière, l'utilisateur peut optimiser l'espace alloué auplan de travailou disposer d'un accès auxbriques logiciellesduportail agent.

Le fil d'Ariane

Situé, horizontalement, en en-tête de chaqueplan de travail, le fil d'Ariane indique l'emplacement de l'utilisateur, en cours de navigation, au sein du portail agent.

L'emplacement est indiqué sous forme de liens vers les pages hiérarchiques parentes de la page où se trouve l'utilisateur.

Il lui est alors possible de se positionner au sein de la hiérachie des pages de Publik; et de cheminer « en arrière » en cliquant sur l'un des liens affichés dans le fil d'Ariane.

Le plan de travail

Situé dans la zone centrale de vos écrans, le plan de travail constitue l'espace à partir duquelles agents de Publikpeuvent assurer leurs missions.

Une poignée d'expansion, en haut à droite du plan de travail, est activable sur certains écrans pour étendre le plan de travail (au détriment de l'espace alloué à la barre latérale).

La barre latérale

La barre latérale est située tout à fait à droite des écrans du portail agent.

Elle affiche les fonctionnalités d'une page relative à une brique logicielle de Publik.

La barre « Utilisateurs »

La barre « utilisateurs » est située en haut à droite des écrans du portail agent.

Elle permet de :

* Gérer son profil d'utilisateur
* Se déconnecter
* Se désinscrire

# Portail citoyen: un guichet virtuel, multi-canal et personnalisé, dédié aux téléservices

Portail citoyen: un guichet virtuel, multi-canal et personnalisé, dédié aux téléservices

Le portail citoyen met à disposition des usagers les formulaires des démarches dématérialisées par leur collectivité.

Les démarches sont accessibles directement depuis le site web de la collectivité, avec un minimum de différence graphique: l'usager passe ainsi de façon transparente du site de la collectivité au portail citoyen et réciproquement.

Lorsqu'un usager de collectivité sollicite une de ces démarches, un formulaire permet de formaliser sa demande et de la transmettre à unAgentchargé de la traiter.

La saisie du formulaire depuis le portail citoyen de Publik peut l'être par l'usager lui-même ou, quand la demande est transmise à la collectivité par un autre canal (téléphone, courriel, courrier, guichet physique, etc), par unagent d'accueilde la collectivité.

Le portail citoyen permet non seulement aux usagers de déposer une demande de téléservice, mais aussi, de sauvegarder l'historique des démarches effectuées, clôturées ou en cours ; ou encore de stocker et d'échanger avec la collectivité, d'éventuels documents, compléments d'information, ou messages.

Un guichet virtuel dédié aux téléservices

Soumettre une demande de téléservice

Chaque démarche dématérialisée d'une collectivité se traduitpar la mise à disposition (à l'usager et/ou à unagent d'accueil)d'un formulaire dédié.

L'administrateur fonctionnelde la collectivité, en charge de la gestion des démarches dématérialisées de sa collectivité, peut restreindre l'accès de ces démarches à certains usagers (et donc la possibilité pour eux de remplir un formulaire), en fonction de critères de son choix (lieu de résidence, âge, etc).

S'ils y ont accès, les usagers peuvent ainsi remplir en ligne, depuis le portail citoyen, n'importe quel formulaire de démarches, 24h/24 et 7J/7, et ce, quel que soit leur moyen d'accès à Internet (mobile ou non).

Ils peuvent le faire en plusieurs temps :toute demande entamée est systématiquement enregistrée.Les formulaires partiellement complétés sont visibles de l'usager dans la partie « Brouillons en cours » de son compte pendant 100 jours avant d'être effacés, un brouillon peut également être accessible via un code de suivi, si cette option a été activée pour le formulaire concerné.

Le formulaire à saisir peut être prérempli avec les informations disponibles sur le profil du compte de l'usager, à condition que celui-ci soit connecté.

Connaître l'état d'avancement d'une demande de téléservice en cours

Quand une demande d'usager est complétée, elle est associée à un ticket de suivi (une référence) communiquée à l'usager pour lui permettrede solliciter la collectivitéau sujet de l'état d'avancement du traitement de sa demande.

Lorsque l'administrateur fonctionnelle permet, l'usager peut lui-même consulter la progression de sa demande depuis le portail citoyen, grâce à la publication de notifications quant au statut de sa demande.

Prendre part à la progression d'une demande de téléservice en cours

Les interactions entre l'agent traitant en charge de cette demande et l'usager sont totalement paramétrables dans le workflow. Des interactions sous forme de questions/réponse, dépôt de fichiers, mise à disposition de documents... sont possibles, si tant est que l'administrateur fonctionnel, au moment de la conception de la démarche, les a paramétrées.

Exemples :

* Si un document manque pour valider la recevabilité d'une demande d'usager à traiter, ou si une donnée saisie par l'usager nécessite une clarification, le portail citoyen permet à l'usager de recevoir un commentaire de l'agent traitant le lui signalant.
* À l'inverse, un usager peut lui aussi prendre contact avec sa collectivité depuis le portail citoyen pour poser une question au sujet de sa demande en cours, ou encore pour indiquer qu'une donnée saisie dans son formulaire doit être modifiée (suite à un changement d'adresse par exemple ou d'état civil).

Échanger et archiver des documents administratifs

Publik intègre un porte-documents, garant de la sécurité et du respect de la vie privée des usagers, pour stocker et échanger, à tout moment, des fichiers entre les usagers et leur collectivité.

Une plateforme mobile et multi-canal

Publik est conçu pour démultiplier les canaux de transmission potentiels d'une demande de téléservice de la part d'un usager vis-à-vis de sa collectivité.

L'usager dispose en effet d'un nombre important de vecteurs de communication avec sa collectivité (site web, guichet physique, courriel, fax, courrier papier, etc) que Publik permet de gérer, en centralisant, au niveau duPortail agent, sous forme numérique, toutes les demandes d'usagers, y compris celles qui n'ont pas été introduites depuis le portail citoyen.

Une connexion automatique avec la centrale téléphonique et une application de dématérialisation du courrier permettent notamment auxagents d'accueild'une collectivité de dématérialiser les demandes d'usagers qui ne sont pas effectuées depuis le portail citoyen. Le portail citoyen étant nativement responsive design et pouvant se comporter, potentiellement, en tant que progressive web app, l'usage en mobilité (smartphones, tablettes) et possible.

Un espace « citoyen-usager » personnalisé et sécurisé

Un compte personnel est attribué à chaque usager du portail citoyen. Il est composé d'un identifiant et d'un mot de passe. Une fois connecté, l'usager a accès à un espace personnalisé, seules les démarches qu'il peut solliciter sont affichées.

S'il saisit dans son profil utilisateur ses informations personnelles, celles-ci seront automatiquement préremplies lorsqu'il effectuera une démarche en ligne qui ne requiert pas l'anonymat.

Depuis son espace personnel, le citoyen-usager peut suivre la progression du traitement de ses demandes en cours, les compléter si besoin, accéder à l'historique de ses démarches, consulter et archiver des documents.

Le portail citoyen permet également aux usagers d'une collectivité de voir remonter l'information depuis des services tiers qui auraient été connectés à Publik : factures émanant du portail Famille, informations sur les emprunts en cours auprès de la médiathèque... Pour ce faire, Publik a recours à la fédération d'identités (SSO - Sigle-Sign-On) pour connecter entre eux, en toute sécurité et dans le respect de la vie privée, les différents comptes de l'usager.

# Mot de passe perdu

Mot de passe perdu

La perte du mot de passe d'un compte est gérable depuis le lienSe connectersitué dans le coin supérieur droit du portail citoyen.

* Cliquer sur « Ré-initialisez le !» (mot de passe)
* Saisir le courriel du compte pour lequel un nouveau mot de passe est nécessaire.
* Cliquer sur « Valider ».Un courriel d'activation est envoyé à l'adresse courriel indiquée
* Ouvrir le mail de ré-initialisation du mot de passe depuis la boîte mail associée au courriel saisi. Cliquer sur le lien de ré-initialisation.
* Ce lien vous redirige vers le portail citoyen.
* Terminer la ré-initialisation du mot de passe en saisissant les informations suivantes :Pour sécuriser un mot de passe, Publik contraint les usagers et les utilisateurs à choisir un mot de passe composé d'au moins 3 types de caractères parmi les caractères suivants : minuscules, majuscules, chiffres et signes de ponctuation.Nouveau mot de passeConfirmation du nouveau mot de passeLe mot de passe doit être tenu secret pour éviter qu'un tiers non autorisé accède au compte.Qu'il s'agisse d'un compte usager ou d'un compte agent, les données accessibles depuis ce compte doivent impérativement demeurer confidentielles, conformément au respect de la vie privé et auRéférentiel Général de Sécurité (RGS).

# Se désinscrire

Se désinscrire

La désinscription se fait depuis l'onglet « Profil » du portail citoyen.

La procédure de désinscription est très facile, et à la fois ... lourde de conséquences.En effet, l'action de suppression d'un compte est irréversible. L'usager ne pourra plus accéder à son compte après sa suppression.C'est pourquoi, il est important de s'assurer que les données du compte, potentiellement utiles à l'avenir, ont été récupérées.

En cas de suppression regrettable d'un compte,S'inscrirene permettra pas de récupérer les données du compte supprimé.

* Sur la page « Profil » du portail citoyen, cliquer sur « Supprimer votre profil ».
* Dites « oui » ou « non » pour répondre à la question « Supprimer votre compte et toutes vos données personnelles ? ».

# Avoir un compte

Avoir un compte

Pour les citoyens, avoir un compte n'est pas une obligation, on peut accéder auportail citoyensans se connecter. Pour les agents par contre, un compte (identifiant / mot de passe) est nécessaire pour pouvoir accéder auportail agent.

(Dés)Inscription

Un compte peut-être créé ou supprimé, découvrez comment.

[S'inscrire](https://doc-publik.entrouvert.com/tour-dhorizon/avoir-un-compte/inscription/)

[Se désinscrire](https://doc-publik.entrouvert.com/tour-dhorizon/avoir-un-compte/desinscription/)

Connexion

Une fois le compte créé, vous pouvez l'utiliser pour vous connecter/déconnecter. Et aussi récupérer un mot de passe perdu.

[Se connecter / déconnecter](https://doc-publik.entrouvert.com/tour-dhorizon/avoir-un-compte/connexion/)

[Mot de passe perdu](https://doc-publik.entrouvert.com/tour-dhorizon/avoir-un-compte/mot-de-passe-perdu/)

Personnaliser un compte

Votre compte comporte un certain nombre d'informations vous concernant, c'est le profil utilisateur. Apprenez à le personnaliser.

[Gérer son profil d'utilisateur](https://doc-publik.entrouvert.com/tour-dhorizon/avoir-un-compte/gestion-profil/)

Paramétrer les droits (rôles) d'un compte utilisateurest du ressort de l'Administrateur technique.

Si un utilisateur de Publik est à la fois citoyen et  agent, il est préférable que celui-ci dispose de deux comptes distincts, c'est-à-dire, d'un compte personnel et d'un compte professionnel.

# Afficher l'information (via les fiches)

Afficher l'information (via les fiches)

Faire une source de données

Lorsque l'on acréé un modèle de ficheet saisi des données dedans, il est fréquent de vouloir en faire une source de données pour pouvoir utiliser le contenu des fiches dans les démarches ou dans d'autres fiches.

Les «Sources de données» sont utilisées dans Publik pour alimenter des champs de type texte ou liste (une option de ces champs permet de sélectionner la source de données voulue) qui vont afficher les informations qu'elles contiennent, éventuellement en les filtrant. Une source de données ordinaire se construit manuellement dans un espace dédié en remplissant plusieurs paramètres.

Avec les fiches, cela n'est plus nécessaire, c'est automatisé : il suffit de renseigner l'option « Gabarit du résumé »dans le modèle de fiche concerné pour que  ce modèle devienne automatiquement une source de données qui contiendra ce que l'on aura mis dans le gabarit du résumé  (le gabarit peut concaténer plusieurs champs).

Avec, par exemple, un modèle de fiche « Établissements scolaires » ayant un champ dont le nom de variable est form_var_nom, le fait d'indiquer {{form_var_nom}} dans le gabarit du résumé suffit à créer automatiquement une source de données contenant le nom de tous les établissements scolaires enregistrés dans les fiches. La source de données est immédiatement disponible, elle apparaît dans la liste des sources de données.

Pour les champs listes dont la source est un modèle de fiche, vous noterez la présence d'un bouton '+' à côté de la liste qui permet d'ajouter une nouvelle fiche sans avoir à quitter le formulaire ou la fiche en cours de saisie. La nouvelle fiche enregistrée viendra remplir automatiquement le champ de la fiche ou du formulaire que l'on est en train de compléter.

Filtrer les fiches

Vues personnalisées

Lesvues personnaliséespermettent d'afficher et d'enregistrer dans les interfaces de traitement (des fiches ou des démarches) des vues, sur mesure, adaptées aux besoins des gestionnaires.

Mais lorsque l'on enregistre une vue personnalisée, on peut également choisir d'en faire une source de données en sélectionnant «comme source de données». La source de données est alors immédiatement disponible après enregistrement de la vue personnalisée.

Cela va permettre d'ajouter à vos sources de données des notions de :

* Classement : en cliquant sur le titre des colonnes du tableau de traitement vous changez le classement de votre vue personnalisée et donc de votre source de données.
* Tri : en cliquant sur  « critères » vous allez pouvoir ajouter des critères de tri et les paramétrer.

Vues personnalisées dynamiques

Pour aller encore plus loin et filtrer l'affichage des fiches en fonction d'un critère provenant du formulaire, il faut utiliser les vues personnalisées dynamiques.

Imaginons une fiche « Marchés » et un formulaire me permettant de choisir un jour de la semaine. Le formulaire devra afficher les marchés qui ont cours pour un jour donné, celui sélectionné par l'usager. Pour cela, nous allons construire une vue personnalisée avec un critère « jour » dans laquelle nous indiquerons le nom de variable utilisé dans le formulaire (par exemple {{ form_var_jour_raw }}). Il suffira ensuite que le champ liste affichant les marchés ait comme source de données notre vue personnalisée dynamique pour que l'ensemble fonctionne.

Explication en images

Il est également possible d'afficher un champ de type liste à choix multiple sourcé sur un premier champ à choix multiple.La valeur personnalisée aura pour syntaxe : {{ form_var_IDENTIFIANT_raw|join:"|" }} à utiliser avec le critère « dans ».

Afficher dans un formulaire les champs d'une fiche qui ne sont pas dans le gabarit du résumé

Via les sources de données issues des fiches, on dispose des informations contenues dans le gabarit du résumé. Mais on souhaite parfois récupérer dans un formulaire une information qui n'est pas présente dans le gabarit du résumé, et qui existe dans un autre champ de la fiche. C'est possible de deux façons différentes :

* Grâce à la présence dans le formulaire d'un champ alimenté par une source de données issue d'un modèle de fiche. Ce champ va permettre de lier une fiche à la demande.
* Grâce auxfiltres de requêtesqui vont permettre d'aller interroger n'importe quel modèle de fiche.

Champ faisant le lien entre fiche et formulaire

Lorsqu'un champ du formulaire a pour source de données un modèle de fiche (ou une vue personnalisée sur un modèle de fiche), on va pouvoir utiliser son nom de variable et le suffixer avec le mot-clé «_structured_» suivi de l'identifiant du champ de la fiche pour récupérer la valeur souhaitée.

Par exemple, un champ listeform_var_ecolealimenté pour un modèle de ficheecole, permettra à l'usager de choisir le nom d'une école particulière. Le modèle de ficheecolepossède un champform_var_adresseque je souhaite afficher dans le formulaire. Cette adresse sera disponible dans mon formulaire grâce à la variable form_var_ecole_structured_adresse.

À noter que cela fonctionnera avec des champs texte ou liste mais pas avec des listes à choix multiple, des fichiers et des cases à cocher. Pour ces champs, il est possible d'utiliser une variable du type form_var_ecole_live_var_adresse.

L’utilisation de la forme_live_a également comme caractéristique de récupérer la valeur de la fiche au moment de l’accès, alors que la forme_structured_récupère la valeur telle qu’elle était à l’enregistrement de la demande.

Filtres de requêtes

Pour récupérer une information contenue dans une fiche qui n'est pas liée au formulaire, il faut utiliser les filtres de requête. Ces derniers offrent un mode d'interrogation des fiches un peu comparable à un version très simplifiée du langage SQL. Typiquement pour aller chercher dans un modèle de fiche donné une information particulière on utilisera la syntaxe suivante :

cards|objects:"identifiant-modele-fiche"|filter_by:"identifiant-champ"|filter_value:"entrouvert"|first|get:"identifiant-champ-à-afficher"

cards|objects: permet d'identifier le modèle de fiche dans lequel on va chercher l'information.

|filter_by: permet d'identifier le champ sur lequel on va faire porter la recherche. Si je souhaite rechercher sur un nom contenu dans un champs form_var_nom de la fiche, je vais écrire|filter_by : "nom".

|filter_value: c'est la valeur recherchée. À noter que ce peut être une variable, typiquement une variable issue du formulaire, on écrira alorsfilter_value:form_var_identifiant-du-champ(sans guillemets).

|first: permet de récupérer uniquement le premier résultat (s'il y en a plusieurs).

|get: permet de désigner le champ contenant l'information que l'on souhaite afficher. Si je souhaite afficher un numéro de téléphone contenu dans le champ form_var_telephone, je vais écrire|get:"telephone".

Les filtres de requêtes s'appliquent aux fiches mais aussi aux formulaires, une section leur est consacrée dans lapage dédiée aux filtres de requête.

Afficher les fiches dans les portails

Les formulaires ne sont pas les seuls endroits où l'on souhaite afficher de l'information issue des fiches, il est fréquent de vouloir le faire également sur le portail citoyen ou sur le portail agent. On dispose pour cela d'une cellule spécifique.

Il existe également unecellule prototype jsonutilisable à titre expérimental mais qui n'est pas destinée à une mise en production.

La cellule fiche(s)

Combo (le CMS qui est utilisé pour fabriquer les portails) dispose d'unecellule « Fiche(s) »qui permet de sélectionner un modèle de fiche et qui affichera l'ensemble des fiches ou uniquement certaines fiches du modèle.

Il faut noter que pour pouvoir voir les fiches qui sont derrière les liens affichés, il est nécessaire de disposer des permissions d'accès nécessaires. On peut cocher une option pour n'afficher que les fiches pour lesquelles l'usager a les permissions nécessaires.

* Studio
* Les tutos

# Paramétrage avancé des fiches

Paramétrage avancé des fiches

Utiliser un identifiant unique personnalisé

Dès que l'on souhaite lier plusieurs modèles de fiche et/ou mettre à jour facilement les fiches, il est recommandé d'utiliser un identifiant personnalisé.

Configurer l'identifiant unique personnalisé

Depuis la page de conception d'un modèle de fiche, un clic sur « Gabarits » permet d'accéder à la zone « Gabarit pour un identifiant unique » qui permet de définir le champ qui sera utilisé comme identifiant (ou de construire cet identifiant sans en faire un champ).

Une fois le gabarit renseigné, l'identifiant est disponible dans la variable{{ form_identifier }}.Si le gabarit de fiche n'est pas défini, {{ form_identifier }} et {{ form_internal_id }} auront la même valeur.

L'identifiant doit être défini avant que des fiches soient enregistrées.
 Si vous  souhaitez le définir a posteriori, vous serez contraint 
d'exporter / effacer / ré-importer les fiches.

L'utilisation de cet identifiant stable permettra d'éviter, par exemple, que les références aux fiches changent lors d'une migration depuis la plateforme de test vers la plateforme de production.

Mettre à jour les fiches

L'autre avantage important lié à l'utilisation d'un identifiant personnalisé stable concerne la mise à jour des fiches lors d'un import CSV (fonctionnalité disponible uniquement lors d'un import JSON auparavant).

La case à cocher « Mettre à jour les fiches existantes » va permettre de mettre à jour toutes les fiches dont l'identifiant existe déjà.

L'import JSON continue de fonctionner comme avant si aucun identifiant personnalisé n'est défini  : l'identifiant interne UUID des fiches est utilisé pour les mises à jour. Mais si un identifiant personnalisé est défini, il est utilisé en lieu et place de l'UUID.

Lier un modèle de fiche à une page

Depuis le menu burger d'une page du portail, vous pouvez utiliser l'entrée « Lier un modèle de fiche » pour choisir le modèle auquel vous voulez lier la page.

Avoir cette liaison permet de disposer d'un paramètre supplémentaire dans les cellules Fiche(s) de la page : « Fiche dont l'identifiant est dans l'URL ». Ce paramètre autorisera l'utilisation d'une URL du type HTTPS://ADRESSE-DE-LA-PAGE/IDENTIFIANT-FICHE/ pour afficher une fiche donnée.

Faire un moteur de recherche sur les fiches

Lacellule recherche de combopeut être configurée pour chercher des usagers, codes de suivi, pages, et/ou demandes.

De la même façon cette cellule, peut être utilisée pour chercher des fiches en plus ou à la place des éléments précités. Pour cela vous devez, dans cet ordre :

* Créer une page dédiée dans combo et utiliser l'entrée « Lier un modèle de fiche » dans le menu burger. Sélectionner le modèle de fiche concerné.
* Ajouter sur cette page une cellule « Fiche(s) » et choisir comme fiche à afficher « Fiche dont l'identifiant est dans l'URL ».
* Sur une autre page du portail, configurer une cellule recherche pour qu'elle utilise cette page. Dans l'écran de configuration de la cellule, en face de  « Ajouter : », cliquer sur le nom du modèle de fiches lié.

Des options supplémentaires pour la recherche de fiches depuis le portail donnent la possibilité de limiter la recherche à une vue personnalisée et de ne pas prendre en compte l’usager connecté. Cochez cette case si vous n'avez pas de résultats dans le moteur.

Avoir des cellules fiches liées sur une page Combo

Après avoir construit un moteur de recherche sur les fiches tel que décrit ci-dessus, il est fréquent de vouloir afficher sur la page de résultat d'autres cellules fiche(s) liées à la cellule fiche(s) principale (celle liée à la page).

Lorsque des modèles de fiches différents utilisent un référentiel commun, ils sont liés. Prenons l'exemple de 3 modèles de fiche :

* Établissements
* Personnes de contact
* Activités

Le modèle des activités contient un établissement qui vient des fiches établissements et c'est la même chose pour le modèle personne de contact. Les modèles « Activités » et « Personnes de contact » sont donc liés par l'utilisation de ce référentiel commun.

Pour exploiter ce lien dans la page combo des résultats, il suffit de donner un identifiant à la cellule fiche(s) principale.

En configurant une cellule fiche(s) secondaire, on aura alors une entrée supplémentaire dans la liste déroulante «Fiche(s) à afficher : », du type « Fiches liées : Établissement - relation inverse ». Cela va nous permettre d'afficher, par exemple, sur la page des activités la fiche de la personne de contact.

Lier un usager à une fiche

Il est fréquemment utile de lier une fiche particulière, contenant des informations métier, à un usager (à un compte) dans Publik. Le but étant :

* de pouvoir donner à cet usager des droits particuliers pour voir / modifier la fiche en question,
* de permettre aux agents habilités de voir immédiatement les informations métier liées à tel ou tel usager.

Pour pouvoir lier des usagers à des fiches, il est nécessaire d'activer dans le modèle de fiche « Lien avec un usager » (en choisissant « Optionnel »).

Une fois fait, on dispose lors de la création ou de la modification de chaque fiche d'une liste déroulante des utilisateurs en barre latérale, elle permet de choisir l'usager que l'on souhaite associer à la fiche.

Lorsqu'une fiche est liée à un usager, le filtre |filter_by_user pourra être utilisé. Par exemple dans une cellule « Contenu d'une fiche », on pourra récupérer l'identifiant d'une fiche grâce à une expression du type :

{{ cards|objects:"enfant"|filter_by_user:request.user|first|get:"id"}}

|filter_by_user:considered_user peut être utilisé dans les formulaires/fiches pour désigner le demandeur et pas la personne connectée (pour un usage backoffice).

Construire une couche cartographique GeoJson avec des fiches

Pour construire unecouche cartographiquegeojson basée sur des fiches, vous devez concevoir un modèle de fiche avec :

* Unchamp de type carte
* Uneaction de géolocalisationdans le workflow

Vous pourrez alors utiliser une URL de ce type comme couche cartographique dans combo :

{{eservices_url}}api/cards/IDENTIFIANT-MODELE-DE-FICHE/geojson?full=on

Cette couche cartographique sera ensuite utilisable pour afficher une carte sur le portail via unecellule carte.

Utiliser plusieurs fiches liées à une demande

Les données d'une fiche liée à une demande sont accessibles depuis cette dernière grâce aux variables {{ form_links_IDENTIFIANT_XXX }} ou XXX désigne les champs de la fiche et IDENTIFIANT le nom de l'action qui l'a créée.

Si plusieurs fiches sont liées à une demande suite à un appel webservice, il est possible d'accéder séparément aux informations des différentes fiches en utilisant un numéro d'index pour désigner la fiche visée :

{{ form_links_IDENTIFIANT_0_form_url }}.

L'ensemble des fiches est en effet accessible dans une liste via :

{{ form_links_IDENTIFIANT }}

Affichage expérimental (déconseillé) : la cellule Prototype JSON

Cette pratique est déconseillée au profit de la cellule Fiche(s).Une cellule prototype JSON n'est pas conçue pour être exploitée en production. Il est possible en revanche de s'en servir de modèle pour développer une cellule combo spécifique utilisable en production.

Configurer un accès aux API

Il s'agit d'un pré-requis. Pour pouvoir utiliser une cellule Prototype JSON, vous devez au préalable créer un compte d'accès aux API.

Depuis l'entrée « Gestion d'identité » du menu latéral vous pouvez accéder à « Clients d'API » puis « Ajouter un nouveau client d'API ».

Vous choisissez alors un nom, un identifiant et un mot de passe (c'est une bonne idée de conserver le mot de passe automatiquement généré) pour cet accès. Après création du compte, ces paramètres seront utilisables dans l'URL de la cellule JSON.

Configurer la cellule

Dans la cellule Combo il faut spécifier une URL de la forme :

https://IDENTIFIANT-API:MOT-DE-PASSE-API@{{eservices_url|split:"://"|get:1}}api/cards/SLUG-DE-LA-FICHE/list/SLUG-DE-LA-VUE/?full=on

Mettez<pre>{{json|pprint}}</pre>dans le corps de la cellule pour afficher l'ensemble de la réponse JSON

Parsez le JSON en utilisant du HTML pour afficher et mettre en forme uniquement les informations que vous souhaitez afficher dans la cellule (et supprimez <pre>{{json|pprint}}</pre> une fois que c'est fait).

Ajouter le paramètrefull=onà l'URL de la cellule permettra de disposer de tous les champs des fiches dans le JSON récupéré.

* Studio
* Les tutos

# Modifier l'information (modifier les fiches)

Modifier l'information (modifier les fiches)

Pour modifier l'information stockée dans les fiches, il y a plusieurs méthodes. Il faut en particulier distinguer les modifications opérées par les usagers, depuis le portail citoyen, et les modifications opérées par des agents, depuis le portail agent.

Modifier les fiches depuis le portail citoyen

Les citoyens ne vont pas accéder directement aux fiches pour les modifier, ils vont le faire via des formulaires qui permettront de modifier tout ou partie d'une fiche. Les modifications s'opèrent grâce à deux actions de workflows à placer dans le workflow associé au formulaire permettant de modifier la fiche.

Action de modification d'une fiche

Cette action de workflowva permettre de pointer une fiche particulière, d'identifier les champs à modifier et d'y associer les valeurs contenues dans le formulaire qui doivent mettre à jour ces champs.

Action workflow externe

Cette actionva permettre d'activer une action globale (configurée pour accepter un déclenchement externe),  existante dans un workflow de fiche.

Une action globale va s'appliquer à une ou plusieurs fiches, c'est donc l'action à utiliser lorsque l'on souhaite modifier plusieurs fiches.

Modifier les fiches en backoffice

Les agents peuvent modifier les fiches directement (quand ils ont le rôle adéquat), mais on peut aussi préférer les faire passer par un formulaire dédié, en saisie backoffice, lorsque des formulaires dédiés existent.

Saisie backoffice dans des formulaires

Si des formulaires ont été élaborés pour permettre aux citoyens de modifier tout ou partie d'une fiche, les mêmes formulaires peuvent être mis à disposition des agents (en leur donnant le rôle de saisie backoffice sur le formulaire) pour opérer les mêmes modifications. C'est le mode de modification qu'on pourra réserver à des agents d'accueil, par exemple.

Modification directe des fiches dans l'interface de traitement

C'est le mode de modification à privilégier pour les agents métier. Il permet en particulier les traitements en masse (lorsque des actions globales adaptées ont été mises en place dans le workflow) ce qui est impossible avec des formulaires de modification.

* Studio
* Les tutos

# Stocker l'information (modèles de fiches)

Stocker l'information (modèles de fiches)

Créer un modèle de fiches

Les données sont stockées sous forme de « fiches ». La première chose à faire pour pouvoir stocker des données est donc de créer un modèle de fiche via l'entrée « Modèle de fiche » du menu latéral. Le modèle de fiche c'est un peu l'équivalent d'une table dans une base de donnée (où chaque fiche serait alors un enregistrement dans la table). La conception d'un modèle de fiche s'apparente à laconception d'un formulaireavec une interface très similaire. Sur le modèle de fiche, il faut affecter des rôles permettant :

* de voir les fiches enregistrées (Visualisation)
* d'enregistrer une nouvelle fiche (Création)
* de modifier une fiche existante (Édition)

Il faut également associer la fiche à unworkflow de ficheexactement comme on le fait pour les formulaires.

Le modèle permet également de définir si les fiches qu'il contient peuvent être liées à des usagers. À terme la liaison avec l’usager sera configurée pour être, au choix, obligatoire ou optionnelle. Pour l’instant seule la partie optionnelle a été développée. La sélection d’un usager via la barre latérale est donc possible pour les fiches, comme pour les demandes saisies en backoffice, si « Optionnel » a été choisi.

Il convient également de définir quels sont les rôles qui vont être autorisés à manipuler (ajouter, voir, éditer) les fiches. Si vous ne disposez pas du rôle permettant de créer les fiches vous ne pourrez pas en ajouter.

Créer les fiches manuellement

Lorsque l'on possède, pour un modèle de fiche donné, le rôle permettant de saisir des enregistrements (rôle de création de fiches), on dispose d'une entrée « Fiches » dans le menu latéral, elle permet de sélectionner le modèle de fiche concerné et de saisir les fiches une à une.

Une fois saisies, les fiches sont présentées sous forme de listing, comme les demandes. Un clic sur une ligne affiche la fiche concernée et permet de travailler dessus via une interface qui dépend duworkflow associé au modèle de fiche.

Créer les fiches en important un fichier CSV ou JSON

Pour gagner du temps, il sera fréquemment utile de créer un grand nombre de fiches automatiquement en important un fichier CSV (encodé en UTF-8 pour éviter les problèmes sur les caractères accentués) ou JSON. Un lien permettant cet import est proposé dans la barre de droite de l'écran de saisie des fiches.

Import CSV

Les colonnes de ce fichier CSV devront être calquées sur les champs de la fiche. Un fichier CSV d'exemple est proposé après avoir cliqué sur import CSV. Il faut respecter scrupuleusement sa structure.

Pour faire un import CSV sur un modèle contenant un type de champ « Liste à choix multiples », il faut utiliser les identifiants (et non pas les libellés) des différents items, séparés par le symbole |.

Pour une liste définie manuellement il n'y a pas de différence entre identifiants et libellés. Pour les autres, vous aurez les identifiants dans l'inspect d'une demande (pour laquelle toutes les cases de la liste ont été cochées) dans la variable  form_var_MA-LISTE_raw.

Import JSON

Il est également possible d’importer des fiches au format JSON. Par rapport au format CSV cela permet notamment d’inclure le contenu de champs de type « Fichier ». Le format JSON utilisé est un format interne pour permettre l’exportation et l’importation de fiches, son format peut évoluer et de ce fait il n’est pas recommandé de l’utiliser avec des applications tierces.

Une fois que des fiches ont été créés, il est fréquent de vouloirles afficher.

Créer les fiches à partir d'un formulaire ou d'une autre fiche

Il est souvent utile de permettre la création de fiches depuis un formulaire ou une autre fiche. On souhaitera par exemple, qu'une fiche concernant une association puisse être créée à partir d'un formulaire « Déclaration d'une association ».

Cela est possible grâce à l'action de workflow «Création d'une fiche». Cette action permettra de créer une nouvelle fiche dans un modèle de fiche donné, et de stocker dedans les informations issues d'un formulaire.

Workflow lié à un modèle de fiche

Un modèle de fiche est associé à un workflow, comme un formulaire, et ce workflow peut être modifié. Le workflow par défaut permet de facilement enregistrer une fiche en offrant dans l'interface de traitement des boutons pour modifier et supprimer une fiche. C'est une bonne idée de partir de ce workflow simple offrant des fonctionnalités de base, pour en construire éventuellement de plus élaborés ensuite.

Il est très souvent utile d'ajouter à son workflow une action globale de suppression : elle permettra typiquement d'effacer l'ensemble des fiches après les avoir sélectionnées, pour procéder à un nouvel import sur un modèle vierge.

Un workflow peut être indifféremment associé à un modèle de fiche ou à un formulaire.

* Studio
* Les tutos

# Liste des tâches

Affichage

Cette vue globale permet d'afficher dans un tableau les demandes associées à plusieurs démarches avec les éléments suivants :

* Le libellé du formulaire concerné.
* Le numéro de la demande.

Cette vue globale a pour objectif d'être un tableau de bord de toutes les demandes potentiellement visibles par un agent, en fonction des ses rôles.

Rechercher, trier, filtrer et sélectionner

La liste des tâches offre un certain nombre de possibilités pour n'afficher que tel ou tel type de demandes.

* Le moteur de recherche « Texte » permet une recherche en texte intégral sur les demandes
* Les demandes du tableau sont triables par colonne en cliquant sur l'intitulé de celle-ci. Un deuxième clic inverse alors l’ordre du tri.
* « En attente de votre part » est choisi par défaut : l'agent loggé ne voit que les demandes pour lesquelles une action est attendue de sa part (plus précisément « de la part de l'un des ses rôles »). Les autres statuts simplifiés pour filtrer la vue globale sont : En attente (demandes dans un statut non final pour lesquelles une action est attendue, mais pas de ma part), Terminé (demandes positionnées dans un statut final), Tous.
* L'affichage peut être limité aux demandes comprises entre la dates de début (incluse) et la date de fin (exclue) si elles sont indiquées (il s'agit de la date de soumission de la demande par l'usager).
* L'affichage peut être limité à une catégorie de démarches particulière.
* Pour aller sur le détail d'une demande, il suffit de cliquer n'importe où sur la ligne correspondante.

Traitement par plusieurs agents

Si un même rôle est attribué à différents utilisateurs (exemple d'un service voirie dont les agents ont collectivement le rôle de traitement des incidents sur voirie), il est possible qu'une demande soit déjà en cours de traitement par un autre utilisateur, Dans ce cas, la demande concernée apparaît en grisé avec un cadenas, en marge gauche, ceci à titre d'information. Il reste quand même possible de traiter cette demande en cliquant dessus : s'affiche alors le message : « Attention, les formulaires de cet utilisateur sont également consultés par : xxxx (il y a moins de x minutes). » et il est possible de « débloquer les actions » pour cette demande.

* Exports

# Tableau de bord

Tableau de bord

Le "Tableau de bord des demandes d'une démarche" offre une vue globale et structurée des demandes associées à une démarche sélectionnée au sein de laliste des démarches.

Le tableau de bord est accessible au gestionnaire lorsqu'il clique sur le libellé d'une démarche depuis laliste des démarchesdont il a la charge.

Le tableau de bord permet de visualiser, toutes les demandes, abouties ou en cours, qu'une démarche sélectionnée a suscité.

Les demandes associées à une démarche sont ainsi centralisées dans un tableau : chaque demande occupe une ligne de ce tableau, tandis que les colonnes distribuent une série de champs communs d'une demande à une autre, tels que "Le nom de l'usager" qui a effectué une demande, "La date de dépôt" de la demande, "Le statut" de la demande, etc.

Pour effectuer un choix de demande à traiter au sein du tableau de bord, le gestionnaire peut affiner l'affichage du tableau grâce aux outils suivants :

* La poigné d'expansion :Elle permet, en un clic, d'étendre ou de réduire l'espace alloué au plan de travail, au détriment ou à la faveur de la barre latérale.
* Les curseurs de tri :À côté du libellé des colonnes du "Tableau de bord", des curseurs, sous forme de flèches, ont pour vocation de trier les demandes: par ordre alphabétique ou ordre croissant/décroissant, selon la nature des données à trier (textuelles ou numériques).

Cliquer sur une demande permet d'accéder auxdétailsde cette dernière.

Export

Pour utiliser les demandes dans un tableur, le gestionnaire a la possibilité de lesexporter. Seules les demandes affichées à l'écran sont exportées.

Statistiques

Le module de "Statistiques"permet de quantifier le volume des demandes, par démarche.

Rechercher, filtrer, trier

Des fonctionnalités permettent de modifier l'affichage des demandes listées dans le tableau de bord.

* Le moteur de rechercheL'outil "Recherche" permet de pointer des demandes en fonction d'une requête textuelle saisie. la recherche s'effectue en texte intégral, comme pour les moteurs de recherche usuels.
* Le filtre "Statut"Par défaut, les demandes liées à une démarche sont listées par ordre de réception. Pour n'afficher que les demandes qui sont dans un statut particulier, un menu déroulant, permet de sélectionner le statut en question. Par ailleurs lorsque qu'on choisit "Terminé", toutes les demandes dont le traitement est fini (i.e. toutes les demandes dans un statut taggé "final") sont affichées. À l'inverse, lorsqu'on choisit "En cours", on affiche toutes les demandes en cours de traitement.
* Paramètrage des colonnesLa composition et l'affichage des colonnes du tableau de bord sont paramétrables selon les besoins et/ou préférences du gestionnaire pour construire desvues personnalisées.

* Exports

# Statistiques internes

Statistiques internes

Attention ces pages de statistiques internes sont progressivement dépréciées au profit de l'utilisation de

pour construire des indicateurs statistiques. Elles seront prochainement abandonnées lorsque la cellule graphe permettra de couvrir tout ce qui est fait ici.

Le module de statistiques internes offre une représentation du nombre de demandes associées à la démarche sélectionnée, en fonction de leurs statuts, de champs du formulaire, et du délai moyen de traitement; ainsi qu'une représentation graphique de l'évolution de ce nombre de demandes dans le temps.

Le nombre de demandes

Dans la colonne de gauche, les statistiques des demandes d'une démarche, sont listées verticalement, par bloc, qui affiche respectivement, le nombre de demandes selon les critères suivants :

* Le statut des demandes associées à la démarche.
* Les champs du formulaire associé à la démarche, qui impliquent des réponses fermées (un champ "Liste" ou "Case à cocher" par exemple).
* Le délai moyen de traitement d'une demande.Ce délai évalue le temps entre la prise en charge et la fin de l'instruction des demandes.

Le nombre de demandes dans le temps

Dans la colonne de droite, sont listées, verticalement, sous forme d'histogrammes, les statistiques de la démarche sélectionnée, toutes demandes confondues, en fonction des vues suivantes :

* La vue "Transmissions par mois"Elle affiche l'évolution du nombre de demandes au cours d'un mois, toutes catégories confondues.
* La vue "Transmissions par jour de la semaine"Elle affiche l'évolution du nombre de demandes au cours d'une semaine, toutes catégories confondues.
* La vue "Transmission par heure"Elle affiche l'évolution des demandes au cours d'une journée, toutes catégories confondues.

Par défaut, le nombre des demandes est indiqué pour le mois, la semaine et la journée en cours.

La barre latérale permet de filtrer dans le temps les statistiques.

Barre latérale de droite

Définir manuellement une période temporelle

Les champs "Date de début" et "Date de fin" permettent de définir une période temporelle.

L'évolution des demandes pour la démarche sélectionnée, dans la colonne de gauche sera ainsi indiquée en fonction de la période définie.

Dans la colonne de droite du plan de travail, l'évolution graphique des demandes sera également affichée en fonction de la période définie.

Définir une période temporelle à l'aide de raccourcis

Les statistiques des demandes d'une démarche peuvent être affichées sur une période pré-définie.

Pour ce faire, il suffit de cliquer sur l'un des raccourcis vers une période pré-définie :

* Mois en cours
* Mois précédent
* Année en cours
* Année précédente

Le calcul du mois et de l'année en cours s'effectue à partir du calendrier civil, et non du jour ouvert. Ainsi, si le 21 avril, une vue du mois précédent est sollicitée, c'est la période du 1er au 30 mars qui sera affichée, non celle du 21 mars au 21 avril.

En fonction du raccourci choisi, les champs "Date de début" et "Date de fin" qui définissent la période sont mis à jour automatiquement.

L'évolution des demandes, dans la colonne de gauche, sera ainsi calculée et affichée en fonction de la période sélectionnée.

L'évolution graphique des demandes sera également calculée et affichée en fonction de la période sélectionnée.

Filtrer les demandes en fonction de champs du formulaire

Les champs impliquant des questions fermées au sein du formulaire associé à la démarche peuvent permettre de filtrer les demandes issues de la démarche en fonction des réponses saisies des usagers.

Pour configurer ce filtre, il faut cliquer sur le lien "changer", et dé/cocher les critères à prendre en compte.

Les statistiques que nous venons d'évoquer sont des statistiques démarche par démarches. Mais on peut aussi voir des statistiques portant sur l'ensemble des démarches depuis l'accueil du traitement. Il suffit de suivre le lien "Statistiques" dans la colonne de gauche.

Les statistiques globales fonctionnent comment les statistiques par formulaire, sauf en ce qui concerne le temps passé dans chaque statut : comme les statuts sont différents d'une démarche à l'autre, il est impossible de faire des statistiques globales en la matière.

* Exports

# Exports

Exports

L'export des demandes est accessible depuis la barre latérale droite dutableau de bord.

Une fenêtre de configuration de l’export des tableaux de 
traitement, permet de choisir :

* "Export vers tableur" : implique un format d'exportOpen Document, moderne et standardisé, lu par une majorité des logiciels tableurs comme celui de LibreOffice (y compris Excel depuis 2003).
* "Export au format CSV" : implique un format d'export de type "texte", caractérisé par des (points-)virgules pour distinguer les différents champs du tableau.
* La présence 
ou l'absence d'une première ligne de titre.

* Exports

# Vues personnalisées

⚙️ Accès dans le BO :Traitement > Vue par formulaires > 👉 un formulaire

Les tableaux de traitement des demandes offrent aux agents et aux administrateurs la possibilité de personnaliser l'affichage des demandes. Ils peuvent choisir lescolonnesqui doivent s'afficher dans le tableau (champs des demandes) et définir descritèresde tri et de filtrage, non seulement sur ces champs, mais aussi sur d'autres éléments.Il est ensuite possible d'enregistrer cette vue, que l'on appelle vue personnalisée. Le nombre de vues personnalisées n'est pas limité.

Les critères

Depuis la barre latérale de droite du

tableau de traitement

on accède à la liste des critères utilisables en cliquant sur « Critères ».  Ces critères sont utilisés en conjonction avec des opérateurs. Parmi ces critères on va trouver :

* Les champs du formulaire
* Des dates de début et de fin
* Le statut
* Les fonctions existant dans le workflow

Concernant les opérateurs on pourra :

* faire une comparaison simple :égal, différent, supérieur, inférieur
* vérifier la présence ou l'absence d'une valeur dans le champ :absent, existant
* sélectionner un intervalle entre telle et telle valeur :entre
* trier sur la présence ou l'absence dans une liste de valeurs :dans, pas dans
* Pour les champs date, possibilité d'utiliser des critères prédéfinis :Hier, Aujourd'hui, Demain, Cette semaine

Les colonnes

tableau de traitementle lien

« Colonnes » va permettre de choisir les colonnes à afficher et de les classer dans l'ordre souhaité.

Un clic sur le titre de la colonne va permettre de classer les fiches/demandes dans un ordre croissant/décroissant concernant la colonne en question

Limiter la vue à un rôle donné

L'administrateur peut décider de laisser tout le monde utiliser une vue ou se la réserver. Mais pour plus de granularité, chacun a la possibilité de créer des vues personnelles et de les rendre disponibles pour les personnes qui partagent le même rôle.

Par exemple, je suis en charge de l'instruction des demandes de stationnement, je peux partager ma vue personnalisée avec mes collègues qui sont également en charge du traitement de ces demandes.

Il existe plusieurs niveaux de granularité concernant la visibilité de ces vues personnalisées :

* par moi uniquement: un agent qui possède au minimum une fonction sur un formulaire (il a donc le droit de visualiser les demandes de ce formulaire) peut enregistrer une vue pour lui-même ;
* par le rôle:un agent peut enregistrer une vue pour les rôles qu'il possède directement ou par héritage lorsque ces rôles sont associés à une fonction sur le formulaire ;
* par tout le monde:un agent peut enregistrer une vue pour tout le monde s'il possède un rôle disposant des permissions d'administration dans la brique W.C.S. pour les formulaires, comme c'est le cas du rôle « Administrateur fonctionnel ».Attention, cette permission permet notamment de modifier les formulaires et d'accéder aux vues de toutes les demandes.

Sauvegardes

Une fois que tous les éléments ont été affichés et triés de façon satisfaisante, il est possible de sauvegarder la vue obtenue afin de pouvoir la réutiliser ultérieurement. La vue sauvegardée peut être rendue accessible à tout le monde ou réservée à son auteur. Dans tous les cas le lien vers cette vue personnalisée apparaît à l'écran dans la barre latérale de droite. Il est possible de construire plusieurs vues personnalisées différentes, sans limitations.

On peut choisir d'indiquer que la vue enregistrée doit être la vue par défaut, afin que le tableau de traitement adopte cette vue dès que l'on arrive sur la page du listing.

La case à cocher « Mettre à jour les paramètres » permet d'écraser la vue en cours avec les nouveaux paramètres choisis.

Les vues personnalisées permettent de définir un « gabarit » spécifique qui sera utilisé en lieu et place du gabarit par défaut du modèle de fiche.

Pour les vues créées sur des fiches, il existe une possibilité supplémentaire. On peut enregistrer la vue personnalisée commesource de donnéeafin qu'elle puisse alimenter les champs liste et texte. Définir un « résumé » (gabarit d’affichage) particulier qui se substituera au résumé par défaut du modèle de fiche, permet de déplacer le focus de la source de donnée d'un champ vers un autre, comme on le faisait auparavant avec les « projections » pour les fichiers CSV.

Pour aller encore plus loin, on utilisera des

[vues personnalisées dynamiques](https://doc-publik.entrouvert.com/admin-fonctionnel/developper-des-applications-simples-avec/afficher-linformation/#vues-personnalisees-dynamiques)

qui permettent de faire varier la vue personnalisée en fonction du contenu d'un élément de la page en cours.

Sources de données avec regroupement

Lorsque l'on enregistre une vue personnalisée dans un listing de fiches et qu'elle est utilisée comme source de données, il est possible d'indiquer qu'un champ de type liste doit être utilisé comme valeur de regroupement.Par exemple, si un champ contient les valeurs "Fruit" et "Légume", il est possible de regrouper les fiches selon ces catégories.

Cette source de données aura un rendu différent selon qu'elle est utilisée dans un champ de type Liste (affichage liste) ou Liste à choix multiple (affichage cases à cocher):

* Exports

# Vue sur une carte

Vue sur une carte

Quand les demandes sont géolocalisées, elles apparaissent sur une carte.

Toutes démarches confondues

Depuis lavue globale, un lien « Vue sur une carte » permet d'afficher une carte avec un pins pour chaque demande, toutes démarches confondues. Un clic sur le pins, ouvre la demande (lorsqu'on a le rôle nécessaire pour la voir).

Il est possible d'utiliser les filtres pour faire varier les catégories et l'état des démarches affichées.

Démarche par démarche

Depuis laliste des démarches, on peut cliquer sur une démarche et arriver sur la liste des demandes pour cette démarche. On dispose alors d'un lien « Rendu sur une carte » permettant d'afficher la même carte que précédemment mais uniquement pour cette démarche particulière.

* Exports

# Détails d'une demande

Détails d'une demande

Le Détail d'une demande permet au gestionnaire d'évaluer le contenu d'une demande d'usager, de visualiser l'état d'avancement de cette demande, d'en faire évoluer l'état, potentiellement d'interagir avec l'usager qui a introduit la demande, et de connaître toutes les demandes introduites par l'usager.

Le "Détail d'une demande" est accessible depuis letableau de bordou laliste des tâchesen cliquant sur une demande.

La vue "Résumé" d'une demande d'usager

La "Vue résumé" donne un aperçu des données saisies au sein du formulaire qui formalise la demande d'un usager. De cette manière, le gestionnaire peut vérifier le contenu d'une demande, et notamment, sa recevabilité.

Elle précise également le statut actuel de la demande.

Cette vue peut être masquée en cliquant sur le titre de la vue. De cette manière, l'utilisateur gagne en espace de travail.

La vue "Journal"

Cette vue propose un historique des différentes étapes par lesquelles est passé la demande et permet de visualiser son état d'avancement au sein de son circuit de traitement.

Saisir des informations

Pour faciliter l'instruction des demandes, l'administrateur fonctionnelqui a conçu la démarche, peut décider d'autoriser la saisie d'informations, sous forme de commentaires ou autre champs, lors de certaines étapes du traitement.

En fonction de la façon dont la démarche a été conçue, on peut :

* Commenter une demande sans changer le statut de la demande :Lorsque le commentaire ne doit pas s'accompagner d'un changement de statut, le gestionnaire doit cliquer, après la saisie du commentaire, sur « Ajouter un commentaire ». Le commentaire est alors ajouté au journal mais la demande reste dans le même statut.
* Saisir des informations et changer le statut de la demande :Une fois la zone de saisie du commentaire complétée, le gestionnaire doit cliquer sur l'option de traitement souhaitée. Les informations sont alors intégrées à la demande (et éventuellement envoyées par mail), et la demande change de statut.

Faire progresser le statut d'une demande

Pour faire évoluer la demande, le gestionnaire doit cliquer sur un des boutons d'action à sa disposition.

Au survol du bouton, une aide contextuelle apparaît surlignée afin d'expliquer à quoi sert le bouton en question.

Dansla barre latérale, le gestionnaire a accès à l'identité de l'usager de la demande sélectionnée, ainsi qu'à la liste des éventuelles autres demandes en cours de cet usager.

* Exports

# Glossaire

Glossaire

Action(au sein d'un workflow) : élément attaché à un statut de workflow, qui permet d'enclencher un évènement manuellement (déclenchement par un agent via un bouton) ou automatiquement.

Action globale(au sein d'un workflow) : action qui, au lieu d'être attaché à un statut particulier, est réalisable depuis tous les statuts d'un workflow.

Agent: personne disposant d'un compte utilisateur et d'un rôle lui permettant d'accéder au portail agents de Publik ; en fonction du ou des rôles attribués au compte, l'agent pourra avoir accès aux écrants de traitement, création de démarches, paramétrage, ...

Administrateur fonctionnel: agent de la collectivité chargé du paramétrage fonctionnel de la plate-forme i.e. création et entretien des formulaires et workflows, administration des utilisateurs (création, attribution des rôles), mise en page des pages du portail usager (front-office) et du portail agents (back-office).

Agent d'accueil: agent chargé de la réception des demandes des usagers au guichet et/ou téléphone. Il a pour rôle de transformer la requête de l'usager en une demande formalisée (i.e. saisie dans un formulaire) qui sera alors transmise à un agent instructeur; les rôles d'agent d'accueil et agent instructeur peuvent être cumulés.

Agent instructeur: l'agent instructeur ou agent traitant ou gestionnaire des demandes, a pour mission de traiter les demandes d'usagers, saisies au sein d'un ou plusieurs formulaire(s) en ligne dont il a la charge.

Brouillon: démarche démarrée par un usager mais qui n'a pas été validée. Un brouillon est accessible avec le code de suivi si celui-ci est activé sur le formulaire et grâce à la cellule combo "Brouillons en cours". Il est également créé automatiquement pour les usagers qui effectue leur demande avec un compte. La durée de conservation du brouillon peut être paramétrée de 2 à 100 jours.

Catégorie(de formulaires) : unité de regroupement (pour affichage) des formulaires en front-office et en back-office.

Champ de formulaire: élément permettant pour l'usager de saisir ou d'accéder à une information. Un formulaire est composé de 1 à n champs.

Champ de traitement(au sein d'un workflow) : élément défini au sein d'un workflow et dont la ou les valeurs sont stockée(s) en cours de traitement.

Demande: informations saisies par un usager, dans un formulaire, pour adresser une requête à la collectivité. La demande est alors traitée par la collectivité. Il y a donc n demandes associées à une démarche.

Démarche: ensemble constitué d'un formulaire et d'un workflow associé.

Fonction(au sein d'un workflow) : élément défini au sein du workflow qui permet d'établir une responsabilité dans le traitement, par exemple « Destinataire » ou « Valideur ». Cette responsabilité est associée, dans le formulaire, à un rôle.

Formulaire: canevas construit par la collectivité pour permettre aux usagers de saisir leurs demandes (dans la terminologie Publik, le formulaire est donc le contenant des demandes, il peut y avoir un grand nombre de demandes par formulaire).

Portail agents: pages accessibles uniquement aux agents, le portail agents présente une page d'accueil, configurable, et l'accès à divers éléments. Les éléments varient en fonctions des rôles attribués à l'agent, le terme de back-office est un synonyme de « Portail agents » .

Portail usagers: pages web exposant le tableau de bord de l'usager, son profil, ses demandes en cours, ses brouillons.... ainsi que l'ensemble des démarches disponibles. Le terme de front-office est un synonyme de « Portail usager » ; en fonction du paramétrage, certaines pages ou démarches peuvent être accessibles uniquement après identification.

Rôle: associer un compte utilisateur à un rôle permet de lui donnet des droits sur la plate-forme. Ces permissions peuvent être techniques (droit de fabriuer des démarches) ou métier (droit de traitement d'une ou plusieurs démarchess). Les rôles peuvent être attribués aussi bien aux agents qu'aux citoyens.

Rôlesinternes: rôles existant dans chaque instance Publik, ils donnent des droits d'administration pour les différentes briques de Publik.

Statut(au sein d'un workflow) : étape par laquelle transite les demandes, un workflow est composé de 1 à n statuts.

Usager: personne ayant complété un formulaire en ligne et/ou disposant d'un compte Publik ; en général, l'usager se crée lui-même son compte.

Variable: référence de la valeur saisie dans un champ de formulaire afin de pouvoir l'utiliser par ailleurs (intégration dans un courriel ou document, intégration dans une condition d'affichage de page, transmission vers un logiciel tiers via webservice, ...)

Workflow(ou circuit de traitement) : succession de statuts modélisant le processus de traitement d'une demande, un formulaire ne débouche que sur un seul workflow mais un workflow peut être utilisés par plusieurs formulaires.

Retrouvez deux fois par moisles notes de mises à jouret toujours plus de tutoriels, d’exemples, de captures d’écran et même de vidéos pour vous aider dans la prise en main des nouveautés et la maîtrise de Publik.

Vous êtes ?

* Agent d’accueil
* Admin fonctionnel
* Admin technique

Nous vous recommandons

* Transformez une données avec les filtres Django
* Utilisez les conditions, dans les champs, dans les pages, dans les workflows
* Personnalisez vos contenus avec les classes CSS

Explorez la documentation

* Notes de mises à jour
* Tour d’horizon
* Guide de l’agent traitant
* Guide de développement
* Allez plus loin
* +

* Liste des connecteurs27 février 2025
* Utiliser les filtres24 février 2025
* Détail d’un formulaire24 février 2025
* Création de document24 février 2025
* Champ carte24 février 2025
* Archives 202422 février 2025

Vue personnalisée dynamique

Petite vidéo explicativeMettre en place une vue personnalisée dynamique

Votre navigateur ne supporte pas les vidéos embarquées.Configurer la prise de rendez-vous backoffice

Découvrir la gestion des applications

Échangez avec les membres du club utilisateurs

Développez et partagez votre expertise avec les autres. Répondez aux questions et améliorez vos connaissances.Vous n’avez pas de compte sur Tracim ? Demandez-en un à votre chef de projet chez Entr’ouvert.

https://publik.tracim.fr/

# Champ texte

Champ texte

Le champ « Texte (ligne) » est dédié à la saisie d'un texte libre, tenant sur une ligne.

Un texte libre peut comprendre des lettres, des chiffres et des caractères spéciaux.

Contrôle de ce qui est saisi dans le champ

L'option « Validation » permet de faire porter un contrôle sur le champ pour vérifier que les données saisies correspondent bien au format attendu pour. Il est donc possible de contrôler que ce qui a été saisi est bien :

Chiffres

Heure

Cette validation permet au navigateur de comprendre qu'il s'agit d'un champ horaire et d'adapter son comportement - avec un téléphone mobile on aura par exemple l'affichage d'une horloge pour sélectionner l'heure)L'heure doit être comprise entre 00:00 et 23:59.

URL

Pour être valide, l'adresse renseignée doit commencer par http:// ou https://

Numéro de téléphone

Accepte un numéro de téléphone international

Numéro de téléphone France

Accepte un numéro de téléphone à 10 chiffres, par exemple 06 39 98 89 93.

Numéro de téléphone mobile (local)

Accepte un numéro de mobile correspondant au pays configuré par l'administrateur dans « Système » dans les options SMS - par défaut la France

Code postal (France)

Code postal à 5 chiffres, par exemple 75014.

Code SIREN (France)

9 chiffres, par exemple 443170139.

Code SIRET (France)

14 chiffres, par exemple 44317013900036.

Numéro de sécurité sociale / NIR (France)

15 chiffres

Numéro de pré-demande ANTS

Numéro d'allocataire CAF

Avis d'impôt - Numéro fiscal

13 chiffres

Avis d'impôt - Référence de l'avis

Numéro RNA

Commence par W

Numéro au registre nationale (Belgique)

11 chiffres

IBAN

Expression rationnelle

Il est également possible de contrôler la saisie par le biais d'expression rationnelle(en respectant la syntaxe des expressions régulières Python).

Exemples d'expressions régulières :

* \d+(?:[.,]\d+)?$ : nombre à virgule (le séparateur peut être une virgule ou un point)
* (([9][7][0-8])|([9][8][0-5]))([0-9]{2}) : code postal Dom-Tom
* ^([0-1][0-9]|2[0-3])[H;h][0-5][0-9]$ : heures minutes avec le format de type 11h30 ou 11H30
* [A-Z '-]+ : texte seulement en majuscules et espace, apostrophe, tiret et au moins un caractère
* [A-Z ÀÂÄÇÉÈÊËÎÏÔÖÙÛÜŸÆŒ '-]+ : idem mais avec majuscules accentuées, champ vide possible (de 0 à n caractères)

Il existe des sites d'explicationdes expressions régulières (regex) en python ainsi que des sites pourvalidervos expressions régulières.

Condition (Django)

Exemples de validation Django :

* value|decimal > 60 : la valeur est supérieure à 60
* value|length < 50 : la valeur fait moins de 50 caractères
* value == "oui" : la valeur est exactement « oui »

« value » est le terme exact à utiliser, il représente la valeur du champ courant.

Pour en savoir plus sur la syntaxe des conditions, reportez-vous àcette page.

Message d'erreur personnalisé

Il est possible d'ajouter à ces contrôles un message d'erreur. Lorsque ce qui est saisi ne correspond pas à ce qui est demandé, le message d'erreur ainsi paramétré sera affiché.

Nombre maximal de caractères

On peut également paramétrer un nombre maximum de caractères. Cela va par exemple permettre d'empêcher de saisir plus de 10 caractères.

[Nom de variable](https://doc-publik.entrouvert.com/admin-fonctionnel/utiliser-les-variables/)

: Permet de réutiliser la valeur d'un champ au sein d'un mail, d'un SMS, d'une condition...

[Préremplir](/admin-fonctionnel/fabrique-formulaires/preremplissage-des-champs/)

: Permet de remplir le champ automatiquement avec une valeur sans intervention de l'usager

[Autres paramètres](https://doc-publik.entrouvert.com/admin-fonctionnel/fabrique-formulaires/form-champs/parametres-champ-generiques/)

: obligatoire, remarque, afficher dans les listings, classe supplémentaire pour les CSS.

* Studio
* Les tutos

# Champ liste à choix multiple

Champ liste à choix multiple

Le champ liste à choix multiple est indiqué lorsque l'information sollicitée auprès des usagers peut comporter 0, 1 ou plusieurs réponses parmi un ensemble d'éléments.

Propriétés spécifiques du champ liste (choix multiple)

Éléments

C'est en ajoutant des « Éléments » à la liste que l'administrateur fonctionnel compose son contenu. Les éléments peuvent être ré-ordonnés par glisser / déplacer.

Nombre maximal de choix

Il est possible de poser une limite haute au nombre d'éléments à choisir. Par défaut cette valeur est à 0 et, dans ce cas, la limite maximale est égale au nombre total d'éléments proposés i.e. il est possible de choisir tous les éléments.

Autocomplétion

Choisir « Autocomplétion » comme mode d'affichage permet de voir la liste des éléments sélectionnables s'affiner au fur et à mesure que l'on tape des caractères au clavier. Très utile pour les longues listes. Untutoriel spécifique sur l'autocomplétion, donne plus de détails.

Anonymiser

En comportement standard, les champs listes sont conservées lors de l'opération d'anonymisation (contrairement aux champs libres qui sont systématiquement effacés) mais dans certains cas (exemple : remontée d'une liste d'enfants depuis logiciel famille) il est nécessaire d'effacer également ces champs de type liste : il faut alors activer cette option « Anonymiser ».

Afficher les éléments désactivés

La source de données (fichier csv) utilisée pour l'affichage des éléments de la liste peut comporter des lignes « désactivées », si tel est le cas et si cette  option est activée alors ces éléments seront affichés mais ne seront pas sélectionnables.

: Permet de remplir le champ automatiquement avec une valeur sans intervention de l'usager. Il faut préremplir avec un tableau, par exemple : ['Pomme', 'Poire'].

* Studio
* Les tutos

# Champ liste

Champ liste

Le champ liste est indiqué lorsque l'information sollicitée auprès des usagers est un choix unique parmi un ensemble d'éléments. Par défaut, un champ liste est présenté sous forme d'une liste déroulante.

Type de liste

Liste simple

C'est le type de liste par défaut, celui qui va permettre d'ajouter un par un des éléments qui seront affichés dans ladite liste sur le formulaire.

Source de données

C'est un type de liste plus élaboré qui permet d'indiquer que la liste sera alimentée par unesource de donnée. C'est le type à privilégier pour toutes les listes qui doivent être utilisées sur plusieurs formulaires.

Lorsque les champs/actions sont configurés pour utiliser des sources de données, il y a un bouton « flèche » à côté du champ qui permet d'accéder directement à la source en question.

L'utilisation d'une source de données issues de fiches permettra entre autres choses l'utilisation de

[sous-listes](https://doc-publik.entrouvert.com/agent-traitant/traitement/vues-personnalisees-du-tableau-de-bord/#sources-de-donnees-groupees-sous-listes)

.

Mode d'affichage de la liste

Liste

La liste sera affichée sous forme de liste déroulante classique. Les éléments peuvent être ré-ordonnés par glisser / déplacer.

Boutons radio

Les éléments de la liste seront exposés sous forme de boutons radio. L'affichage en boutons radio convient plus particulièrement aux listes courtes, pour lesquelles le fait de voir directement l'ensemble des éléments en permanence et sans avoir à cliquer est un avantage. Les éléments peuvent être ré-ordonnés par glisser / déplacer.

Choisir « Autocomplétion » comme mode d'affichage permet de voir la liste des éléments sélectionnables s'affiner au fur et à mesure que l'on tape des caractères au clavier. Très utile pour les longues listes. Un

[tutoriel spécifique sur l'autocomplétion](https://doc-publik.entrouvert.com/admin-fonctionnel/les-tutos/aide-a-la-saisie/)

, donne plus de détails.

Cartes (données géographiques)

Ce mode de visualisation permet l'affichage des différents éléments de la liste sur une carte lors d’utilisation de données cartographiques (source de données au format GeoJSON). Il n'est donc utilisable qu'avec le

[type de liste « Source de données »](https://doc-publik.entrouvert.com/admin-fonctionnel/fabrique-formulaires/form-champs/champ_liste/#source-de-donnees)

et en utilisant une

[source de donnée](https://doc-publik.entrouvert.com/admin-fonctionnel/parametrage-avance/sources-de-donnees/)

au format GeoJSON

Horaires

Ce mode de visualisation permet l'affichage des différents éléments de la liste sous forme de créneaux horaires répartis dans un calendrier. Il n'est utilisable qu'avec le

liée à un agenda.

Images

Le mode d'affichage « Images » permet d'afficher une série d'images issues de fiches, accompagnées du texte du gabarit du modèle de fiche. Pour que cela fonctionne, il faut utiliser comme source de données du champ liste un modèle de fiches contenant un champ fichier avec « image » comme identifiant.

L'affichage d'une liste d'images prévoit un libellé pour chaque image.

Ce libellé a la valeur du gabarit personnalisé de la fiche.

Affichage sous forme d'étoiles (vote, enquête de satisfaction)

Il est possible d'utiliser ce champ pour permettre à l'usager de donner son avis sur un sujet. Pour cela il faut commencer par définir la liste des valeurs possibles (par exemple un chiffre de 1 à 5). Il y aura autant d'étoiles que de valeurs définies. Ensuite il est nécessaire d'indiquer le style csstemplate-evaluationdans le champ « Classes supplémentaires pour les styles CSS » et de choisir le mode d'affichage« Boutons radio»(paramètres avancés du champ).

Vous obtiendrez alors en front-office un rendu sous forme d'étoiles sélectionnables.

Liste avec des sous-listes

Il est possible d'avoir plusieurs niveaux dans une liste (2 niveaux) :

Lorsque l'on configure, dans un listing de fiches, une vue personnalisée utilisée comme source de données, il est possible d'indiquer que tel ou tel champ de type liste doit être utilisé comme valeur de regroupement. Dans l'exemple de la capture, le champ liste utilisé comme regroupement contient les valeurs « Fruit » et « Légume ».

Options

En comportement standard, les champs listes sont conservés lors de l'opération d'anonymisation (contrairement aux champs libres qui sont systématiquement effacés) mais dans certains cas (exemple : remontée d'une liste d'enfants depuis un logiciel famille) il est nécessaire d'effacer également ces champs de type liste : il faut alors activer cette option « Anonymiser ».

Ajouter dans les filtres par défaut

Cocher cette case va permettre d'utiliser la liste en question :

* en tant que « Critère » d'affichage (en marge droite dans les tableaux de traitement « Vue par formulaires »),
* en tant que filtre pour les statistiques.

Nota bene : cette option n'est pas activée par défaut.

Utiliserla remarque comme première option

Dans le cas d'un menu déroulant, le premier élément de la liste sera par défaut sélectionné si aucun choix explicite n'est effectué par l'usager, comportement qui peut être problématique.

Pour éviter la sélection par défaut du premier élément d'une liste déroulante, vous pouvez mettre un texte dans «  Remarque ». Par exemple, « Choisissez dans cette liste », « Votre choix », ou encore « --- ». Si vous cochez « Utilisez la remarque comme première option », ce texte sera affiché par défaut mais l'usager sera bien obligé de choisir une « vraie » valeur si le champ liste est obligatoire.

* Studio
* Les tutos

# Appeler un webservice

Appeler un webservice

Cette action est plus technique que les autres et peut nécessiter qu'un connecteur vers une application tierce ait été développé au préalable. Elle est utilisée/configurée par les services informatiques.

L'action « Webservice » permet d'appeler un système tiers et, éventuellement, de lui transmettre des données, dont celles issues de formulaires de demandes d'usagers ayant atteint le statut qui contient cette action.

L'action webservice permet de générer un fichier plutôt qu'une réponse JSON en cochant « Fichier joint » comme type de réponse (dans l'onglet réponse). Si une donnée de traitement de type « Fichier » existe dans le workflow, il sera possible de la lier à ce fichier en la sélectionnant dans la liste déroulante « Enregistrer le document généré comme donnée de traitement ».

Édition

Les étapes d'édition de l'action « Webservice » sont les suivantes :

* Indiquer le libellé de l'appel du webservice.
* Saisir l'URL du webservice sollicité.Le champ « URL » est obligatoire.L'URL peut contenir des variables, pour afficher une information particulière. Dans « Données à envoyer en paramètres à l'URL », on peut spécifier un couple clé/valeur. Par exemple en utilisantemailet{{session_user_email}}, on va pouvoir former une URL qui sera https://www.example.net/notify?email={{session_user_email}}
* Choisir la méthode utiliséeGET : pour récupérer un élémentPOST : Pour envoyer un élémentPUT : Pour créer un élémentPATCH : Pour mettre à jour un élémentDELETE : pour effacer un élémentSi aucune donnée n'est indiquée et que le formulaire ne doit pas être transmis, alors la requête HTTP effectuée est un GET sur l'URL.
* Dé/Cocher la case « Envoyer les données du formulaire ».Ce choix est proposé si méthode POST, PUT ou PATCH choisie. Cochée, la case indique que l'ensemble des données du formulaire doit être transmis, avec un appel dont le contenu correspondra au formulaire encodé au format JSON, comme décrit sur cettepage sur l'API.Si la case « Envoyer les données du formulaire » est cochée et que des « Données à envoyer dans le corps de la requête » sont indiquées, alors ces dernières sont ajoutées dans le JSON du formulaire, dans une clé « extra ».
* « Données à envoyer dans le corps de la requête » permet d'indiquer les données qui seront transmises sous la forme d'un dictionnaire clé-valeur au format JSON.
* Sur chaque ligne, la colonne de gauche est le nom de la clé, celle de droite, la valeur.ExempleCe tableau de valeurs :code_appelw.c.s.form_number{{form_number}}formera ce JSON :{
    "code_appel": "w.c.s.",
    "form_number": "4"
  }
* Le paramètre « Identifiant » permet d'enregistrer le résultat retourné par l'appel dans une variable du type {{ form_workflow_data_IDENTIFIANT_response_XXX  }} . Quand la réponse correspond au format classique des API Publik, on aura :{{ form_workflow_data_IDENTIFIANT_response_data  }} pour récupérer les données retournées en JSON,{{ form_workflow_data_IDENTIFIANT_response_data.0  }} pour récupérer le premier enregistrement d'un tableau JSON,{{ form_workflow_data_IDENTIFIANT_response_data.0.NOM-COLONNE  }} pour récupérer la valeur d'une colonne du tableau pour un enregistrement donné,{{ form_workflow_data_IDENTIFIANT_status  }} pour récupérer le statut http de la requête (200 signifie qu'elle s'est bien passée),{{ form_workflow_data_IDENTIFIANT_response_err  }}  pour récupérer les erreurs (1 signifie qu'il y a eu une erreur, 0 signifie qu'il n'y en a pas eu)Attention lorsque l'on utilise l'API d'Authentic (le fournisseur d'identité qui gère les rôles et les utilisateurs), la réponse ne se trouvera pas dans la variable{{ form_workflow_data_IDENTIFIANT_response_data}} mais plutôt dans{{ form_workflow_data_IDENTIFIANT_response_results}}
* L'onglet "gestion des erreurs" permet de faire partir la demande dans le statut de votre choix lorsque l'appel renvoie une erreur. Cela permet d'identifier rapidement une demande en erreur.

* Studio
* Les tutos

# Gérer les Collectivités

Gérer les Collectivités

Modifier les paramètres d'une collectivité

⚙️ Accès dans le BO :Gestion d'identités > Collectivités > Collectivité par défaut

Cette page comporte de nombreuses paramètres qui sont personnalisables.

Les utilisateurs peuvent réinitialiser le mot de passe

Politique de création de mot de passe des utilisateurs

Compte inactif

L’envoi d’un courriel d’alerte avant la suppression d’un compte repose sur une durée (exprimée en jours) calculée à partir de la dernière connexion de l’usager. Une fois ce délai dépassé, le compte est considéré comme inactif.Deux paramètres distincts permettent de configurer cette suppression automatique :

* Nombre de jours avant l’alerte de suppression de compte
* Nombre de jours avant la suppression des comptes inutilisés

Cette suppression automatique concerne tous les comptes, y compris ceux ayant utilisé FranceConnect.

Le courriel d’alerte envoyé aux usagers n’est pas personnalisable.

* Studio
* Les tutos

# Déclarer des services OIDC

Déclarer des services OIDC

Cette page liste les services i.e. les différentes briques composant Publik mais elle permet également de déclarer de nouveaux services suivant le protocole OIDC (OpenID Connect), seul ce deuxième aspect est détaillé ci-dessous.

Si vous souhaitez utiliser Publik comme fournisseur d'identités (FI) pour des application tierces (fournisseur de serice - FS) tel, par exemple, un portail de médiathèque ou un portail famille, vous pourrez déclarer ce fournisseur de service via le bouton « Ajouter un service OIDC ».

* Identifiant du client (client id) : cet identifiant doit être transmis au gestionnaire de l'application tierce pour son propre paramétrage.
* Secret du client (client secret) :idem ; comme son nom l'indique, ne transmettez ce secret qu'au gestionnaire de l'application tierce, de préférence par un moyen sécurisé..
* URIs de redirection : cette ou ces URLs vous seront fournies par le gestionnaire de l'application tierce.
* URIs de redirection après déconnexion : idem.

Toutes les autres champs non mentionnés ci-dessus peuvent être laissés vides ou à leur valeur par défaut.

Afin que le gestionnaire de l'application tierce puisse paramétrer son application en tant que fournisseur de service OIDC, il aura également besoin des informations disponibles sur une adresse du type https://connexion.demarches.votreville.fr/.well-known/openid-configuration. Par exemple, pour ce présent site de documentation, qui est construit avec une instance Publik, l'URL est :

https://connexion-doc-publik.entrouvert.com/.well-known/openid-configuration

* Studio
* Les tutos

# Champ courriel

Champ courriel

Spécificités du champ courriel

Le champ « Courriel » est indiqué lorsque l’information sollicitée auprès des usagers est une adresse électronique.

Remarque : L’action de workflow « Envoyer un courriel » à « Usager » envoie un message à l’usager qui a fait la demande. Le premier champ de type « Courriel » avec un préremplissage « Champ utilisateur » = « Adresse électronique » sera utilisé comme adresse courriel de l’usager.

Le champ est contrôlé : si l’usager saisit une adresse mail incorrecte (sans @ ou dont le nom de domaine n’existe pas), il sera alerté par un message d’erreur.

: Permet de réutiliser la valeur d’un champ au sein d’un mail, d’un SMS, d’une condition...

: Permet de remplir le champ automatiquement avec une valeur sans intervention de l’usager

* Studio
* Les tutos

# Alerte

Alerte

L'alerte est affichée uniquement dans le statut dans lequel elle est déclarée. Lorsque la demande passe dans un autre statut l'alerte disparaît. Pour afficher un message pérenne (visible pendant toute la durée du traitement de la demande) préférez l'action "Message dans l'historique".

L'action« Alerte » a pour effet l'affichage d'un texte explicatif affiché en haut ou en bas de page lorsqu'une demande atteint le statut qui contient l'action.

L'option « Position » permet de choisir entre « Haut de la page » ou « Bas de la page » (qui affiche un message, juste au-dessus des éventuels boutons d'actions).

L'option « Niveau »  permet de définir le style qui sera appliqué à ce message d'alerte en fonction de son importance : information, succès, avertissement, erreur. En front office comme en backoffice, des icônes et une couleur spécifiques seront liées au message en fonction de ce qui est choisi ici.

Front Office

Backoffice

Édition

Les étapes d'édition de l'action « Alerte » sont les suivantes :

* Rédiger le message. Édition en texte riche dans le corps du message.  ou utilisation de codehtml. Un certain nombre de variables peuvent être saisis.
* Sélectionner au sein d'une liste déroulante, et ajouter les fonctions et/ou les rôles d'utilisateurs à qui est destiné le message.
* Option supplémentaire :Condition. Il est possible de lier l'affichage de ce message à une condition.

Utilisation dans une action globale

Dans une action globale, l'action « Alerte » peut être exécutée avec un déclencheur manuel.Il y a toutefois deux limitations :

* un seul message peut être affiché à la fois (si plusieurs actions « Alerte » sont ajoutées, seule la dernière est affichée) ;
* elle ne s’applique qu’aux actions individuelles sur les demandes ou les fiches, excluant les actions en masse.

* Studio
* Les tutos

# Requête sur fichier tableur (ODS ou CSV)

Attention: l'utilisation d'un fichier tableur comme source de données est en cours de dépréciation, au profit de l'utilisation desfiches. Aussi, si vous devez créer maintenant une source de données, prévoyez directement une gestion de votre source de données à base de fiches.

Requête sur fichier tableur (ODS ou CSV)

Fichiers avec plusieurs colonnes

Nous avons vu commentfabriquer une source de donnée simple, mais il est possible d'avoir un fichier tableur avec de nombreuses colonnes. Pour l'exploiter il suffit d'ajouter des noms de clés pour les colonnes, au lieu d'avoir simplement :

id, text

On pourra avoir :

id, text, adresse, nom, prenom

Si le CSV est relié à un champ de formulaire ayant par exemple pour identifiant « valeur », {{form_var_valeur}} va contenir une cellule de la colonne « text » et les autres cellules pour cette même ligne seront disponibles dans les variables {{form_var_valeur_nom}}, {{form_var_valeur_prenom}} et {{form_var_valeur_adresse}} ; {{form_var_valeur_raw}} contiendra une cellule de la colonne « id ».

Interrogation directe

Filtres simples

En admettant que nous avons créé un connecteur CSV dont l'identifiant est « musees », le fichier est alors interrogeable directement en utilisant les URL ci dessous :

{{passerelle_url}}csvdatasource/musees/data

Retourne toutes les lignes du fichier.

{{passerelle_url}}csvdatasource/musees/data?q=abc

Retourne les lignes contenant « abc » (ou « ABC ») dans la colonne « text ».

Construction de requêtes

Lorsqu'on n'arrive pas à obtenir l'information désirée avec ce type d'interrogation directe, il est possible de construire des requêtes dont l'objectif est, en particulier, de pouvoir déplacer le focus sur une colonne particulière et de lui appliquer des traitements comme le filtrage, le dédoublonnage ou le tri.

Pour cela, lorsqu'on est sur la page d'accueil du connecteur, il faut cliquer sur « Nouvelle requête », lui donner un nom, une description et l'enregistrer.

Anatomie d'une requête

Les requêtes sont paramétrées à l'aide d'expressions Python, chaque champ de la requête accepte une liste d'expressions séparées par des sauts de ligne.

Les variables accessibles dans ces expressions sont nommées en fonction des noms de colonne définies dans le connecteur au fichier tableur. Si par exemple une colonne se nomme « adresse » vous pourrez utiliser la variable « adresse » dans vos expressions, elle contiendra la chaîne de caractère située dans la colonne « adresse ».

Une requête va permettre d'envoyer une valeur particulière pour un paramètre passé à l'URL de la requête. Si vous ajoutez un filtre (voir plus bas)commune == query['commune']par exemple, vous pourrez d'ajouter?commune=CASSISà l'URL, pour obtenir uniquement les lignes du CSV pour lesquelles la valeur de la commune est « CASSIS ».

Si notre connecteur a pour identifiantliste-ecole, et notre requête d'exemplecommune, les écoles de CASSIS seront accessibles grâces à l'URL :

{{passerelle_url}}csvdatasource/liste-ecole/query/commune/?commune=CASSIS

Attention, par défaut lorsqu'un filtre est construit, le paramètre devient obligatoire et s'il n'est pas envoyé dans l'URL, l'expression provoquera une erreur. Pour rendre un paramètre optionnel on utilisera la sous-expression « query.get('commune') » qui renverra une valeur nulle en cas d'absence de ce paramètre. On testera la présence d'un paramètre avec la sous expression « 'nom_du_parametre' in query ».

Paramétrage d'une requête

Les différents paramétrages sont :

* les filtrages : des expressions booléennes (Oui/Non) définissant si une ligne du tableau doit être conservée ou pas ;
* les tris : des expressions de type quelconque (numérique ou chaîne de caractère). Les lignes seront triées par l'ordre lexicographique de la valeur de ces expressions, c'est à dire que l'on va d'abord trier par la valeur de la première expression, puis, en cas d'égalité, par la valeur de la seconde expression (puis de la troisième, et ainsi de suite) ;
* les dédoublonnements : une liste d'expressions définissant une clé à une ou plusieurs valeurs, en cas d'égalité dans les clés, seule la première ligne du tableau ayant cette valeur de clé est conservée,
* les projections : les projections sont composées d'un nom puis d'une expression Python séparée par un caractère deux points (« : »), elles permettent de renommer, transformer et restreindre les valeurs d'origine du tableau.

Pour aider à la compréhension de ces différents paramètres nous allons partir de l'exemple d'une liste d'horaire pour un réseau de transport public. On supposera un fichier tabulé donnant les horaires, les lignes et les arrêts. Les horaires seront donnés sous la forme d'une chaîne de caractère à 4 chiffres comme « 0840 » facilitant ainsi les comparaisons.

horaire | ligne | arret
-----------------------
0840 | A | Avenue du Revestel
0900 | A | Faculté
0930 | A | Opéra
0940 | A | Avenue du Revestel
1000 | C | Les Goudes
0940 | B | Rue du Château
1000 | B | Hotel de ville

Nous supposerons que le connecteur créé pour ce fichier se nomme transport, les requêtes que nous allons définir seront donc accessibles via :{{passerelle_url}}/csvdatasource/transport/nom-de-la-requête/

Dans un premier temps on souhaitera construire une requête renvoyant la liste des lignes. Pour cela on utilisera le dédoublonnement (pour ne pas avoir de répétition) mais aussi les projections pour obtenir des colonnes nommées « id » et « text » (obligatoires).

Cette requête renverra le document JSON suivant sur un GET à l'URL{{passerelle_url}}/csvdatasource/transport/query/lignes/ :

[ 
  { "id": "A", "text": "A" }, 
  { "id": "B", "text": "B" }, 
  { "id": "C", "text": "C"} 
]

La prochaine requête que nous pourrions vouloir est la liste des arrêts pour une ligne donnée, dans l'ordre des horaires :

Cette requête renverra le document JSON suivant sur un GET à l'URL{{passerelle_url}}csvdatasource/transport/query/arret/?ligne=A :

[ 
  { "id": "Avenue du Revestel", "text": "Avenue du Revestel" }, 
  { "id": "Faculté", "text": "Faculté" },
  { "id": "Opéra", "text": "Opéra" }
]

Pour obtenir la liste des horaires pour un arrêt donné d'une ligne, on passera ligne et arrêt en paramètre, on filtrera selon ces deux paramètres avec :

ligne == query['ligne']
arret == query['arret']

on triera selon la colonne « horaire » et on projetera la même colonne « horaire » sous les noms « id » et « text ».

Structure du format retour

Par défaut les requêtes retournent une liste de dictionnaires (ou tableaux JSON) dans un document JSON ayant cette forme :

{ 
  "err": 0, 
  "data": [ 
    {..ŕesultat 1..}, 
    {..résultat 2..}
    ...
  ]
}

Cette structure/format est nommé « Dictionnaire ».

Mais d'autres formats sont possibles :

* tableau: le champ « data » contient un tableau dont chaque ligne est un tableau des valeurs ordonnées en fonction des projections définies ou des noms des colonnes,
* tuples: le champ « data » contient un tableau dont chaque ligne est un tableau de paires dont le premier élément est le nom d'une colonne ou d'une projection et le second élément sa valeur, ex.: [ ["id", 1], ["text": "valeur 1"] ],
* une seule ligne: ce format suppose que la requête ne peut renvoyer qu'une seule ligne, dans ce cas le dictionnaire de cette ligne est directement renvoyé dans le champ « data »; si la condition n'est pas remplie une erreur sera levée,
* une seule valeur: ce format suppose qu'en plus de ne renvoyer qu'une seule ligne, cette ligne contient une colonne unique, dans ce cas la valeur de la colonne sera renvoyée dans le champ « data »; si la condition n'est pas remplie une erreur sera levée.

* Studio
* Les tutos

Pour activer le multilinguisme dans Publik :

* Aller dans Paramètres > Langue
* Cocher la case Activer la prise en charge du multilinguisme

La prise en charge du multilinguisme concerne uniquementles formulaires, les fiches, les workflows.

Les éléments de base, tels que les libellés des boutons "Suivant" et "Précédent", sont automatiquement traduits en anglais et en allemand.

Les libellés des champs et des listes ne sont pas traduits automatiquement et doivent être ajoutés manuellement.

Pour traduire un champ d'une fiche, il faut l'ajouter dans le gabarit du modèle de fiche avec le filtre|translate.

Dans les workflows, certaines actions, comme l'envoi d'un courriel, utilisent la langue associée à la demande lors de la saisie. Cela permet d'envoyer un courriel unique pour un changement de statut, par exemple :

* en français (langue par défaut) pour l'agent
* en anglais pour l'utilisateur, à condition qu'une traduction en anglais ait été saisie

La langue du formulaire suit celle configurée dans le navigateur de l'utilisateur. Cependant, si une URL avec un préfixe de langue est utilisée (ex./en/ou/de/), elle a la priorité. De plus, la langue sélectionnée par l'utilisateur est enregistrée avec la demande.

Pour afficher un formulaire traduit, il faut utiliser une URL contenant un préfixe de langue.Exemple :{{eservices_url }}/en/IDENTIFIANT_CATEGORIE/IDENTIFIANT_FORMULAIRE/L'ajout de/en/permet d'afficher la version anglaise du formulaire.

# Protection dite « pot de miel »

Protection dite « pot de miel »

Tous les formulaires sont protégés par un mécanisme appelé « pot de miel ». Il s'agit d'un champ caché ajouté à chaque formulaire. Ce champ ne sera jamais rempli par un humain, mais un robot de spam, qui remplit automatiquement tous les champs d'un formulaire, y inscrira une valeur. Lorsqu'une soumission est reçue avec ce champ rempli, elle est immédiatement identifiée comme étant du spam et rejetée.

Ce type de protection est largement utilisé sur Internet et permet d'éliminer environ 99% des spams sans impacter l'expérience utilisateur.

* Studio

# Documenter dans Studio

Documenter dans Studio

Publik est doté d'une fonctionnalité de documentation au sein même des formulaires, modèles de fiches, workflows, etc.

Pour documenter, il faut cliquer sur l'icônequi affiche unz zone de texte libre qui permet de mettre en forme du texte (différent niveau de titre, liste à puce, lien, etc.).

Exemple de documentation d'un workflow

Il est possible de documenter la page d'accueil du workflow, les statuts, les actions, les variables du workflow, les actions globales, les données de traitement, etc.

La documentation est intégrée à l'inspecteur de workflow. Le texte apparaît dans un encadré précédé de l'icône.

* Studio

# Notification au demandeur

Notification au demandeur

Cette action permet d'afficher un message à l'usager via un espace dédié dans le CMS. Le message ainsi publié sera mis en avant depuis le tableau de bord du demandeur.

Si le mode PWA est activé avec l'option « Activer la possibilité de s’abonner à des notifications « Push » », l'action de notification envoie également unenotification Pushen même temps qu'elle l'affiche sur le tableau de bord de l'usager.

Édition

Les étapes d'édition de l'action « Notification au demandeur »  sont les suivantes :

* Saisissez un « Titre de notification ».
* Saisissez un « Corps de message ». Comme pour les courriels, celui-ci est un gabarit qui peut contenir des variables. Il s'agit d'un texte brut qui n'a pas vocation à recevoir de formatage particulier.
* Possibilité de spécifier une URL spécifique pour permettre l'utilisation de cette action avec des fiches auxquelles la personne notifiée n'a pas accès.

Optionnellement vous pouvez ajouter une « Origine » (généralement le nom de l'organisme ou du service expéditeur) et une condition si l'envoi de cette alerte doit être conditionné.

Publication des alertes

Pour afficher les alertes à l'usager, il faut ajouter une cellule « Notifications à l'usager » dans une page du portail citoyen. Si cette page apparaît dans le menu de navigation, une chiffre indiquera à l'usager son nombre de notifications (à proximité du nom de la page).

Les alertes poussées vers l'usager restent publiées pendant 3 jours et sont grisées une fois que l'usager en a pris connaissance.

Exemple de mise en avant depuis la page d'accueil d'un portail :

* Studio
* Les tutos

# Évènements

Évènements

Pour configurer un agenda de type « évènements », il faut y ajouter les évènements adéquats, en précisant la date, l'heure et le nombre de places disponibles (champs obligatoires). Parmi les champs optionnels, le libellé sera utile pour permettre aux usagers de choisir entre « Multisport, du 4 au 8 juillet » ou « Natation, du 7 et 8 juillet » ; d'autres champs optionnels sont possibles : nombre de places possibles en liste d'attente, tarif, description...

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.

Paramétrage de l'agenda

Lorsque l'agenda est créé, un certain nombre de paramètres sont exposés sur la page d'accueil et peuvent être changés en cliquant sur le bouton « configurer » en face du paramètre concerné.

Rappels

Des rappels peuvent être configurés au niveau de l'agenda, indépendamment de ce qui sera fabriqué dans le workflow. Ils sont désactivés par défaut.

Les rappels se font par courriel et/ou par SMS (si une plate-forme d'envoi de SMS est raccordée) et ils contiennent par défaut

les informations de base telles que le lieu, la date et l’heure. Ce qui peut être configuré :

* Le moment du rappel (1 à 3 jours avant)
* Le canal ou les canaux utilisés (SMS et/ou courriel)
* Un texte personnalisé qui vient s'ajouter au texte de base (attention à ne pas dépasser 160 caractères pour les SMS).

Pour que ces rappels soient effectifs, l'appel webservice de réservation dans le workflow, doit contenir les paramètres

user_email

et/ou

user_phone_number

contenant respectivement le courriel / le numéro de mobile de l'usager, ainsi que

form_url

contenant l'URL de la demande (typiquement

{{ form_url }}

).

Note : pour éviter les rappels inutiles, ceux-ci ne sont envoyés que pour les réservations effectuées depuis plus de 12 heures.

Permissions

La configuration des permissions permet d'associer à l'agenda :

* un rôle de visualisation pour l'accès à la page récapitulative des évènements et aux écrans de pointage,
* une rôle d'édition pour le paramétrage de l'agenda (gestion des évènements, périodes d'exclusion, rappels, délais de réservation...)

Délais de réservation

Par défaut, les agendas sont configurés pour permettre l'inscription au plus tard la veille de l'évènement et jusqu'à 56 jours ouvrés avant. Mais il est donc possible d'indiquer des valeurs différentes en fonction de vos besoins en définissant un nombre de jours minimal (borne incluse) et un nombre de jours maximal (borne exclue). Il faut entendre ces journées en termes calendaires (de 00h00 à 23h59).

Une option spécifique permet d'indiquer que le nombre de jours minimal est calculé en jour ouvrés (c'est toujours le cas s'agissant du nombre de jour maximal).

* Un délai minimal réglé à 0 permet une inscription le jour même tant que l'évènement n'a pas commencé
* Un délai minimal réglé à 1 permet une réservation jusqu'à 23h59 la veille de l'évènement.

Paramétrage d'un évènement

Chaque évènement de l'agenda peut être paramétré de façon indépendantes concernant :

* Le libellé
* La date et l'heure
* La récurrence
* La durée
* Le nombre de place
* Le nombre de place sur liste d'attente
* Le moment de la publication
* La description
* Le tarif
* l'URL

Options

Adresse de la démarche de réservation

L'ajout de l'URL du formulaire fait apparaître le lien « Démarche de réservation » dans le menu kebab d'un événement en back-office.Ce champ permet par exemple d'ajouter un lien vers la saisie en back-office :{{ eservices_url }}backoffice/submission/IDENTIFIANT-DU-FORMULAIRE/

Exposer les évènements dans un formulaire

Les évènements peuvent être exposés dans un champ listeconfiguré pour utiliser une source de donnée.

Quelques minutes après la création d'un agenda évènements (ou après avoir cliqué sur « Actualiser les agendas dans l'écran des sources de données »), une source de donnée est disponible dans la liste des sources de données « Agendas ». Le champ présentera alors sous forme de liste déroulante le libellé des évènements.

À la place de la source de donnée disponible automatiquement, il est possible d'utiliser une URL JSON comme source de données du champ liste  avec le paramètremin_placespour ne récupérer que les évènements qui ont suffisamment de places disponibles par rapport à un nombre de places souhaitées. Par exemple, si l'on a un champ « nombre de personnes » qui a pour identifiantnombre_personnes:

{{agendas_url}}api/agenda/SLUG-AGENDA/datetimes/?min_places={{form_var_nombre_personnes}}

Lorsque l'on paramètre l'agenda, on peut choisir d'afficher d'autres informations dans la liste, en allant dans l'onglet « Paramètres d'affichage » pour configurer le gabarit d'affichage. Les variables suivantes sont utilisables dans le gabarit :

* {{ event.label }} : le libellé
* {{ event.start_datetime }} : date et heure de début
* {{ event.places }} :  le nombre total de places
* {{ event.remaining_places }} : le nombre de places restantes
* {{ event.duration }} : la  durée
* {{ event.pricing }} : le tarif

Grâce au champ liste créé, il est également possible afficher dans un champs commentaire (ou d'utiliser ultérieurement dans le le workflow), des informations comparables. Si le champ liste a pour identifiant « event » :

Attention: Pour que les informations listées ci-dessous apparaissent correctement dans un champ commentaire lorsque l'évènement choisi dans le formulaire change, le nom de la variable du champ liste doit être indiqué dans le champ commentaire,{{ form_var_event_places_available }} seulpar exemple ne sera pas mis à jour dynamiquement, il faudra mettre :

{% if form_var_event %}

{{ form_var_event_places_available }}

{% endif %}

* Le libellé : {{ form_var_event_label }}
* La durée : {{ form_var_event_duration }}
* Le nombre de place restantes : {{ form_var_event_places_available }}
* L'info complet / pas complet : {{ form_var_event_places_full }}
* Places disponibles sur liste d'attente : {{ form_var_event_places_waiting_list_available }}
* La description : {{ form_var_event_description }}
* Le tarif : {{ form_var_event_pricing }}
* l'URL : {{ form_var_event_url }}

Lorsque l'usager aura choisi un évènement et validé le formulaire, il est nécessaire que le workflow soit correctement configuré pourenregistrer l'inscription dans l'agenda.

Évènements récurrents

Les agendas évènements peuvent accueillir des évènements récurrents, sorte d'hybridation entre les rendez-vous et les évènements. La récurrence se configure dans les options de l'évènement et offre la possibilité de définir des évènements répétés tous les jours, ou tous les jours ouvrés, ou toutes les semaines, ou toutes les deux semaines.

Il est  possible de pointer un ou plusieurs jours de la semaine où les répétitions doivent avoir lieu. cela permettra de créer facilement, par exemple, un cours de yoga tous les lundis de 9h à 10h et tous les mercredis de 14h à 15h.

Sur la page de

paramétrage de l'Agenda

(et pas de l'évènement), il est possible de définir des exceptions pour les évènements récurrents, en cliquant sur « Ajouter une exception » sous « Exceptions aux récurrences »  c'est particulièrement utile pour les jours fériés et les périodes de vacances.

Pointage

Il est possible de pointer les personnes qui se sont inscrites à un évènement et étaient présentes ou absentes.

Consultez la page

[Pointage des inscriptions à un évènement](https://doc-publik.entrouvert.com/admin-fonctionnel/prises-de-rendez-vous/evenements/pointage-des-inscriptions/)

.

Agendas

* Studio
* Les tutos

# Rendez-vous

Rendez-vous

Pour configurer un agenda de type « rendez-vous », il faut définir les plages horaires d'ouverture (par exemple, « les lundis de 9 à 17 heures et le mercredi de 14 à 18 heures ») et un ou plusieurs types de rendez-vous ayant chacun une durée définie.

Il est possible de définir :

* des plages horaires régulières pour, par exemple, noter une ouverture tous les premiers lundis du mois ou le deuxième et le quatrième mercredis du mois.
* une plage horaire unique à une date donnée

L'agenda va aussi vous permettre de définir un délai minimal et maximal de réservation, des rappels par SMS et/ou courriel, et des permissions en visualisation et en gestion.

Types de Rendez-vous

Les types de rendez-vous comprennent un libellé et une durée, c'est tout. Ils vont permettre d'exposer des créneaux différents et adaptés pour des personnes qui viendraient par exemple pour faire un unique passeport ou pour d'autres qui viendrait en faire 4. Lorsque vous avez défini plusieurs type de rendez-vous différents dans un agenda, il peut être utile d'afficher ces types (rendez-vous pour 1 personne, rendez-vous famille...) dans le formulaire pour permettre à l'usager de choisir le type qui l'intéresse.

Les types de rendez-vous peuvent être exposés dans un champ listeconfiguré pour utiliser une source de donnée. Quelques minutes après la création d'un agenda rendez-vous, une source de donnée « Nom de l'agenda - Type de rendez-vous » est en effet disponible pour cela.

Vous donnez ainsi la possibilité à l'usager de choisir parmi les type de rendez-vous existants. Vous pouvez lier ce choix au créneaux qui seront affichés dans la liste exposant les créneaux en procédant de la sorte :

* Donnez l'identifiant « meeting_type » au champ liste des types de rendez-vous,
* Configurez le champ liste exposant les créneaux pour qu'il utilise comme source de données« Nom de l'agenda - Créneaux du type form_var_meeting_type_raw »

Si vous créez un type de rendez-vous de 30 min sur une plage horaire de 8h00 à 12h00, vous aurez 8 créneaux disponibles, le dernier affiché étant celui de 11h30 (il n'y a pas de créneau disponible à 12h00 qui est l'heure de fermeture).

Guichets

Il est possible de créer plusieurs guichets, permettant ainsi de multiplier le nombre de places disponibles pour un même créneau. Pour créer un nouveau guichet, il suffit de cliquer sur « Nouveau guichet » et de choisir le nom du nouveau guichet.

Les rendez-vous seront pris sur un guichet ou l'autre, indifféremment. Dans la vue calendaire, on verra quel est le guichet concerné par le rendez-vous.

Gestion globale

Par défaut, l'agenda est créé en gestion globale des guichets, cela signifie que la configuration des plages horaires d'ouverture et des exceptions est commune à tous les guichets

Gestion unitaire

Mais il est possible de basculer en « Gestion unitaire des guichets » dans le menu burger. Chaque guichet peut alors être configuré indépendamment des autres, avec ses propres plages horaires et ses propres exceptions.

Les types de rendez-vous, les rappels, les délais de réservations et les permissions sont communs à tous les guichets. Pour mettre en place quelque chose de différent à ce niveau là, vous avez besoin d'un nouvel agenda et pas d'un nouveau guichet.

Vue calendaire des rendez-vous pris

Les agents ayant le rôle requis, accèdent à la vue calendaire des rendez-vous pris. Cette vue peut être :

* quotidienne pour exposer le détail desrendez-vousde la journée,
* hebdomadaire pour avoir une vue synthétique de la semaine en cours,
* mensuelle pour avoir une vue plus globale desrendez-vouspris, et voir le détail desrendez-vousau survol de la souris.

Lorsque l'agenda est créé, un certain nombre de paramètres sont exposés dans des onglets dédiés.

Une ressource (une salle, une voiture, un vidéoprojecteur...) peut être associée à un ou plusieurs agenda(s), l'objectif étant de permettre la réservation de cette ressource pour une période donnée.

Il faut commencer par créer la ressource concernée (depuis le menu burger de la page d'accueil des agendas) avant de pouvoir l'associer à l'agenda.

Une fois l'association réalisée, les périodes de disponibilités de la ressource peuvent être affichées dans un formulaire en utilisant comme source d'un champ liste une URL du type

/api/agenda/SLUG-DE-LAGENDA/meetings/SLUG-DU-TYPE-DE-RDV/datetimes/?resources=MA-SALLE

Une source de donnée est automatiquement créé en même temps qu'un agenda. Il est possible de la dupliquer pour créer une source de donnée dédiée à une ressource en ajoutant le paramètre?resources=MA-SALLE.

Il est possible d'afficher les périodes de disponibilités pour plusieurs ressources, en les séparant par des virgules :

?resources=MA-SALLE1,MA-SALLE2

Paramètres d'affichage

Dans l'onglet « Paramètres d'affichage » de l'écran de configuration de l'agenda, il est possible de définir ce que l'on souhaite afficher dans la vue calendaire pour chaque rendez-vous. Cela prend la forme d'un gabarit dans lequel on peut utiliser un certain nombre de variables, par exemple :

* {{ booking.label }} : l'intitulé du rendez-vous
* {{ booking.user_name }} : le nom de l'utilisateur
* {{ booking.extra_data.QUELQUECHOSE }} : une donnée transmise lors de la réservation via le paramètre extra_data
* {{booking.event.desk }} et {{booking.event.desk.slug }} : Le libellé et le slug du guichet sur lequel la réservation a eu lieu

Rappels de réservation

Chaque agenda permet de configurer un rappel (et un seul) pour chaque rendez-vous/évènement, indépendamment de ce qui sera fabriqué dans le workflow. Le rappel est désactivé par défaut.

les informations de base telles que le lieu, la date et l’heure. Le texte de base ne peut être modifié. Ce qui peut être configuré :

* Le moment du rappel (entre 1 et 5 jours avant)

et/ou

contenant respectivement le courriel / le numéro de mobile de l'usager, ainsi que l'URL de la demande (classiquement

).

Les

[variables utilisées pour l'affichage](https://doc-publik.entrouvert.com/admin-fonctionnel/prises-de-rendez-vous/rendez-vous/#affichage-des-rdv)

sont utilisables pour les rappels.

Si le texte par défaut, non modifiable, ne correspond pas à ce qui est souhaité pour le rappel, il est toujours possible de paramétrer une action SMS ou courriel à la place.

* un rôle de visualisation pour l'accès à lavue calendaire des rendez-vous pris,
* un rôle d'édition pour le paramétrage de l'agenda (périodes horaires, types derendez-vous, périodes d'exclusion, rappels, délais de réservation...)

Par défaut, les agendas sont configurés pour permettre la prise de rendez-vous au plus tard la veille du rendez-vous et jusqu'à 56 jours avant. Mais il est donc possible d'indiquer des valeurs différentes en fonction de vos besoins en définissant un nombre de jours minimal (borne incluse) et un nombre de jours maximal (borne exclue). Il faut entendre ces journées en termes calendaires (de 00h00 à 23h59).

* Un délai minimal réglé à 0 permet une réservation le jour même
* Un délai minimal réglé à 1 interdit les réservations sur le jour même et permet une réservation le lendemain entre 00h00 et 23h59

Exposer les créneaux horaires dans un formulaire

Les créneaux disponibles peuvent être exposés dans un champ listeconfiguré pour utiliser une source de donnée. Quelques minutes après la création d'un agenda rendez-vous, une source de donnée « Agendas - nom du type de rendez-vous » est en effet disponible pour chaque type de rendez-vous et il suffit de la sélectionner dans la liste des sources de données « Agendas ». Le champ listeconfiguré en mode « Horaires »présentera alors sous forme calendaire l'ensemble des créneaux disponibles.

L'ancienne méthode, était de sélectionner « URL du JSON » dans la liste des sources de données, et d'indiquer :

{{agendas_url}}api/agenda/AGENDA/meetings/TYPE-DE-RDV/datetimes/

Indépendamment du délai de réservation configuré au niveau de l'agenda, on peut choisir de n'afficher les créneaux qu'à partir d'une certaine date. Le champ « Date d'alignement » disponible quand on sélectionne le mode d'affichage « Horaires » pour la liste, accepte une date pouvantprovenir d'un gabarit.

Dans les « Paramètres supplémentaires » du champ liste, le réglage « Afficher les éléments désactivés » (désactivé par défaut) permet d'afficher pour information, en grisé, les créneaux déjà réservés.

Lorsque l'usager aura choisi un créneau et validé le formulaire, il est nécessaire que le workflow soit correctement configuré pourenregistrer la réservation dans l'agenda.

Changer les horaires : exceptions et calendriers d'indisponibilités

Exceptions

Les agendas définissent, de façon récurrente, les horaires d'ouverture pour une semaine type mais il est possible de définir pour chaque guichet (ou globalement pour l'agenda) des périodes pendant lesquelles les horaires normaux ne s'appliquent pas : les « exceptions ». Il peut y avoir des exceptions parce qu'un jour est férié, parce qu'une personne est absente ou simplement parce que les horaires d'ouverture changent durant une période donnée.

Les exceptions permettent de définir une date/heure de début et une date/heure de fin, les créneaux indiqués sont alors indisponibles entre les bornes indiquées. Dans l'écran d'accueil de l'agenda, il est possible de d'« ajouter une exception » (au niveau des périodes horaires) :

* manuellement en saisissant le début et la fin de chaque exception,
* ou, après avoir cliqué sur l’icône clé, en face de « Exceptions », via un fichier (.ics) qui pourra être ajouté ponctuellement ou importé automatiquement toutes les heures si ce fichier est accessible depuis une URL (nota : seules les exceptions dans les 600 jours à venir sont importées).

Périodes d'indisponibilité

Chaque guichet dispose d'un calendrier d'indisponibilité « Jours fériés » prédéfini, qui peut être désactivé si nécessaire.

Par défaut, les agendas sont créés avec des périodes d'indisponibilité qui correspondent aux jours fériés français. Mais il est possible,

depuis la page d'accueil des agendas

, d'ajouter d'autres « Calendriers d'indisponibilité » qui seront autant de périodes pendant lesquelles aucune prise de rendez-vous n'est possible.

Une fois que le calendrier d'indisponibilité est créé, il est possible de l'associer à un agenda de type rendez-vous en allant

dans la page de paramétrage de ce dernier

et en cliquant sur l'icône de la petite clé en face de « Exceptions ». En cas de conflit avec des réservations existantes, un message d'alerte est affiché.

Après configuration, le calendrier d'indisponibilité est exposé dans la liste des exceptions de l'agenda concerné.

Le calendrier d'indisponibilité peut être alimenté par un fichier ICS.

Mettre des couleurs aux rendez-vous

Il est possible d'afficher des couleurs sur les créneaux réservés dans un agenda, ces couleurs sont sélectionnées automatiquement, elles ne sont pas paramétrables. Par défaut, les rendez-vous sont en bleu.

Dans l'appel de réservation, dans le corps de la requête, il faut passer le nouveau paramètre « use_color_for ». Sa valeur doit être une chaîne de caractères et entraînera l'attribution d'une couleur. Si le libellé est inconnu, une couleur de la palette est attribuée, sinon on réutilise la couleur déjà attribuée pour cette chaîne de caractères.

Il y a 8 couleurs en tout, le neuvième libellé reprend la première couleur.

Une légende s'affiche en bas des vues calendriers, elle indique la correspondance entre libellés et couleurs présentes sur la vue courante.

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 son logiciel de messagerie n'aura qu'à cliquer sur le fichier .ics pour mettre le rendez-vous dans son agenda. Pour suivre le tutoriel,c'est par là.

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. C'est la méthode recommandée.

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

Ces logiciels accéderont à une adresse du type :

{{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 donc nécessaire de disposer d'une clé et d'un identifiant API pour construire l'adresse en question. Pour cela, vous devez créer un rôle dédié, par exemple « Accès API » (qui ne contiendra aucun utilisateur).Puis, dans l'entrée Paramètres du menu latéral, vous pourrez configurer un nouvel accès aux API en indiquant le rôle « Accès API ». Vous avez désormais un identifiant et une clé d'accès.

Mais il faut encore que ce rôle ait accès à la démarche, pour cela il doit être associé à une fonction dans le workflow (tous les rôles associés à une fonction ont alors accès à la démarche concernée). Dans le workflow, il faut ajouter une fonction « Accès ics » (par exemple), et l'associer au rôle « Accès API » (dans le formulaire ou dans le workflow).

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.

Agendas

* Studio
* Les tutos

# Agendas virtuels

Agendas virtuels

L'agenda virtuel est un type d'agenda particulier quiagrège des agendas de type rendez-vous(uniquement, pas d'agendas virtuels d'évènements possibles) : les créneaux exposés par l'agenda virtuel seront la somme de tous les créneaux disponibles dans les agendas inclus.

L'agenda virtuel se crée comme n'importe quel autre agenda en cliquant sur «Nouveau». Pour ajouter un agenda rendez-vous à l'agenda virtuel, il faut cliquer sur « Paramétrage » puis sur « Inclure un agenda ».

Exemples de cas d'usage d'un agenda virtuel :

* Proposer les premiers créneaux disponibles parmi l’ensemble des agendas inclus dans l'agenda virtuel : si vous avez plusieurs agendas gérant chacun les rendez-vous d'un(e) assistant(e) sociale, passer par un agenda virtuel qui inclut tous ces agendas, permettra à l'usager de prendre rendez-vous avec n'importe quel assistant(e) sociale, sur le créneau qui l'arrange.
* Réserver des créneaux uniquement pour enregistrement par les agents. Sur un agenda « rendez-vous état civil », vous pouvez créer un agenda virtuel qui inclut cet agenda et y définir des périodes d'exclusion ; si vous exposez l'agenda initial « rendez-vous état civil » aux agents, ceux-ci auront accès à l'intégralité des créneaux et en exposant l'agenda virtuel dans un formulaire en front office i.e. pour les usagers, ceux-ci ne pourront pas réserver sur les créneaux dans les périodes d'exclusion.

Les agendas agrégés doivent tous avoir les mêmes types de rendez-vous i.e. même durée, même identifiant et même libellé.

Agendas

* Studio
* Les tutos

# Enregistrer, modifier, annuler dans un agenda

Enregistrer, modifier, annuler dans un agenda

C'est dans le workflow que l'on va pouvoir procéder à l'enregistrement dans un agenda, pour prendre, annuler ou encore déplacer une ou plusieurs réservations, grâce à uneaction webservice.

Enregistrer un rendez-vous ou une inscription

L'action webservice doit être configurée en POST. L'URL à utiliser dans cet appel, en considérant que le champ présentant le choix avait comme identifiant « EVENT », sera{{ form_var_IDENTIFIANT-CHAMP-EVENT_api_fillslot_url }}.

L'appel webservice doit inclure les « Données à envoyer dans le corps de la requête » suivantes :

* labelpour le libellé qui sera affiché dans les plages réservées dans les agendas, vue back-office (par exemple pourrait être{{ form_name }},
* user_first_nameetuser_last_namepour le prénom et le nom de l'usager, si défini viendra s'afficher dans la plage réservée à la suite delabel,
* backoffice_urlpour la demande vers laquelle créer un lien activé sur le libellé précédent (usuellement doit être{{ form_url_backoffice }}),
* user_display_labelpour le libellé qui sera présenté à l'usager (par exemple « Rendez-vous passeport »). Ces deux dernières données ne sont utilisées que dans le cas de génération d'un fichier ics (cf. letutoriel dédié).
* user_emailpour l’adresse électronique de l’usager, nécessaire pour que les rappels par email fonctionnent.
* user_phone_numberpour le numéro de téléphone mobile de l’usager, nécessaire pour que les rappels par SMS fonctionnent.
* form_url, optionnel, et permet de passer l'adresse de la demande, ce qui ajoutera un bouton "Modifier ou annuler le rendez-vous" dans les courriels de rappel.
* cancel_callback_url, optionnel mais à utiliser pour permettrel'annulation depuis l'agenda.

Il est possible d'ajouter n'importe quel couple donnée/valeur dans l'appel webservice. La donnée pourra être utilisée ensuite pour configurer un filtre dans l'écran de pointage. Par exemple, si j'utilise regime: "végétarien", je pourrais dans les paramètres de l'écran de pointage indiquer

regime

comme filtre. Cela permettra d'avoir dans l'écran de pointage un bouton radio pour chaque valeur associée à la donnée regime (Végétarien, Allergique, etc.). Ces boutons radio permettent de n'afficher que les réservations concernées.

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

Attribuer un identifiant à l'appel webservice, par exemple « reservation », permettra d'utiliser les variables{{form_workflow_data_reservation_response_*}}qui contiennent de nombreuses informations utiles (regardezla vue inspect d'une demandepour les voir toutes).

Annuler un rendez-vous ou une inscription

l'action webservice permettant d'annuler un enregistrement dans l'agenda se configure en POST avec :

* URL: {{form_workflow_data_reservation_response_api_cancel_url }}

L'annulation ainsi configurée pourra être déclenchée par l'usager ou l'agent en fonction des choix faits dans le workflow, voir en exemple le workflow «

[Prise de rendez-vous](https://catalogue.publik.love/workflows/#rendez-vous)

» sur le catalogue des démarches.

On peut également permettre aux agents d'annuler un rendez-vous depuis l'agenda, mais cela nécessite uneconfiguration différenteet plus poussée du workflow.

Modifier un rendez-vous ou une inscription

La modification d'un enregistrement c'est en réalité une action d'annulation de l'enregistrement existant et une action de création d'un nouvel enregistrement. Il est tout à fait possible de faire cela avec 2 actions webservices séparés en utilisant les deux appels vu précédemment.

Mais il est possible d'utiliser un seul appel pour faciliter les choses : il fera à la fois l'annulation et le nouvel enregistrement comme sur le workflow «Prise de rendez-vous» sur le catalogue. Dans notre exemple,nous avons stocké l'identifiant du rendez-vous existant dans une donnée de traitement {{ form_var_id_rdv }}, et nous exposons la possibilité de changer l'enregistrement via une action formulaire dans le workflow qui nous donne une variable{{form_workflow_form_IDENTIFIANT-FORMULAIRE_var_IDENTIFIANT-CHAMP-EVENT_api_fillslot_url }}.

L'action webservice est utilisée à la fois pour faire le premier enregistrement et le modifier. Elle se configure en post comme suit :

* URL : {% firstofform_workflow_form_IDENTIFIANT-FORMULAIRE_var_IDENTIFIANT-CHAMP-EVENT_api_fillslot_urlform_var_IDENTIFIANT-CHAMP-EVENT_api_fillslot_url%}
* backoffice_url : {{form_url_backoffice|safe}}
* cancel_booking_id : {{form_var_id_rdv|default:""}}
* label : {{form_name|safe}}
* user_name : {{form_user_display_name|safe}}

Unparamétrage plus avancé du workflowest possible pour faire plusieurs d'inscriptions d'un coup, gérer les erreurs, annuler les rendez-vous directement depuis l'agenda ou encore gérer une liste d'attente.

Agendas

* Studio
* Les tutos

# Paramétrage avancé des workflows pour les agendas

Paramétrage avancé des workflows pour les agendas

Pour une utilisation avancée des agendas, il peut être utile deconsulter 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 fairevia 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.

La méthode recommandée pour cela est :

* ajouter uneaction 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 «Rôles requis pour déclencher via un appel HTTP» il faut sélectionner « Appels signés aux API » pour que cet appel externe ne soit pas ouvert à tous.
* 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 ».

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 :

* 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/
* Une action globale Présence, avec un déclencheur « Appel externe », ayant pour identifiant presence. Dans «Rôles requis pour déclencher via un appel HTTP» il faut sélectionner « Appels signés aux API » pour que cet appel externe ne soit pas ouvert à tous.
* Une action globale Absence, avec un déclencheur « Appel externe », ayant pour identifiant absence. Dans «Rôles requis pour déclencher via un appel HTTP» 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'attributin_waiting_listest 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ùreservationest 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 appelPOSTdoit incluredans le corps de la requête, les données envoyées habituellement dans le cas d'uneréservation simple, et en plus les données suivantes  :

* slotspour les identifiants des évènements à réserver (usuellement {{form_var_event_raw}})
* user_external_idpour 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ètreslotsvide.

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 webserviceGETà/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_userqui vautmain-listpour les évènements pour lesquels l'usager est réellement inscrit, ouwaiting-listpour 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 unnouvel appel webservice POST identique à l'appel de réservationmais envoyant seulement une donnée « lock_code » (et rien d'autre) remplie par {{ session_hash_id }}. Donnons lui l'identifiant « preblocage ».
* Ajouter unecondition de sortie de pagesur 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 unesource de données personnaliséepour 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](https://doc-publik.entrouvert.com/admin-fonctionnel/les-tutos/pre-reservation-dun-rendez-vous-ou-dun-evenement/)

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

Agendas

* Studio
* Les tutos

# Éléments dépréciés

Éléments dépréciés

Publik est né en 2005.

Faire en sorte qu'une application aussi ancienne reste innovante sans souffrir de la  « dette technologique » qui affecte tant de logiciels utilisés dans l'administration publique, c'est un travail considérable.

Il s'accompagne nécessairement de la dépréciation, programmée et lente, d'un certain nombre d'éléments que nous listons ici.Dès qu'un élément est présent sur cette page, cela signifie qu'il est déprécié.Et ce même lorsque sa date de retrait n'est pas encore fixée.

Ces éléments fonctionnent encore, mais nous apportons peu d'attention à leur fonctionnement, il est donc conseillé de les remplacer dès à présent. La date d'échéance indique le moment auquel ils cesseront de fonctionner.

La page d'accueil de studio permet de voir les éléments dépréciés utilisés sur votre instance.

Élément déprécié | À remplacer par | Commentaire | Date d’annonce | Échéance
Fichiers CSV comme sources de données | Les fiches | Il est possible d'importer les CSV dans des modèles de fiches. Les fiches peuvent être plus facilement maintenues. | 11/04/2022 | 
Langage EZT | Gabarits Django | Il faut remplacer les [] par des {{}} et écrire les conditions sous la forme{% if ... %}xxxxx{% endif %} | 11/04/2022 | 30/06/2025
Modèles de document RTF | Modèles ODT | Il faut utiliser le format Open Document pour les modèles de l'action « Création de documents » | 11/04/2022 | 31/12/2024
URL JSONP | URL JSON | Cela nécessite de bien comprendre le fonctionnement de la source de donnée utilisée pour récupérer un élément précis ("id") et permettre d'effectuer une recherche ("q") | 11/04/2022 | 
JSON Data Store | Les fiches | Il est plus simple aujourd'hui de stocker/modifier/afficher l'information via les fiches que via ces stores préexistants. | 11/04/2022 | 
Fargo | Porte-document fait avec des fiches | Fargo est très peu utilisé. Nous le remplacerons par un porte-document basé sur les fiches. | 11/04/2022 | 31/12/2025
BiJoe | Statistiques faites avec Combo | L'interface de Bi-joe est complexe. Nous la remplacerons par celle plus simple de Combo qui devra couvrir les besoins courants à terme. | 11/04/2022 | 
Action de resoumission | Action création d'une demande | L’action création d'une demande est plus large et permet de faire ce que faisait l’action resoumission | 14/04/2022 | 
Champs de type Tableaux | Blocs de champs | Les 3 types de champs Tableaux peuvent avantageusement être remplacés par desblocs de champset donner une information mieux structurée. | 26/04/2022 | 
Champs de type « Éléments classés » | Blocs de champs | On peut utiliser lesblocs de champspour avoir un choix 1, choix 2, choix 3, etc. (il faut utiliser {{ block_counter.index}} pour avoir un numéro incrémental). | 21/10/2022 | 
Action de courriel récapitulatif | Rien | On constate que les gens qui ne veulent pas recevoir de courriel à chaque demande, sont souvent sur la plate-forme et n'ont pas besoin de ce récapitulatif. | 18/11/2022 | 
Liens incluant le code de suivi | {% temporary_access_url %} | Il existe unebalise {% temporary_access_url %}pour obtenir une adresse d’accès temporaire à une demande, sans authentification. | 08/02/2024 | 
Dépréciations passées
Conditions et préremplissages en Python | Conditions et préremplissages en Django | Ce peut être complexe pour les calculs ou l’enchaînement de booléens, il faut alors décomposer les opérations | 11/04/2022 | 31/12/2024

Vous pouvez trouver de l'aide pour remplacer vos conditions, expressions ou préremplissagessur cette page.

Limites sur le nombre d'éléments

Par ailleurs, pour veiller à la stabilité de Publik et pour que l'objectif de simplification portée par une GRU ne soit pas perdu de vue, nous avons mis en place les limitations listées ci-dessous. Les formulaires et workflows qui dépassent ces limites sont dépréciés.

* Studio
* Les tutos

# Donnée calculée

Donnée calculée

Ce type de champ, utilisable dans un formulaire ou une fiche, permet d'avoir un champ caché à l'utilisateur et dans lequel on stocke une valeur, comme on le fait avec une donnée de traitement dans les workflows.

Cette valeur peut provenir de différentes sources :

* Un paramètre passé dans l'URL :{{ request.GET.parametre }}
* Un calcul :{{ form_var_truc|add:form_var_machin }}
* Un texte :{{ form_var_bidule }}
* Toute autre valeur fixe

Cette valeur peut être unparamètre passé dans l’url{{ request.GET.parametre}}, un calcul {{ form_var_truc|add:form_var_machin }}, un texte {{ form_var_bidule }} ou toute autre valeur fixe.

Valeur (sous forme de gabarit Django)

C'est ici que l'on définit le contenu de ce champ. Ce contenu pourra être réexploitable ultérieurement en appelant la variable form_var_IDENTIFIANT. Cette définition se fait sous la forme d'un gabarit Django.

Les informations stockées dans le formulaire sont le plus souvent textuelles. Il est nécessaire d'utiliser le filtre |decimal lorsque l'on souhaite effectuer des calculs, ce filtre permettant de transformer le texte en nombre.

Les valeurs de ces champs sontcalculées en entrée de page. Elles sontrecalculées en sortie de pagesi la case « Conserver la valeur initialement calculée » n'est pas cochée.L'ordre de positionnement des champs « Donnée calculée » dans une page n'a pas d'influence sur le calcul.

Les données recalculées à la sortie de page peuvent être utilisées dans les conditions de sortie de page.

Ainsi, si vous avez une donnée calculée dépendante d'un champ de la page, sa valeur ne sera définie qu'à la sortie de la page, uniquement si l'option "Conserver la valeur initialement calculée" n'est pas activée. Vous ne pouvez donc pas utiliser une donnée calculée dans un champ de la même page si cette donnée dépend d'un autre champ de cette page.

Conserver la valeur initialement calculée

Cette option permet de conserver unparamètre transmis dans une urlde la forme :

https://mon-site/mon-formulaire/?parametre=la-valeur-a-transmettre

Il est obligatoire de cocher cette case pour que cela fonctionne.

Associer le champ à une fiche

Associer le champ donnée calculée à une fiche permet d'accéder aux données structurées de la fiche sélectionnée. Les données de la fiche deviennent alors disponibles dans des variables du type :

form_var_DONNEE-CALCULEE_live_var_CHAMP-FICHE

Pour cela, configurez le champ de type « Donnée calculée » comme suit :

* Source de données: Le modèle de fiche concerné.
* Valeur: L'identifiant de la fiche concerné.

Informations de débogage

Lorsqu'un formulaire contient au moins un champ de type « Donnée calculée », un volet « Informations de déboguage » est mis à disposition des administrateurs de démarches. Ce volet permet de visualiser le résultat des données calculées ainsi que les requêtes HTTP effectuées pour les champs de la page.

* Studio
* Les tutos

# Les principes de la gestion des rôles

Les principes de la gestion des rôles

Des permissions sont associées aux rôles ce qui permet d'attribuer des permissions à des utilisateurs en affectant des rôles aux utilisateurs. Certains rôles n'ont pas de permissions associées. Ces rôles servent à grouper des utilisateurs.

Un rôle peut également se voir affecter un autre rôle. Cette opération est communément appelé « héritage ». Lorsqu'un rôle se voit assigner un autre rôle, le premier est appelé « parent » et le second, « enfant ». Tous les utilisateurs affectés au rôle « parent » possèdent automatiquement le rôle « enfant ». Si le rôle « enfant » dispose de permissions, les utilisateurs affectés aux rôles « parent » auront automatiquement ces permissions.

Prenons l'exemple du rôle « Administrateur des utilisateurs », auquel est associé la permission qui permet de créer, de modifier ou de supprimer un compte utilisateur, et du rôle « Administrateur ». Le rôle « Administrateur » se voit assigner le rôle « Administrateur des utilisateurs ». Un utilisateur auquel on assigne le rôle « Administrateur » possède automatiquement le rôle « Administrateur des utilisateurs », donc la permission de créer, de modifier ou de supprimer un compte utilisateur.

Publik comporte deux catégories de rôles :

* Les rôles internes ou rôles "techniques" qui servent à définir les permissions pour administrer le système Publik. Les rôles et les permissions qui leurs sont assignées sont définis au niveau du système et ne sont pas modifiables, à l'exception de l'assignation des utilisateurs à ces rôles.
* Les rôles fonctionnels ou rôles "métiers" qui servent à définir les permissions des agents dans le traitement des demandes.

Le menu back-office des fonctionnalités s'adapte en fonction des permissions de l'utilisateur. Dès l'assignation de rôles, les permissions de l'utilisateur sont mises à jour et les accès sont restreints ou accrus. Le menu peut lui nécessiter une déconnexion et une reconnexion pour être mis à jour.

Les rôles internes ou rôles « techniques »

Les rôles internes ou rôles "techniques" servent à définir les permissions pour administrer le système Publik. Les rôles internes ou rôles "techniques" sont les suivants :

* Administrateur de PasserellePermission : Administration des connecteurs métiers. (Services Web). Uniquement si droits d'administration /Paramètres/Administrateur de Statistiques (Système/ bouton « Statistiques de fréquentation »)
* Administrateur de Agendas (Chrono)Permission : création et gestion des agendas.
* Administrateur d'Authentic :Administrateur : regroupe les 4 zones d'authentic : Administrateur des collectivités, Administrateur des rôles, Administrateur des services, Administrateur des utilisateurs.Permission : Affectation des utilisateurs aux rôles techniques.Administrateur des utilisateurs :Permission : Créer, modifier, supprimer un utilisateur. Pour affecter un rôle à un utilisateur il est également nécessaire de disposer de la permission de "Administrateur des rôles".Administrateur des rôles :Permission : Créer, modifier, supprimer un rôle non technique. Pour affecter un rôle à un utilisateur il également nécessaire de disposer de la permission de "Administrateur des utilisateurs".Administrateur des collectivitésPermission : Créer, modifier, supprimer une entité.Administrateur des services :Permission : Associer un rôle métier à un service (administrateur Agendas, Démarches, Hobo, Passerelle, Portail Agent, Portail Citoyen).Administrateur des paramètresPermission : Attribuer des rôles techniques à un rôle métier. Permission réservée au rôle Support. (Paramètres)
* Administrateur de Combo :Administrateur de Accueil de l'interface Agent (Portail Agent)Permission :Administrateur de Portail agentPermission : Utiliser le CMS de l'interface graphique du portail agent.Administrateur de Portail usagerPermission : Utiliser le CMS de l'interface graphique du portail agent.Administrateur du backofficePermission : accéder au backoffice, avec les droits minimums : accès à la page d'accueil du backoffice Agent, accès aux pages de traitement des demandes et des fiches. Ce rôle doit être attribué à tous les rôles métier
* Administrateur de Démarches (W.C.S.)Administrateur de FormulairesPermission : Créer, modifier, supprimer un formulaire (Fabrique de formulaires), un circuit de traitement (Studio/Workflows) et une catégorie de formulaires (Catégories). Accéder à la partie traitement des demandes avec la vue de toutes les demandes et de leur contenu (Traitement).Administrateur des modèles de fichesPermission : Créer, modifier, supprimer un modèle de fiche (Studio/Modèles de fiche), un circuit de traitement (Studio/Workflows) et une catégorie de fiches (Catégories). Accéder à la partie traitement des fiches avec la vue de toutes les fiches et de leur contenu (Fiches).Administrateur des workflowsPermission : Créer, modifier, supprimer un circuit de traitement (Studio/Workflows)Administrateur des catégoriesPermission : Créer, modifier, supprimer une catégorie (Catégories).

Les rôles fonctionnels ou rôles « métiers »

Les rôles fonctionnels ou rôles "métiers" servent à définir les permissions des agents dans le traitement des demandes.

Lors du déploiement de Publik, 3 rôles métier sont créés qui possèdent certains rôles techniques :Voir dans le Back Office, si vous y avez accès (cet accès est en général réservé au Support) : Menu latéral gauche /paramètres/, catégorie « Sécurité », « Permissions d’administration »

* Administrateur Fonctionnel : possède la plupart des rôles techniques, sauf l'accès aux /Paramètres. Les utilisateurs qui ont ce rôle créent les démarches (formulaires, les fiches, les workflows, etc.) et qui composent les portails Agent et Citoyen (création des pages, etc.).
* Agent : ne possède que le rôle technique « back office ». Un utilisateur qui possède ce rôle à accès au BO pour le traitement des demandes.
* Support : Un utilisateur qui a ce rôle possède tous les droits techniques.

Il est recommandé que tous les nouveaux rôles métier créés par l’administrateur fonctionnel contiennent les permissions du rôle « Agent » pour avoir accès au backoffice.

Les rôles fonctionnels se voient attribuer des actions de traitement par le biais des circuits de traitement (workflows).

Par exemple, le rôleagents-voirie(qui n'a donc par défaut que le rôle technique « Agent ») est associé sur les formulaires de la voirie à la fonctionDestinatairedu circuit de traitement "Voirie" et se voit donc associer en permission toutes les actions permises à la fonction Destinataire dans ce circuit de traitement.

Assigner un utilisateur à un rôle : voir icihttps://doc-publik.entrouvert.com/admin-fonctionnel/gerer-les-roles/assigner-un-utilisateur-a-un-role/

* Studio
* Les tutos

# Fiche d'un utilisateur

Fiche d'un utilisateur

La fiche d'un utilisateur permet la visualisation du profil de l'utilisateur et donne accès à toutes les opérations d'administration sur l'utilisateur.

La fiche d'un utilisateur est accessible depuisla liste des utilisateurs.

La visibilité des actions sur l'utilisateur dépend des droits d'accès de l'agent.

Le profil de l'utilisateur

* Le profil de l'utilisateur affiche l'ensemble des attributs de l'utilisateur.
* Le champCourrielest suivi du statut de validation de l'adresse de Courriel.
* Les champs obligatoires ont un intitulé suivi d'un astérisque rouge.
* Plusieurs attributs sont utilisables sur les champs du profil utilisateur :Obligatoire (impossible de créer un compte sans ce champ)Demandé à l'inscription (proposé lors de la création de compte)Requis à la connexion (rendra obligatoire la complétion de ce champ avant connexion). Cela peut être utile pour gérer un système de Conditions générales d’utilisation, où l’introduction d’une nouvelle version de celles-ci devra être portée à la connaissance de l’usager.Visible par l'usager (l'usager pourra voir le champ)Modifiable par l'usager (l'usager pourra éditer le champ)Pris en compte dans les recherches (sera indexé pour les recherches concernant les usagers)Désactivé (un champ du profil ne peut pas être supprimé mais il peut être désactivé).

Les informations générales sur l'utilisateur

Les informations générales se trouvent en haut de la colonne de droite et indiquent :

* La date de dernière connexion.
* La date de création.
* La date de dernière modification.

Les actions sur l'utilisateur

Éditer le profil de l'utilisateur

L'édition du profil de l'utilisateur se fait en cliquant sur le lien « Éditer » en haut à droite de la fiche.

Supprimer l'utilisateur

La suppression de l'utilisateur se fait en cliquant sur le lien « Supprimer » en haut à droite de la fiche.

Suspendre le compte et activer le compte

La suspension du compte empêche l'utilisateur de se connecter. Le compte est « désactivé ». Lorsque le compte est suspendu il est possible de le « réactiver ».

Suspendre le compte ne supprime pas les rôles de l'utilisateur. L'utilisateur ne peut cependant pas exercer ses droits puisqu'il ne peut pas se connecter.

La suspension du compte se fait en cliquant sur le bouton « Suspendre ».

L'activation du compte se fait en cliquant sur le bouton « Activer ».

Le bouton « Suspendre » n'apparaît que lorsque le compte est activé. Le bouton « Activer » n'apparaît que lorsque le compte est suspendu.

Gérer le mot de passe

Action « Réinitialiser le mot de passe »

Cette action est utilisée lorsque l'utilisateur a perdu son mot de passe. Elle permet de lui envoyer un courriel contenant un lien lui permettant de réinitialiser son mot de passe.

Cette action ne supprime pas, ou n'invalide pas, le mot de passe actuel du compte. Cette action ne suspend pas le compte.

Action « Forcer le mot de passe au prochain login » et « Ne pas forcer le mot de passe au prochain login »

L'action « Forcer le mot de passe au prochain login» est utilisée pour obliger l'usager à changer son mot de passe lors de sa prochaine connexion.

Lorsque cette action est utilisée, cette action est remplacée par l'action « Ne pas forcer le mot de passe au prochain login ».

Lorsque l'utilisateur a modifié son mot de passe, l'action « Ne pas forcer le mot de passe au prochain login » est remplacée par l'action « Forcer le mot de passe au prochain login ».

L'action « Ne pas forcer le mot de passe au prochain login » permet d'annuler l'action « Forcer le mot de passe au prochain login ».

Action « Changer le mot de passe »

L'action « Changer le mot de passe » permet de modifier le mot de passe de l'utilisateur.

Cette action n'a pas d'effet sur les actions « Réinitialiser le mot de passe », « Forcer le mot de passe au prochain login » et « Ne pas forcer le mot de passe au prochain login ».

Action « Changer l'adresse de courriel »

L'action « Changer l'adresse de courriel » n'est visible que si l'utilisateur se trouve dans une collectivité pour laquelle l'option « Validation des adresses de courriel » est activée.

Cette action permet d'envoyer un courriel à la nouvelle adresse de l'utilisateur saisie. Ce courriel contient un lien permettant à l'utilisateur de valider ce changement d'adresse de courriel.

Les rôles de l'utilisateur

Modifier les rôles

L'action « Modifier les rôles » permet d'inscrire et de désinscrire l'utilisateur à des rôles.

Liste des rôles

La liste des rôles de l'usager indiquent tous les rôles de l'usager, ceux auxquels il appartient directement et ceux auxquels il appartient indirectement.

Informations personnalisées dans la barre latérale

Il est possible d'ajouter les informations que vous voulez concernant l'utilisateur, sous la liste des rôles. Ce contenu est défini par un gabarit éditable en allant sur {{idp_url}}/manage/users/advanced/.

Un exemple d'utilisation est détaillé dans untutoriel concernant les rôles temporaires.

* Studio
* Les tutos

# Liste des utilisateurs

Liste des utilisateurs

DEBUT contenu

La page d'accueil offre la liste des utilisateurs, la recherche d'utilisateurs et permet l'ajout d'un nouvel utilisateur.

Le lien « Ajouter un utilisateur » n'apparaît que si l'agent possède les droits de création d'un utilisateur.

La liste des utilisateurs

La liste des utilisateurs est restreinte en fonction des droits d'accès de l'agent qui consulte la page.

Les utilisateurs sont classés par ordre alphabétique appliqué par défaut sur leur nom d'affichage, soit le prénom suivi du nom, qui apparaît en première colonne.

Le classement par ordre alphabétique peut être appliqué sur l'Identifiant, l'adresse de courriel, le prénom ou le nom en cliquant sur l'intitulé de la colonne correspondant.

La colonne intitulée « Actif » indique ✔ si le compte est activé ou ✘ si le compte est suspendu.

La colonne intitulée « Courriel vérifié » indique ✔ si l'adresse de courriel du compte est vérifiée ou ✘ si elle n'est pas vérifiée.

Une page de la liste est limitée par défaut à 25 utilisateurs. Le nombre de pages est indiqué en bas de page. Les numéros de page sont des liens permettant de naviguer entre les pages.

En bas de page sont affichés les fonctions d'export de la liste des utilisateurs. La liste des utilisateurs est exportable au format CSV, JSON ou ODS.

L'ensemble de la liste est exportée, elle n'est pas limitée à la page affichée ni à la liste filtrée par la recherche.

Publik multi-collectivités

Dans un publik multi-collectivités, lorsque la recherche n'est pas filtrée selon la collectivité, la collectivité d'appartenance de l'utilisateur est affichée en dernière colonne de la liste.

La recherche d'utilisateurs

La recherche se fait à partir du champ de saisie de la barre latérale de gauche. La recherche porte sur les champs « Prénom », « Nom », « Courriel » et « Identifiant » du profil de l'utilisateur.

La recherche se lance automatiquement dès la saisie dans le champ de recherche dans la très grande majorité des cas. Il n'est nécessaire de cliquer sur le bouton « Rechercher » que lorsque le langage Javascript est désactivé dans le navigateur de l'agent.

Les exports de la liste des utilisateurs ne sont pas modifiés par le filtrage résultant de la recherche.

Dans un publik multi-collectivités, une liste déroulante appelée « Collectivité » permet de filtrer la liste des utilisateurs selon leur collectivité d'appartenance. Dans ce cas, la colonne « Collectivité » de la liste n'est pas affichée.

Par défaut, le sélecteur est positionné sur « Toutes » pour que la liste ne soient pas filtrée par la collectivité d'appartenance des utilisateurs.

Le sélecteur propose un choix intitulé « Aucune » permettant de rechercher les utilisateurs sans collectivité. Aujourd'hui Publik ne permet plus de créer de nouveaux utilisateurs sans collectivité d'appartenance.

Pourquoi « Ajouter un utilisateur » est grisé !?

Préalablement à l'ajout d'un utilisateur il est nécessaire de choisir la collectivité d'appartenance de cet utilisateur. Cela se fait en choisissant la collectivité dans le sélecteur de collectivité. Si le sélecteur indique « Toutes » ou « Aucune » le lien « Ajouter un utilisateur » est grisé.

FIN contenu

* Studio
* Les tutos

# Surveillance et suivi applicatif

Surveillance et suivi applicatif

StatsD

w.c.s.peut communiquer à un serveurStatsDune série
    d'informations concernant le traitement des requêtes HTTP et
    l'authentification des utilisateurs.

L'adresse du serveurStatsDest récupérée d'une variable
    d'environnement nomméeQOMMON_STATSD_HOSTNAMEqui sera
    communément positionnée au niveau du serveur Web; par défautlocalhostsera utilisé.

Exemple de configuration Apache

SetEnv QOMMON_STATSD_HOSTNAME statsd.example.net

Les clés positionnées sont de la formewcs.domaine.clé, les points présents dans le
    nom de domaine remplacés par des tirets; par exemplewcs.teleservices-example-net.login-error.

Les informations suivantes sont communiquées :

login-submit | Compteur incrémenté lors de la validation d'une page
      d'authentification
--------------------------------------------------------------------------------------------
login-error | Compteur incrémenté lors d'une tentative d'authentification
      infructueuse.
login-success | Compteur incrémenté lors d'une tentative d'authentification
      réussie
successful-request | Compteur incrémenté à la fin d'une requête HTTP réussie
failed-request | Compteur incrémenté à la fin d'une requête HTTP avortée par
             une erreur interne (erreur HTTP 500)

# Récupération des données d’un usager

Récupération des données d’un usager

Il s’agit ici des API permettant à un logiciel tiers de récupérer les données
associées aux usagers enregistrés.

Demandes

La liste des demandes transmises par un usager est accessible à l’URL/api/users/uuid/forms, elle reprend un ensemble
    minimal d’informations concernant chacune de celles-ci.

GET https://www.example.net/api/users/uuid/forms{
    "err": 0,
    "data": [
        {
            "category_id": "1",
            "category_name": "Divers",
            "datetime": "2014-03-28 15:36:52",
            "form_name": "Demande d’inscription",
            "form_slug": "demande-d-inscription",
            "form_number": "123",
            "form_number_raw": "123",
            "form_receipt_date": "28/03/2014",
            "form_receipt_time": "15:36",
            "form_status": "Nouveau",
            "form_status_is_endpoint": false,
            "form_uri": "demande-d-inscription/123/",
            "form_url": "http://www.example.net/demande-d-inscription/123/",
            "form_url_backoffice": "http://www.example.net/backoffice/demande-d-inscription/123/",
            "name": "Demande d’inscription",
            "status": "Nouveau",
            "title": "Demande d’inscription #123 (Nouveau)",
            "url": "http://www.example.net/demande-d-inscription/123/",
        },
        {
            "category_id": "2",
            "category_name": "Prise de rendez-vous",
            "datetime": "2014-03-17 10:39:52",
            "form_name": "Rendez-vous avec le service B",
            "form_slug": "rendez-vous-service-b",
            "form_number": "456",
            "form_number_raw": "456",
            "form_receipt_date": "17/03/2014",
            "form_receipt_time": "10:39",
            "form_status": "En cours",
            "form_uri": "rendez-vous-service-b/456/",
            "form_url": "http://www.example.net/rendez-vous-service-b/456/",
            "form_url_backoffice": "http://www.example.net/backoffice/rendez-vous-service-b/456/",
            "name": "Rendez-vous avec le service B"",
            "title": "Rendez-vous avec le service B #456 (En cours)",
            "url": "http://www.example.net/rendez-vous-service-b/456/",
        },
        {
            "category_id": "3",
            "category_name": "Modification de vos coordonn\u00e9es",
            "datetime": "2014-03-17 10:42:17",
            "form_name": "Changement d’adresse",
            "form_slug": "changement-d-adresse",
            "form_number": "424",
            "form_number_raw": "424",
            "form_receipt_time": "10:42",
            "form_status": "Traitement de la demande termin\u00e9",
            "form_status_is_endpoint": true,
            "form_uri": "changement-d-adresse/424/",
            "form_url": "http://www.example.net/changement-d-adresse/424/",
            "form_url_backoffice": "http://www.example.net/backoffice/changement-d-adresse/424/",
            "name": "Changement d’adresse",
            "status": "Traitement de la demande termin\u00e9",
            "title": "Changement d’adresse #424 (Traitement de la demande termin\u00e9)",
            "url": "http://www.example.net/changement-d-adresse/424/",
        }
    ]
}

Le même résultat peut être obtenu en utilisant/api/user/formsmais cet endpoint ne fonctionne pas avec l’authentification HTTP Basique;
elle demande la mise en place de l’algorithme de signature.

Il est possible de recevoir un ensemble plus complet de données en passant un
paramètrefull=onà l’adresse.  Pour inclure également les
brouillons, un paramètreinclude-drafts=truepeut être passé.

Par ailleurs le filtre?filter-user-uuid=peut s’appliquer sur
les API de récupérations de demandes et de fiches pour filtrer sur un usager
particulier.

Brouillons

La liste des brouillons de l’usager est accessible à l’adresse/api/users/uuid/drafts.

GET https://www.example.net/api/user/uuid/drafts{
    "err": 0,
    "data": [
        {
            "datetime": "2014-07-21 10:15:21",
            "name": "Demande de relecture",
            "title": "Demande de relecture, brouillon enregistré le 21/07/2014 10:15",
            "url": "http://www.example.net/demande-de-relecture/164"
        }
    ]
}

# Traitement d’un formulaire

Traitement d’un formulaire

Synchrone

Pour faire évoluer un formulaire en fonction de données extérieures, le
workflow peut contenir une action d’appel à un
webserviceet enchaîner sur une série de sauts automatiques,
conditionnés par le résultat de l’appel.

Asynchrone

Pour des traitements asynchrones, w.c.s expose également une API autorisant
les logiciels tiers à faire progresser le
traitement d’un formulaire; cela passe par la définition dans le statut du
workflow d’un élément de type « Changement de statut automatique », dans
lequel un identifiant de déclencheur est défini.

La demande d’un changement d’état se fait par une requêtePOSTà
l’adresse du formulaire en question, suivi dejump/trigger/et de
la référence à l’identifiant de déclencheur (validatedans
l’exemple qui suit).

Lors de cette requête, il est nécessaire d’inclure l’entêteAccept: application/json.

POST https://www.example.net/inscriptions/newsletter/14/jump/trigger/validate/{"url": null, "err": 0}

Il est également possible d’accompagner le déclenchement d’un changement
de statut d’une série de données, qui seront enregistrées dans les données de
workflow du formulaire.

POST https://www.example.net/inscriptions/newsletter/14/jump/trigger/validate/
→ {"reason": "C’est ok."}{"url": null, "err": 0}

Ces données seront accessibles dans des variables nomméesform_trigger_l’identifiant_du
déclencheur_content_données, l’exemple ci-dessus
donnerait donc une variableform_trigger_validate_content_reasonavec le texteC’est ok.comme valeur.

Des déclencheurs peuvent aussi être définis au niveau des actions
globales du workflow, ils pourront alors être appelés quel que soit le statut
de la demande.

Un tel appel, avec un déclencheur global ici intituléurgentse
ferait ainsi :

POST https://www.example.net/api/forms/newsletter/14/hooks/urgent/{"err": 0}

# Variables d’environnement

Variables d’environnement

La majeure partie du paramétrage est accessible via les écrans de paramétrage
ou via le fichiersite-options.cfg; pour faciliter le travail de
configuration quand il s’agit d’informations proches de l’administration
système, il existe également la possibilité d’utiliser des variables
d’environnement.

Redirection des emails

Accessible dans l’écran de paramétrage des options de debug, il est
    aussi possible de forcer les emails générés par la plateforme à être
    envoyés vers une adresse unique, en positionnant la variable
    d’environnementQOMMON_MAIL_REDIRECTION.

Fréquence de vérification des expirations des sauts

Par défaut les sauts de workflow sont évalués trois fois par heure, toutes
   les vingt minutes.  Il est possible de définir une autre fréquence dans la
   variable d’environnementWCS_JUMP_TIMEOUT_CHECKS.  Cette
   variable doit contenir le nombre de vérifications à réaliser par heure, le
   maximum est d’une vérification toutes les minutes (i.e.WCS_JUMP_TIMEOUT_CHECKS=60).

# Authentification

Authentification

Gestion des accès aux API

La création d’accès aux API se gère globalement depuis le module de gestion d’identités (Authentic). L’écran de configuration est accessible depuis la page d’accueil de ce module, via le bouton « Clients d’API » dans sa barre latérale droite.

Le bouton « Ajouter un nouveau client d’API » permet d’ajouter un accès, et il faut indiquer :

* Nom : le nom choisi pour l’accès, qui sera affiché dans la page des accès ;
* Description : pour se rappeler de l’usage prévu pour cet accès ;
* Identifiant : le nom de l’utilisateur à utiliser pour l’authentification HTTP Basic, ou le paramètreorigpour l’authentification par signature ;
* Mot de passe : le mot de passe pour l’authentification HTTP Basic de cet utilisateur ;
* Collectivité : dans un environnement multi-collectivités, la collectivité à laquelle attacher cet accès ;
* Rôles : la liste des rôles automatiquement obtenus lorsque cet accès est utilisé. Par exemple, s’il s’agit de permettre de lister des demandes d’une certaine démarche, il faut indiquer un rôle qui permet de voir les demandes. Ce rôle est à déterminer selon le paramétrage du formulaire de la démarche et/ou de son workflow.

Il est conseillé de créer des «rôles techniques» dédiés aux API. Ces rôles ne sont jamais donnés à des utilisateurs de la plateforme, ils sont utilisés uniquement dans le paramétrage des accès. Typiquement une démarche est paramétrée pour qu’un certain rôle technique ait accès à ses demandes, et ce même rôle est indiqué dans l’accès aux API dédié.

Définitions de l’usager concerné

Si l’authentification utilisée passe par un accès aux API qui ne donne pas de rôle spécifique, alors il faut indiquer dans la query-string un usager qui aura les rôles nécessaires.

C'est aussi nécessaire pour les appels concernant un usager particulier, tel que la récupération de la liste de ses formulaires en cours.

L’usager est précisé en ajoutant dans la query string :

* soit un paramètreemailpour trouver l’usager selon son adresse électronique
* soit un paramètreNameIDpour trouver l’usager selon son NameID SAML.

Authentification simple HTTP Basic

Pour accéder aux API avec l’authentification HTTP Basic classique, il faut utiliser le nom d’utilisateur (identifiant d’accès) et le mot de passe (clé d’accès) de l’accès configuré ci-dessus.

Authentification par signature de l’URL

Historiquement un système d’authentification alternatif, basé sur une signature ajoutée à la fin de l’URL était également disponible. Avec la généralisation de l’HTTPS, il est obsolète.

Signature des requêtes

La signature d’un appel aux API passe par une clé partagée à configurer des deux cotés de la liaison, la signature est du type HMAC; l’algorithme de hash à employer est passé en paramètre.

En ce qui concerne l’algorithme de hash, il est préconisé d’utiliser SHA-256 par respect duRéférentiel Général de Sécurité (RGS).

La signature est à calculer sur la query string encodée complète, en enlevant les paramètres terminauxalgo,timestamp,nonce,origetsignatures’ils sont présents.

La formule de calcul de la signature est la suivante :

BASE64(HMAC-HASH(query_string+'algo=HASH&timestamp=' + timestamp + '&nonce=' + nonce '&orig=" + orig, clé))

* timestampest la date dans la zone GMT au format ISO8601 en se limitant à la précision des secondes (ex : 2012-04-04T12:34:00Z),
* nonceest un aléa, typiquement la réprésentation hexa d’un nombre pseudo-aléatoire de 128 bits,
* origest une chaîne précisant l’émetteur de la requête,
* algo est une chaîne représentant l’algorithme de hachage utilisé, sont définis : sha1, sha256, sha512 pour les trois algorithmes correspondant. L’utilisation d’une valeur différente n’est pas définie. L’algorithme sha256 est préconisé.

La query string définitive est ainsi :

qs_initial&algo=algo&timestamp=timestamp&nonce=nonce&orig=orig&signature=signature

Configuration des clés partagées

La définition des clés se fait lors de la création des accès aux API (voir plus haut). Lors de la création d'un nouvel accès, l’identifiant d'accès correspond au «orig» et la clé d'accès est la clé de signature. Les rôles sont ceux qui seront obtenus lors de l’usage de l’accès.

Historiquement les clés partagées pouvaient aussi être définies dans le fichiersite-options.cfg, dans une section[api-secrets], cette méthode n'est pas conseillée car elle ne permet pas de préciser finement les rôles. Exemple :

[api-secrets]
intranet = 12345

Exemples d'implémentation de l’algorithme de signature

Voici des exemples de code pour créer des URLs signées selon l’algorithme expliqué ci-dessus.

Python

#! /usr/bin/env python3

import base64
import hashlib
import hmac
import random
import urllib.parse

def sign_url(url, key, algo='sha256', orig=None, timestamp=None, nonce=None):
    parsed = urllib.parse.urlparse(url)
    new_query = sign_query(parsed.query, key, algo, orig, timestamp, nonce)
    return urllib.parse.urlunparse(parsed[:4] + (new_query,) + parsed[5:])

def sign_query(query, key, algo='sha256', orig=None, timestamp=None, nonce=None):
    if timestamp is None:
        timestamp = datetime.datetime.utcnow()
    timestamp = timestamp.strftime('%Y-%m-%dT%H:%M:%SZ')
    if nonce is None:
        nonce = hex(random.getrandbits(128))[2:].rstrip('L')
    new_query = query
    if new_query:
        new_query += '&'
    new_query += urllib.parse.urlencode((('algo', algo), ('timestamp', timestamp), ('nonce', nonce)))
    if orig is not None:
        new_query += '&' + urllib.parse.urlencode({'orig': orig})
    signature = base64.b64encode(sign_string(new_query, key, algo=algo))
    new_query += '&' + urllib.parse.urlencode({'signature': signature})
    return new_query

def sign_string(s, key, algo='sha256', timedelta=30):
    if not isinstance(key, bytes):
        key = key.encode('utf-8')
    if not isinstance(s, bytes):
        s = s.encode('utf-8')
    digestmod = getattr(hashlib, algo)
    hash = hmac.HMAC(key, digestmod=digestmod, msg=s)
    return hash.digest()

# usage:
url = sign_url('https://www.example.net/uri/?arg=val&arg2=val2', 'user-key', orig='user')

PHP

<?php

function sign_url(string $url, string $orig, string $key) {
	$parsed_url = parse_url($url);
	$timestamp =  gmstrftime("%Y-%m-%dT%H:%M:%SZ");
	$nonce = bin2hex(random_bytes(16));
	$new_query = '';
	if (isset($parsed_url['query'])) {
		$new_query .= $parsed_url['query'] . '&';
	}
	$new_query .= http_build_query(array(
		'algo' => 'sha256',
		'timestamp' => $timestamp,
		'nonce' => $nonce,
		'orig' => $orig));
	$signature = base64_encode(hash_hmac('sha256', $new_query, $key, $raw_output = true));
	$new_query .= '&' . http_build_query(array('signature' => $signature));
	$scheme   = isset($parsed_url['scheme']) ? $parsed_url['scheme'] . '://' : '';
	$host     = isset($parsed_url['host']) ? $parsed_url['host'] : '';
	$port     = isset($parsed_url['port']) ? ':' . $parsed_url['port'] : '';
	$user     = isset($parsed_url['user']) ? $parsed_url['user'] : '';
	$pass     = isset($parsed_url['pass']) ? ':' . $parsed_url['pass']  : '';
	$pass     = ($user || $pass) ? "$pass@" : '';
	$path     = isset($parsed_url['path']) ? $parsed_url['path'] : '';
	$fragment = isset($parsed_url['fragment']) ? '#' . $parsed_url['fragment'] : '';
	return "$scheme$user$pass$host$port$path?$new_query$fragment";
}

# usage:
url = sign_url("http://www.example.net/uri/?arg=val&arg2=val2", "user", "user-key");

?>

Shell (bash)

#!/bin/bash

url="http://www.example.net/uri/?arg=val&arg2=val2"
orig="user"
key="user-key"

function rawurlencode() {
  local string="${1}"
  local strlen=${#string}
  local encoded=""
  local pos c o
  for ((pos=0; pos<strlen; pos++)); do
     c=${string:$pos:1}
     case "$c" in
        [-_.~a-zA-Z0-9] ) o="${c}" ;;
        * )               printf -v o '%%%02x' "'$c"
     esac
     encoded+="${o}"
  done
  echo "${encoded}"
}

now=$(date -u +%FT%TZ);
nonce=$(od -N16 -txL /dev/urandom | cut -c8- | tr -d " ")
qs="algo=sha256&timestamp=$now&nonce=$nonce&orig=$orig"
sig=$(rawurlencode $(echo -n "$qs" | openssl dgst -binary -sha256 -hmac "$key" | base64))
signed="${url}?$qs&signature=$sig"
echo "$signed"

# Complétion et modification d’un formulaire

Complétion et modification d’un formulaire

w.c.s expose une API autorisant les logiciels tiers à transmettre des données
structurées permettant la complétion d’un formulaire ou la modification d’un
formulaire existant.

Il n’y a aucune vérification du format des données reçues, elles sont
  enregistrée telles quelles. Les contraintes de validation ou les conditions
  d’affichage ne sont pas prises en compte.

Complétion d’un formulaire

La complétion d’un formulaire se fait par une requêtePOSTà
   l’adresse/api/formdefs/slug/submit, le contenu de
   la requête doit être un dictionnaire contenant obligatoirement un attributdataet optionnellement un attributmetaet un
   attributcontext.

Leslugest l’identifiant non-numérique utilisé dans les URL, il
    est visible depuis l’écran d’un formulaire, dans la fenêtre de modification
    du titre.

L’attributdataest obligatoire et contient un dictionnaire
   dont les clés sont les noms de variable (remplacé ici parvarname) des champs du formulaire et les valeurs le contenu de
   ces champs.

* Les champs de type simple tels que « Texte », « Texte long » ou
   « Courriel » sont des chaînes de caractères.
* Les champs de type « Liste » et « Liste à choix multiples » acceptent
   différentes valeurs selon leur configuration, ceci est décrit dansTransmission des champs « Liste » et « Liste à choix multiple ».
* Les champs de type « Date » sont des chaînes de caractères au format
   ISO-8601, i.e.YYYY-MM-DD.
* Les champs de type « Fichier » sont des dictionnaires contenant les clésfilenamepour le nom de fichier etcontentpour le
   contenu de celui-ci, encodé en base64.
* Les champs de type « Carte » sont des dictionnaires contenant les cléslatpour la latitute en nombre décimal etlonpour la longitude en nombre décimal.
* Les blocs de champs sont des listes de dictionnaires, avec comme clés les
   différents champs du blocs, par exemple pour un bloc contenant deux champs,
   avec les identifiantsarticleetquantite:[{"article": "Pomme", "quantite": "2"}, {"article": "Poire", "quantite": 4}]

L’attributuserest optionnel et peut contenir un identifiant
   permettant d’associer la demande à un usager existant; l’identifiant peut
   être soit l’identifiant unique (UUID/NameID), passé dans une cléNameID, soit l’adresse électronique de l’usager, passée dans
   une cléemail.

L’attributmetaest optionnel et contient une série de
   paramètres supplémentaires concernant le formulaire.

Métadonnées

draft | truepour enregistrer le formulaire comme étant un
      brouillon.
--------------------------------------------------------------------------
backoffice-submission | truepour enregistrer le formulaire comme étant
      saisi depuis le backoffice.

L’attributcontextest également optionnel et contient une
   série de renseignements supplémentaires sur le contexte de l’envoi du
   formulaire.  Les attributs reconnus sontchannel,thumbnail_url,user_idetcomments.

L’exemple suivant complète un formulaire d’inscription à une newsletter, qui
   demanderait trois champs : prénom (nom de variableprenom), nom
   (nom de variablenom) et adresse électronique (nom de variableemail).

POST https://www.example.net/api/formdefs/newsletter/submit{"err": 0, "data": {"id": "1"}}

Avec les données suivantes en entrée :

{
  "data": {
     "prenom": "Marc",
     "nom": "L.",
     "email": "marc@example.net"
  },
  "user": {
  }
}

Modification d’un formulaire

Un formulaire qui peut être modifié (par la présence d’une action de workflow
   de type « Édition ») peut également être modifié via un appel à
   l’API, en faisant unPOSTsur l’adresse du formulaire.

Les données attendues sont similaires à la création d’un nouveau formulaire,
   seuls les champs présents seront pris en compte.

Cet appel :

POST https://www.example.net/api/forms/newsletter/1/{"err": 0}

Avec les données suivantes en entrée, modifiera donc uniquement le champ
  « email ».

{
  "data": {
     "email": "marc@example.org"
  }
}

Transmission des champs « Liste » et « Liste à choix multiple »

Pour les champs de type « Liste », si le champ est configuré avec une simple
   liste d’options, la valeur doit être une chaîne tirée de la liste.

"data": {
       "varname": "Libellé 1"
    }

Si le champ est configuré pour tirer ses options depuis une source de
    données, la valeur peut être l’identifiant d’une donnée structurée ou si la
    donnée structurée complète est transmise, l’identifiant de la donnée dans
    une clé suffixée de_raw, le libellé de la donnée dans la clé
    normale et éventuellement la donnée structurée complète dans une clé
    suffixée de_structured.

Identifiant d’une option

"data": {
       "varname": "1"
    }

Donnée structurée

"data": {
       "varname": "Libellé 1",
       "varname_raw": "1",
       "varname_structured": {
          "id": "1",
          "text": "Libellé 1",
          "foo": "bar"
       }
    }

Pour les champs de type « Liste à choix multiple », si le champ est
   configuré avec une simple liste d’options, la valeur doit être une
   liste de chaînes tirées de la liste.

"data": {
       "varname": ["Libellé 1", "Libellé 2"]
    }

    données, la valeur peut être une liste d’identifiants ou,
    si la donnée structurée complète est transmise, la liste des identifiants
    de la donnée dans une clé suffixée de_raw, la liste des
    libellés de la donnée dans la clé normale et éventuellement la liste des
    données structurées complètes dans une clé suffixée de_structured.

Liste d’identifiants d’options

"data": {
       "varname": ["1", "2"]
    }

Listes de données structurées

"data": {
       "varname": ["Libellé 1", "Libellé 2"],
       "varname_raw": ["1", "2"],
       "varname_structured": [
         {
            "id": "1",
            "text": "Libellé 1",
            "foo": "bar"
         },
         {
            "id": "2",
            "text": "Libellé 2",
            "foo": "bar2"
         }
       ]
    }

# Accès à des référentiels externe

Accès à des référentiels externe

w.c.s. peut utiliser des référentiels externes pour par exemple alimenter la
liste des choix possibles dans un champ; pour ce faire w.c.s. utilise le
format JSON.
L’adresse appelée doit répondre aux exigences suivantes :

* retourner les données, triées, dans un attribut nommédata;
* présenter chaque élément des données dans un dictionnaire contenant
          deux éléments,idcontenant un identifiant unique ettextcontenant le texte de la valeur ;

Exemple JSON

GET https://www.example.net/data/fruits{
    "data": [
        {
            "text": "Poire",
            "id": "1"
        },
        {
            "text": "Pomme",
            "id": "2"
        }
    ]
}

Quand il y a besoin de filtrer dynamiquement les données
(autocomplétion, recherche dans un champ liste), l’adresse appellée
doit respecter les exigences supplémentaires suivantes :

* accepter un paramètre, usuellementid,
          permettant de retourner un seul élément en le désignant par son identifiant ;
* accepter un paramètre, usuellementq,
          permettant de filtrer les éléments en fonction de leur contenu.

Exemple JSON d’un élément unique désigné par son identifiant

GET https://www.example.net/data/fruits?id=1{
    "data": [
        {
            "id": "1"
        }
    ]
}

Exemple JSON filtré par contenu

GET https://www.example.net/data/fruits?q=pom{
    "data": [
        {
            "id": "2"
        }
    ]
}

En plus des clésidettextqui sont obligatoires,
les différents éléments peuvent contenir des clés supplémentaires, pour des
informations annexes. Celles-ci seront alors accessibles dans les variables
de contexte du formulaire.

Exemple JSON enrichi

    "data": [
        {
            "id": "1",
            "saison": "automne",
            "prix": "1"
        },
        {
            "id": "2",
            "prix": "2"
        }
    ]
}

# Gestion des fiches

Gestion des fiches

Une application tierce peut créer des fiches, récupérer et modifier les données
des fiches, et peut également obtenir la liste des modèles de fiche et les
schémas de données associés.

Création d’une fiche

La création d’une fiche se fait par une requêtePOSTà
   l’adresse/api/cards/slug/submit, le contenu de
   la requête doit être un dictionnaire contenant obligatoirement un attributdata.

    est visible depuis l’écran d’un modèle de fiche, dans la fenêtre de
    modification du titre.

   dont les clés sont les noms de variable (remplacé ici parvarname) des champs de la fiche et les valeurs le contenu de

L’exemple suivant crée une fiche « Parking », dont le modèle
   de fiche a comme identifiant « parkings », qui demanderait trois champs :
   adresse (nom de variableadresse), date d’ouverture
   (nom de variabledate_ouverture) et nom (nom de variablenom).

POST https://www.example.net/api/cards/parkings/submit{"err": 0, "data": {"id": "5"}}

{
  "data": {
     "adresse": "rue de l’Opéra",
     "date_ouverture": "2020-11-12",
     "nom": "Parking Opéra-Tolozan"
  }
}

    enregistrée telles quelles. Les contraintes de validation ou les conditions
    d’affichage ne sont pas prises en compte.

Création d’un ensemble de fiches par import CSV

Il est possible de créer un ensemble de fiches par import d’un fichier CSV.
Cela s’effectue par une requêtePUTà l’adresse/api/cards/slug/import-csv. Le contenu de la requête
doit être un fichier CSV (text/csv).

Chaque ligne du fichier va provoquer la création d’une nouvelle fiche et lancer
le workflow correspondant.

PUT https://www.example.net/api/cards/slug/import-csv{"err": 0}

Le fichier CSV doit suivre le même format que celui utilisé lors d’un import
CSV dans l’interface de gestion.

Quand le modèle de fiche définit un identifiant personnalisé pour les
fiches, il est possible de définr le comportement à adopter concernant les
fiches qui auraient le même identifiant :update-mode=updatepour faire
la mise à jour,update-mode=skippour ignorer ces fiches. Le
comportement sur les fiches existantes mais absentes du fichier CSV peut
également être contrôlé,delete-mode=keeppour les conserver,delete-mode=deletepour les supprimer.

Import CSV asynchrone (recommandé)

En plus de la création des fiches, le workflow va être exécuté pour chacune :
sur un fichier CSV important le temps d’exécution de l’import peut dépasser la
limite acceptée par le serveur HTTP (souvent 20 ou 30 secondes). Il est donc
recommandé d’utiliser l’option asynchrone de l’import CSV.

Pour faire un import asynchrone, ajouterasync=ondans les
paramètres de l’URL :

PUT https://www.example.net/api/cards/slug/import-csv?async=on{
    "err": 0,
    "data": {
        "job": {
            "id": "1234",
            "url": "https://www.example.net/api/jobs/1234/"
        }
    }
}

Cet appel envoie le fichier CSV, mais il n’est pas aussitôt importé. Une tâche
(job) est lancée qui va effectivement faire l’import, et on peut en
suivre la progression en appellant son URL indiquée en retour de l’appel PUT.

GET https://www.example.net/api/jobs/1234/{
    "err": 0,
    "data": {
        "status": "en cours",
        "label": "Importation des données dans des fiches",
        "creation_time": 1634910701,
        "completion_time": null,
        "completion_status": "23/46 (50%)"
}
}

Pour suivre la bonne exécution de l’import, il faut appeler cette URL jusqu’à
ce que la valeurcompletion_timesoit renseignée. La valeurstatuspermet de savoir alors si l’import s'est correctement
déroulé.

Récupération des données d’une fiche

L’exemple suivant récupère les données d’une fiche « Parking », dont le modèle
de fiche a comme identifiant « parkings ».

GET https://www.example.net/api/cards/parkings/5/

Le contenu ainsi obtenu est le suivant :

{
   "digest" : "Parking Opéra-Tolozan",
   "display_id" : "31-5",
   "display_name" : "Parkings - n°31-5",
   "id" : "5",
   "last_update_time" : "2020-11-24T14:18:16",
   "receipt_time" : "2020-11-06T14:48:07",
   "fields" : { 
      "adresse" : "rue de l’Opéra",
      "date_ouverture" : "2020-11-12",
      "nom" : "Parking Opéra-Tolozan"
   },
   "text" : "Parking Opéra-Tolozan",
   "url" : "https://.../backoffice/data/parkings/5/",
   "workflow" : {
      "status" : {
         "id" : "recorded",
         "name" : "Recorded",
         "endpoint": false
      }
   },
   "evolution" : [...],
   "geolocations": {...},
   "roles": {...}
}

La structure du contenu correspond à celle de l’API deCréation d’une fiche.

Modification des données d’une fiche

Sur le même modèle que les formulaires une fiche qui peut être modifiée (par
la présence d’une action de workflow de type « Édition ») peut également être
modifiée via un appel à l’API.

Les données attendues sont similaires à la création d’une nouvelle fiche
(Création d’une fiche), seuls les champs présents seront pris en compte.

POST https://www.example.net/api/cards/parkings/5/

Liste de fiches

La liste des fiches d’un modèle donné est destinée à être utilisée par
un système de synchronisation. Elle ne retourne donc pour chaque fiche que
son numéro (id), ses dates de création et de dernière mise à jour.

Un système de synchronisation vérifiera depuis cette liste si de nouvelles
demandes existent, ou si certaines ont été mises à jour, sont obsolètes ou
effacées, puis effectuera pour chacune les actions nécessaires.

GET https://www.example.net/api/cards/parkings/list{
    "data": [
        {
            "id": 1,
            "text": "Parking de la place",
            "url": "https://www.example.net/backoffice/data/parkings/1/",
            "last_update_time": "2015-03-26T23:08:45",
            "receipt_time": "2015-03-26T23:08:44",
            "display_id": "12-1",
            "display_name": "Parkings - n°12-1"
        },
        {
            "id": 2,
            "text": "Parking des nénuphars",
            "url": "https://www.example.net/backoffice/data/parkings/2/",
            "last_update_time": "2015-03-27T09:03:12",
            "receipt_time": "2015-03-27T09:03:12",
            "display_id": "12-2",
            "display_name": "Parkings - n°12-2"
        },
        {
            "id": 3,
            "text": "Parking de la rivière",
            "url": "https://www.example.net/backoffice/data/parkings/3/",
            "last_update_time": "2015-03-27T12:11:21",
            "receipt_time": "2015-03-27T12:45:19",
            "display_id": "12-3",
            "display_name": "Parkings - n°12-3"
        }
    ]
}

Des paramètres peuvent être envoyés dans la requête pour filtrer la liste des
fiches, ils sont similaires à ceux de l’API derécupération d’une liste de formulaires. Les
autres paramètres de cette API sont également exploitables, pour inclure
l’ensemble des données (full=on) ou anonymiser celles-ci
(anonymise).

Il est également possible de récupérer une liste filtrée correspondant à une
vue personnalisée, en ajoutant l’identifiant de celle-ci à l’adresse, ex :

GET https://www.example.net/api/cards/parkings/list/vue-personnalisee{
    "data": [
        {
            "id": 1,
        },
        {
            "id": 3,
        }
    ]
}

Schéma de données

Une API existe pour récupérer le schéma de données d’un modèle de fiches.

GET https://www.example.net/api/cards/parkings/@schema{
   "always_advertise" : false,
   "appearance_keywords" : null,
   "confirmation" : false,
   "description" : null,
   "detailed_emails" : true,
   "digest_template" : "{{form_var_nom}}",
   "disabled" : false,
   "disabled_redirection" : null,
   "discussion" : false,
   "drafts_lifespan" : null,
   "drafts_max_per_user" : null,
   "enable_tracking_codes" : false,
   "expiration_date" : null,
   "fields" : [
      {
         "anonymise" : true,
         "data_source" : {},
         "label" : "Nom",
         "prefill" : {
            "type" : "none"
         },
         "required" : true,
         "type" : "string",
         "validation" : {},
         "varname" : "nom"
      },
      ...
   ],
      "fields" : [],
      "functions" : {
         "_editor" : "Editor",
         "_viewer" : "Viewer"
      },
      "name" : "Fiche parking",
      "statuses" : [
         {
            "endpoint" : false,
            "forced_endpoint" : false,
            "id" : "recorded",
            "name" : "Recorded",
            "waitpoint" : true
         },
      ...
   }
}

Liste des modèles de fiches

Une API permet de récupérer la liste des modèles de fiches.

GET https://www.example.net/api/cards/@list{
   "data" : [
      {
         "custom_views" : [],
         "description" : "",
         "id" : "parkings",
         "keywords" : [],
         "slug" : "parkings",
         "text" : "Parkings",
         "title" : "Parkings",
         "url" : "https://.../backoffice/data/parkings/"
      },
      ...
   }
}

# Permissions d’administration

Permissions d’administration

Dans le fonctionnement de base un compte d’administration ouvre l’accès à
  toutes les pages de l’interface d’administration, il est néanmoins possible
  de paramétrer de manière plus fine l’accès aux différentes sections.

Dans l’espace de paramétrage, dans la section « Sécurité », suivez le lien
  « Permissions d’administration ».  Pour chacune des grandes sections de
  l’administration (Formulaires,Modèles de fiches,Workflows…) vous pouvez restreindre l’accès aux utilisateurs
  disposant de rôles particuliers.

Accès d’administration de secours

En cas de mauvaise manipulation et de perte totale de l’accès à l’interface
    d’administration, le système dispose d’un moyen de secours
    pour temporairement désactiver la vérification des permissions d’accès.

Dans le répertoire de l’instance (/var/lib/wcs/tenants/www.example.net/par exemple), un fichierADMIN_FOR_ALLdoit être créé,
    contenant l’adresse IP qui sera utilisée pour la connexion.

#cd /var/lib/wcs/tenants/www.example.net/#echo 77.109.103.99 > ADMIN_FOR_ALL

L’interface d’administration devient alors accessible pour permettre la
     correction de l’éventuelle erreur. Dans ce mode elle affiche son bandeau
     en rouge vif, rappel que celui-ci est exceptionnel et dangereux.  Dès
     l’accès restauré, il est important de supprimer le fichierADMIN_FOR_ALL.

Pour des raisons de compatibilité, un fichierADMIN_FOR_ALLvide ouvre l’accès pour toutes les connexions; ce comportement
      dangereux sera supprimé dans une version à venir, son utilisation est
      fortement découragée.

# Accès aux listes et schémas de données

Accès aux listes et schémas de données

w.c.s expose une API permettant aux logiciels tiers de connaître les différents
formulaires et leurs schémas de données.

La liste des formulaires accessibles à un utilisateur est disponible à
l’URL/api/formdefs/.

GET https://www.example.net/api/formdefs/[{"url": "https://www.example.net/inscriptions/newsletter",
  "title": "Newsletter",
  "slug": "newsletter",
  "authentication_required": false,
  "redirection": false,
  "description": "",
  "keywords": [],
  "category": "Inscriptions",
  "category_slug": "inscriptions"},
 {"url": "https://www.example.net/inscriptions/piscine",
  "title": "Piscine",
  "slug": "piscine",
  "authentication_required": true,
  "description": "La piscine est ouverte du lundi au samedi.",
  "keywords": ["sport"],
  "category_slug": "inscriptions"}
]

Note de compatibilité : la même information est disponible à la racine du site,
quand un entêteAccept: application/jsonest transmis, ou à une
URL/jsonautrement.

La liste des formulaires accessibles à un utilisateur dans le but de faire une
saisie backoffice est disponible, sous le même format, via l’URL/api/formdefs/?backoffice-submission=on.

Il est également possible d’obtenir un nombre permettant de trier les résultats
par « popularité » en ajoutant un paramètreinclude-count=on. Les
différentes entrées disposeront alors d’une clécount.

L’informationcountn’estpasle décompte intégral des
demandes, c’est un indice composite donnant davantage de poids aux demandes
récentes.

La liste retournée inclura les formulaires désactivés en ajoutant le paramètreinclude-disabled=on.

La liste des catégories est disponible à l’URL/api/categories/.

GET https://www.example.net/api/categories/{"data":
  [
   {"url": "https://www.example.net/inscriptions/",
    "slug": "inscriptions",
    "title": "Inscriptions",
     "description": "<p>Pour vous et vos enfants...</p>" },
   {"url": "https://www.example.net/etat-civil/",
    "slug": "etat-civil",
    "title": "État civil"}
  ]
}

Il est possible de passer un paramètrefull=ondans l’adresse pour
obtenir pour chacune des catégories la liste des formulaires qu’elle contient,
dans une clé supplémentaire,forms.

Les formulaires d’une catégorie précise sont disponibles à l’URL/api/categories/slug/formdefs/.

GET https://www.example.net/api/categories/inscriptions/formdefs/

Comme pour la liste des formulaires en général, on peut ajouter l’argument?backoffice-submission=onà cette URL, pour n’obtenir que les
formulaires de la catégorie accessibles en saisie backoffice.

Rôles

La liste des rôles est disponible à l’URL/api/roles.

GET https://www.example.net/api/roles{"data":
  [
   {"id": 1,
    "text": "Gestionnaires formulaires",
    "slug": "gestionnaires-formulaires"},
   {"id": 2,
    "text": "Usagers privilégiés",
    "slug": "usagers-privilegies"}
  ]
}

Schéma de données d’un formulaire

Le schéma de données d’un formulaire est accessible à l’adresse/api/formdefs/slug/schema; l’appel doit obligatoirement
être signé ou réalisé avec un accès disposant des rôles de gestion sur le
formulaire.

{
    "name": "Newsletter",
    "only_allow_one": false,
    "enable_tracking_codes": true,
    "tracking_code_verify_fields": ["1"],
    "confirmation": true,
    "discussion": false,
    "fields": [
        {
            "label": "Nom",
            "required": true,
            "type": "string",
            "varname": "nom"
        },
        {
            "label": "Pr\u00e9nom",
            "required": false,
            "varname": "prenom"
        },
        {
            "label": "Adresse \u00e9lectronique",
            "type": "email",
            "varname": "email"
        }
    ],
    "workflow": {
        "name": "Workflow Newsletter",
        "id": "1",
        "last_modification_time": "2015-12-12T10:20:45",
        "statuses": [
            {
                "id": "1",
                "name": "Nouveau",
                "forced_endpoint": false
            },
            {
                "id": "2",
                "name": "En cours",
            },
            {
                "id": "3",
                "name": "Terminé",
            }
        ]
    }
}

Note de compatibilité : la même information est disponible en ajoutant/schemaà l’adresse publique du formulaire, par exemplehttp://www.example.net/inscriptions/newsletter/schema.

# Récupération des données d’un formulaire

Récupération des données d’un formulaire

Il s’agit ici d’une API permettant à un logiciel tiers de récupérer les données
associées à un formulaire complété; cet accès peut aussi bien être initié par
l’application tierce (mode pull) ou par w.c.s., à différents moments du
traitement d’un formulaire (mode push).

Mode « Pull »

L’exemple suivant récupère les données d’un formulaire d’inscription à une
newsletter.

GET https://www.example.net/api/forms/newsletter/16/

{
    "id": "16",
    "receipt_time": "2013-01-04T13:39:47",
    "last_update_time": "2013-01-04T13:41:21",
    "fields": {
        "email": "marc@example.net",
        "nom": "L.",
        "prenom": "Marc"
    },
    "geolocations": {
        "base": {
            "lat": 10,
            "lon": -12,
        }
    },
    "user": {
        "id": 1,
        "name": "Fred"
    },
        "status": {
            "id": "1",
            "name": "New",
            "endpoint": false
        },
        "data": {
            "creation_status": 200,
            "creation_response": {
                "dn": "cn=marc@example.net,ou=people"
            },
            "inscription_status": 200,
            "inscription_response": {
                "liste": "lalettre@example.com"
            }
        }
    },
    "roles": {
      "_receiver": [
        {
          "emails_to_members": false,
          "name": "Agents traitants",
          "text": "",
          "emails": [],
          "slug": "agents-traitants",
          "details": "",
          "id": "1",
          "allows_backoffice_access": true
        }
      ],
      "concerned": [
        {
          "id": "1",
        }
      ],
      "actions": [
        {
          "name": "test",
          "id": "1",
        }
      ]
    },
    "submission": {
      "backoffice": false,
      "channel": "Web"
    },
    "evolution": [
      {
        "status": "1",
        "time": "2013-01-04T13:39:49",
        "user": {
            "id": 1,
            "name": "Fred"
            "email": "fred@example.com",
            "NameID": ["123456"]
        },
        "parts": [
          {
            "type": "wscall-error",
            "summary": "description de l’erreur",
            "label": "appel du web-service XYZ",
            "data": "données reçues jusqu’à 10000 octets..."
          },
          {
            "type": "workflow-comment",
            "content": "commentaire"
          }
        ]
      },
    ]
}

Seuls les champs ayant unnom de variablesont exportés dansfields.

Les différentes géolocalisation associées au formulaire sont listées dans l’attributgeolocations. Pour l’instant il n’en existe qu’une toujours nomméebase.

Concernant les rôles et fonctions de workflow, les différents intervenants sont
listés dans l’attributroles, en différentes séries qui vont
dépendre de fonctions attachées au workflow.  Deux séries sont particulières,
la sérieconcernedreprend les rôles concernés par la demande et
la sérieactionsreprend les rôles disposant d’une capacité
d’action sur la demande.

L’information sur l’origine de la demande, si la saisie a eu lieu depuis le
backoffice et quel était le canal d’origine de la demande, est disponible
dans l’attributsubmission.

L’historique du formulaire, ses transitions dans différents statuts, est disponible dans l’attributevolution. Cette liste de dictionnaires contient l’instant de la transition
dans l’attributtime, le code du statut concerné dansstatuset
une description de l’utilisateur responsable de la transition dansuser. L’attribut
optionnelpartspeut contenir une liste de dictionnaires liés aux actions de workflow,
comme un commentaire ou une erreur lors de l’appel d’unweb service.

Il est bien sûr nécessaire de disposer des autorisations nécessaires pour
  accéder ainsi aux données d’un formulaire.

Mode « push »

Il est également possible pour un workflow d’être configuré pour transmettre
les données à une URL fournie par une application tierce. Un document JSON
(tel celui donné plus haut) est alors transmis en utilisant la méthode POST.

En retour, l’application tierce peut fournir un objet JSON qui sera enregistré
dans les données du workflow du formulaire (voir le dictionnaire "data" dans
l’exemple ci-dessus).

Les données d’un formulaire sont placées dans le champsfieldsde
la réponse. Les champs de type simple tels que « Texte », « Texte long » ou
« Courriel » sont vus en tant que chaîne de caractères :

(...)
    },
    (...)

Représentation d’un champ « Fichier »

Les champs de type « Fichier » sont exportés selon le schéma suivant :

(...)
        "photo": {
            "filename": "exemple.txt",
            "content_type": "text/plain",
            "content": "Q2VjaSBuJ2VzdCBwYXMgdW4gZXhlbXBsZS4=",
            "url": "https://.../"
        }
    },
    (...)

La valeur decontentest le contenu du fichier, encodé en base64.

Représentation d’un bloc de champs

Les blocs de champs sont exportés selon le schéma suivant, par exemple pour un
champ avec l’identifiantlivres:

(...)
        "livres": "Bloodless, Cauchemar",
        "livres_digests": ["Bloodless", "Cauchemar"],
        "livres_raw": [
            {"titre": "Bloodless", "auteur": "Valentine Gallardo"},
            {"titre": "Cauchemar", "auteur": "Pierre Ferrero"}
        ]
    },
    (...)

La valeur delivresest la forme textuelle de l’ensemble de la
sélection,livres_digestsreprend les gabarits de résumé des
différents éléments du bloc etlivres_rawcontient le détail de
ces éléments.

Liste de formulaires

La liste des demandes pour un formulaire donné est destinée à être utilisée par
un système de synchronisation. Elle ne retourne donc pour chaque demande que

effacées, puis effectuera pour chacune les actions nécessaires (pull, push,
etc.).

GET https://www.example.net/api/forms/inscriptions/list

[
    {
        "url": "https://www.example.net/inscriptions/1/",
        "last_update_time": "2015-03-26T23:08:45",
        "receipt_time": "2015-03-26T23:08:44",
        "id": 1
    },
    {
        "url": "https://www.example.net/inscriptions/3/",
        "last_update_time": "2015-03-27T12:11:21",
        "receipt_time": "2015-03-27T12:45:19",
        "id": 3
    }
]

Des paramètres peuvent être envoyés dans la requête pour filtrer le listing
voulu. Par défaut tout est retourné, indépendamment du statut, pour avoir une
liste limitée aux demandes non terminées, il faut utiliserfilter=pending:

GET https://www.example.net/api/forms/inscriptions/list?filter=pending

Il est également possible de filtrer sur le contenu des formulaires, à partir
des champs associés à un nom de variable et de type « Liste ».  Par exemple sur
un champ « Type » (nom de variabletype) dont une des valeurs
possibles est « gratuit » :

GET https://www.example.net/api/forms/inscriptions/list?filter-type=gratuit

Les opérateurs sont possibles sur ces filtres, par exemple pour filtrer sur les
valeurs qui ne seraient pas « gratuit » :

GET https://www.example.net/api/forms/inscriptions/list?filter-type=gratuit&filter-type-operator=ne

Opérateurs

eq | = | est égal
-----------------
ne | != | est différent
lt | < | est plus petit
lte | <= | est plus petit ou égal
gt | > | est plus grand
gte | >= | est plus grand ou égal
between |  | est entre
absent |  | n’a pas de valeur
existing |  | a une valeur présente
in |  | est dans
not_in |  | n’est pas dans
icontains |  | contient le texte
is_today |  | correspond à aujourd’hui
is_tomorrow |  | correspond à demain
is_yesterday |  | correspond à hier
is_this_week |  | est dans cette semaine

Pour les opérateurs qui demandent plusieurs valeurs (in, not_in, between),
  les valeurs doivent être passées séparées par le symbole|.

D’autres paramètres de filtres existent. Pour filtrer sur les demandes déposées
après une date donnée
(?filter-start=on&filter-start-value=2020-01-03),
ou avant une date donnée
(?filter-end=on&filter-end-value=2020-01-03) et de la même
manière sur les demandes modifiées après ou avant une date,
(?filter-start-mtime=on&filter-start-mtime-value=2020-01-03ou?filter-end-mtime=on&filter-end-mtime-value=2020-01-03).
Pour filtrer selon l’usager associé (?filter-user-uuid=XYZ) ou
selon l’appartenance d’un usager à une fonction particulière
(?filter-user-function=_mandataire&filter-user-uuid=XYZ).
Et pour filtrer selon l’agent qui a fait la saisie en backoffice
(?filter-submission-agent-uuid=XYZ).

Afin de faciliter certains traitementsbatch, il est possible de
demander que l’ensemble des données associées aux formulaires soient
retourné, plutôt qu’un jeu réduit adapté aux systèmes de synchronisation.
Pour ce faire, il suffit de passer un paramètrefull=ondans
l’adresse.

GET https://www.example.net/api/forms/inscriptions/list?full=on

À noter que pour ne pas alourdir l’export en modefull=on, le
contenu des champs de type « Fichier » n’est pas exporté.

Un paramètreinclude-actionspermet d’inclure (on) ou
non (off) la liste des actions globales et des déclencheurs de
sauts automatiques actuellement accessible via l'API à l'utilisateur qui
effectue la requête.

GET https://www.example.net/api/forms/inscriptions/list?include-actions=on

Données anonymisées

Les API « Liste de formulaires » et le mode Pull de récupération d’un formulaire acceptent un
paramètre supplémentaireanonymise. Quand celui-ci est présent des données anonymisées
des formulaires sont renvoyées et les contrôles d’accès sont simplifiés à une signature simple, il
n’est pas nécessaire de préciser l’identifiant d’un utilisateur.

GET https://www.example.net/api/forms/inscriptions/list?full=on&anonymiseGET https://www.example.net/api/forms/inscriptions/10/?anonymise

Par ailleurs, l’API « Liste de formulaires » accepte un paramètreinclude-anonymisedpermettant d’inclure (on) ou non
(off) les demandes anonymisées dans la liste :

GET https://www.example.net/api/forms/inscriptions/list?include-anonymised=on

Données de l’ensemble des formulaires

De manière similaire à l’API de récupération de la liste des demandes d’un
   formulaire, il est possible de récupérer l’ensemble des demandes de la
   plateforme, peu importe leurs types.

GET https://www.example.net/api/forms/

{
    "data": [
        {
            "url": "https://www.example.net/inscriptions/1/",
            "id": 1
        },
        {
            "url": "https://www.example.net/inscriptions/3/",
            "id": 3
        },
        {
            "url": "https://www.example.net/signalement/1/",
            "last_update_time": "2015-03-25T14:14:21",
            "receipt_time": "2015-03-25T14:48:20",
            "id": 1
        }
    ]
}

Des paramètres peuvent être envoyés dans la requête pour filtrer les résultats.
Il s’agit des mêmes paramètres que ceux du tableau global en backoffice.
Par exemple, pour avoir une liste limitée aux demandes terminées :

GET https://www.example.net/api/forms/?status=done

Le paramètrefulln’est pas pris en charge dans cette API; le
paramètreanonymisenon plus, les données l’étant déjà.

Données géolocalisées

Pour les formulaires définissant une prise en charge de la géolocalisation, il
est possible de récupérer les données au format GeoJSON, en faisant appel au
webservice/geojson.

GET https://www.example.net/api/forms/inscriptions/geojson{
    {
      "geometry": {
        "type": "Point",
        "coordinates": [
          1.23456789,
          50.1234567
        ]
      },
        "url": "http://example.net/backoffice/management/inscriptions/28/"
      }
    }
  ]
}

De manière identique aux appels précédents, des filtres peuvent être passés dans l’URL.

Les URL retournées pour les demandes pointent vers l’interface de gestion de celles-ci.

Il est également possible d’obtenir les informations géographiques de
l’ensemble des demandes :

GET https://www.example.net/api/forms/geojson

Une API existe pour déterminer l’existence d’un code de suivi et, le cas
échéant, découvrir la demande associée.

GET https://www.example.net/api/code/QRFPTSLR{"url": "...",
 "load_url": "...",
 "err": 0}

Dans l’attributurlse trouvera l’adresse native de la demande,
qui demandera authentification de l’utilisateur, et dans l’attributload_urlune adresse permettant de charger la demande sur la seule
foi de l’accès. Il est important d’utiliser cette adresse et de ne pas essayer
de la construire manuellement avec le code de suivi car elle peut évoluer. Pour
cette même raison elle devrait être utilisée immédiatement, sans être stockée.

En cas d’inexistence du code de suivi donné, une réponse avec un code de retour
404 est retourné.

Le cadre d’utilisation des codes de suivi devant être limité car ouvrant
  un accès important aux demandes associées, cette API est restreinte aux
  utilisations internes avec identification par signature.

# Lister et rechercher des utilisateurs

Lister et rechercher des utilisateurs

La liste des utilisateurs et la recherche des utilisateurs se fait avec un même WebService accessible à l'adresse/api/users/via la méthodeHTTP GET.

Nom | Sémantique | Valeurs permises | Exemple
---------------------------------------------
ordering | Permet de passer le nom d'un champ par lequel les réponses seront ordonnées, préfixé par-l'ordre est inversé | [-]date_joined, [-]modified, [-]first_name, [-]last_name | 
first_name | recherche exacte sur le prénom pour une valeur exacte |  | 
first_name__iexact | recherche exacte sur le prénom pour une valeur exacte en ignorant la casse |  | 
first_name__icontains | recherche exacte sur le prénom pour une sous chaîne en ignorant la casse |  | 
first_name__gte | recherche sur le prénom supérieure ou égale à la valeur |  | 
first_name__lte | recherche sur le prénom inférieure ou égale à la valeur |  | 
first_name__gt | recherche sur le prénom supérieure à la valeur |  | 
first_name__lt | recherche sur le prénom inférieure à la valeur |  | 
last_name+__iexact,__icontains,__gte,__lte,__gt,__lt | idem que pour le prénom mais avec le nom |  | 
modified__gte | recherche sur la date de dernière modification supérieure ou égale à la valeur | date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS | curl -X GET -u login:password https://authentic/api/users/?modified__gte=2017-03-28T00:00:00
modified__lte | recherche sur la date de dernière modification inférieure ou égale à la valeur | date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS | 
modified__gt | recherche sur la date de dernière modification supérieure à la valeur | date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS | 
modified__lt | recherche sur la date de dernière modification inférieure à la valeur | date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS | 
email | recherche sur le courriel exact |  | 
email__iexact | recherche sur le courriel exact en ignorant la casse |  | 
ou__slug | recherche dans une unité organisationnelle | identifiant court (slug) de l'unité organisationnelle | 
service-slug & service-ou | recherche des utilisateurs autorisés pour un service | service-slug prend pour valeur l'identifiant court (slug) du service et service-ou prend pour valeur l'identifiant court (slug) de l'unité organisationnelle dans laquelle est le service (« default » si le service est dans l'unité par défaut) | 

Le document retour est un objet/dictionnaire JSON, les résultats sont toujours paginés, chaque page a une taille de 100, le lien vers la page suivante est dans la propriété next et celui vers la page précédente dans la propriété previous. La propriété results contient la liste des résultats.

La liste des attributs dépend des attributs configurés dans le profil d'un utilisateur. Les attributs sont au minimum les suivant :

Propriété | Description | Format
uuid/sub | identifiant/identifiant OIDC de l'utilisateur | chaîne hexadécimal
first_name | prénom | chaîne quelconque
last_name | nom | chaîne quelconque
email | adresse de courriel | adresse de courriel
email_verified | statut de validation de l'adresse de courriel | true/false
modified | date de dernière modification | date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS
date_joined | date de création | date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS
is_active | statut d'activation du compte | true/false

Exemple

GET /api/users/ HTTP/1.1
Authorization: Basic xxx

200 Ok

{
    "next": "https://cresson.entrouvert.org/api/users/?cursor=XYZ",
    "previous": null,
    "results": [
        {
            "date_joined": "2017-07-25T08:41:40.998793Z",
            "email": "bob.leponge@france.fr",
            "email_verified": true,
            "first_name": "Bob",
            "is_active": true,
            "last_name": "Léponge",
            "modified": "2017-08-31T15:16:29.690864Z",
            "sub": "YTIBAQB9-fZcwZKt7k28P_towGlszsW0uDvxq5hd_zQOJhGBJ1qP3FYajF-JUY6ug_Ekw8k",
        },
        ...
    ]
}

400 | Le format de la requête est invalide (paramètre interdit ou avec une valeur invalide) | Un document JSON décrivant les erreurs rencontrées
403 | Permission non accordée d'effectuer l'action | 

Pagination des résultats

La réponse d'un cas passant contient au maximum 100 utilisateurs. Si le resultat est supérieur à 100 utilisateurs, le résultat se découpe en plusieurs pages et la réponse à la requête initiale ne contient que les 100 premiers utilisateurs de la liste. Il faut ensuite parcourir les pages suivantes en interrogeant l'url spécifiée dans le champs next de la réponse et cela jusqu'à ce que le champs next soit à null.

200 Ok

{
    "next": "https://moncompte.grandlyon.com/api/users/?cursor=XYZ",
        {
...

Le champs next indique qu'il y a une autre page de résultat que l'on obtient par la requête :

GET /api/users/?cursor=XYZ HTTP/1.1

200 Ok

{
    "next": null,
    "previous": "https://moncompte.grandlyon.com/api/users/?cursor=ABC",
        {
...

Filtrage selon un rôle

Pour limiter les résultats aux utilisateurs disposant d’un rôle, il faut utiliser l’API permettant delister les membres d'un rôle, elle expose les mêmes paramètres et le même fonctionnement que l’API décrite sur cette page.

# Lister les membres d'un rôle

Lister les membres d'un rôle

La liste et la recherche des utilisateurs membres d’un rôle se fait avec un même WebService accessible à l'adresse /api/roles/<role-uuid>/members/ via la méthode HTTP GET.Les paramètres acceptés sont les mêmes que ceux de l'API pour lister et rechercher les utilisateurs.

L'appartenance d'un utilisateur à un rôle peut-être testé avec ce WebService accessible à l'adresse /api/roles/<role-uuid>/members/<uuid-user>/ via la méthode HTTP GET.

Ces deux WebServices acceptent un paramètre nested (faux par défaut) qui permet d'inclure les membres indirects dans les résultats.

nested | Permet de retourner également les utilisateurs inclus récursivement, lorsque le rôle contient également les membres d'autres rôles | false (défault), true, 0, 1 | 

Les formats de retour sont les mêmes que ceux de l'API pour lister et rechercher les utilisateurs.

# Lister les rôles

Lister les rôles

La liste des rôles se fait avec un même WebService accessible à l'adresse/api/roles/via la méthodeHTTP GET. Il n'est pas possible de filtrer les résultats selon certains attributs du rôle.

uuid | rechercher un rôle par son identifiant | chaîne hexadécimale | 9c05a50defd6412a9580a455e6c69cd0
name | recherche exacte sur le nom pour une valeur exacte | chaîne quelconque | Administrateur
name__iexact | recherche exacte sur le nom pour une valeur exacte en ignorant la casse | chaîne quelconque | administrateur
name__icontains | recherche exacte sur le nom pour une sous chaîne en ignorant la casse | chaîne quelconque | ministr
name__startswith | recherche exacte sur le début du nom | chaîne quelconque | Admin
slug | recherche exacte sur l'identifiant court (slug) pour une valeur exacte | chaîne quelconque | _a2-manager
slug__iexact | recherche exacte sur l'identifiant court (slug) pour une valeur exacte en ignorant la casse | chaîne quelconque | _A2-Manager
slug__icontains | recherche exacte sur l'identifiant court (slug) pour une sous chaîne en ignorant la casse | chaîne quelconque | Manage
slug__startswith | recherche sur le début de l'identifiant court (slug | chaîne quelconque | _a2-
limit | nombre maximum d'enregistrements retournés | entier | 50
offset | position du premier enregistrement à retourner relativement à l'ensemble total des enregistrement concernés par la requête | entier | 100
ordering | Permet de passer le nom d'un champ par lequel les réponses seront ordonnées, préfixé par-l'ordre est inversé | nom d'un attribut (name, slug) | -
admin | Filtre (true) ou exclut (false) les rôles d'administrations, ceux dont le slug commence par _a2-manager | true ou false | true
internal | Filtre (true) ou exclut (false) les rôles internes, ceux dont le slug commence par un _ | true ou false | true

Les attributs sont les suivants :

name | nom | chaîne quelconque
ou | unité organisationnelle | chaîne quelconque
slug | identifiant court | chaîne quelconque
uuid | identifiant | chaîne hexadécimal

Exemple

GET /api/roles/ HTTP/1.1

200 Ok

{
    "next": "https://foo.com/api/roles/?limit=10&offset=10",
         {                                                                                          
            "name": "Foo",                            
            "ou": "default",                          
            "slug": "foo",                         
            "uuid": "99aa781541e84b51b47c9e379bc282a8"
        },                                            
        {                    
            "name": "Bar",                           
            "ou": "default",                      
            "slug": "bar",                         
            "uuid": "38aa46545f11430a82c4efcf435bd8e7"
        }
     .....
    ]
}

# Ajouter un utilisateur dans un rôle

Ajouter un utilisateur dans un rôle

La création d'un role se fait avec le WebService accessible à l'adresse/api/roles/<role_uuid>/members/<user_uuid>/ via la méthodeHTTP POST.

Paramètres : aucun paramètre

Exemple

POST /api/roles/22de997677fa4ec5adbe2c6e505862fa/members/12e4a3f2fdc241968a102bcbf22f4edf/  HTTP/1.1 

201 Created

{
    "detail": "Utilisateur ajouté au rôle",
    "result": 1
}

# Modifier un rôle

Modifier un rôle

La création d'un rôle se fait avec le WebService accessible à l'adresse/api/roles/<uuid>/via la méthodeHTTP PATCH ou PUTen soumettant un document JSON décrivant le rôle à créer.

name | nom | non | chaîne quelconque
slug | identifiant court | non | chaîne quelconque
ou | identifiant d'une collectivité | non | chaîne quelconque

Exemple

PATCH /api/roles/3b8e9fc0f6ae4731b5bbec2812f7d370/ HTTP/1.1 

{
    "name": "Fooaa" 
}

200 OK

{
    "name": "Fooaa",
    "ou": "default",
    "slug": "foo",
    "uuid": "3b8e9fc0f6ae4731b5bbec2812f7d370"
}

# Supprimer un rôle

Supprimer un rôle

La suppression d'un rôle se fait avec le WebService accessible à l'adresse/api/roles/<uuid>/via la méthodeHTTP DELETE.

Aucun paramètre.

Exemple

DELETE /api/roles/8e7f200b4bb447fa8a91cd03c0f0ade3/ HTTP/1.1 

204 No Content

# Supprimer un utilisateur

Supprimer un utilisateur

La suppression d'utilisateur se fait avec le WebService accessible à l'adresse/api/users/<uuid>/via la méthodeHTTP DELETE.

Exemple

DELETE /api/users/8e7f200b4bb447fa8a91cd03c0f0ade3/ HTTP/1.1 

# Supprimer les relations d’héritage d’un rôle

Supprimer les relations d’héritage d’un rôle

La suppression d’une relation de parenté à un rôle cible se fait en connaissant l’UUID de ce rôle.Comme pour l’ajout d’une relation d’héritage, cette suppression peut être effectuée soit en mentionnant l’UUID, le slug, ou le nom du rôle parent (pour cette dernière option, le nom doit être unique).

Cette suppression se fait via le verbe DELETE sur l’URI

/api/roles/<UUID du rôle cible>/relationships/parents/

en mentionnant en payload DELETE, soit l’UUID

{"parent": {"uuid": "abc"}}

soit le slug

{"parent": {"slug": "role-lambda"}}

soit le nom

{"parent": {"name": "Role Lambda"}}

du rôle parent.

En retour, l’endpoint renvoie la liste des rôles parents directs existants pour ce rôle une fois la suppression effectuée.

Si cet appel doit être fait depuis w.c.s., par exemple à l’aide de l’action Webservice, les données de payload doivent être mentionnées en gabarit Django et donc il n’est pas possible de construire un dictionnaire en valeur du dictionnaire principal de payload (c’est-à-dire qu’aucune imbrication n’est possible).Dans ce cas, il convient d’utiliserla syntaxe spécifiqueà Authentic pour reconstruire des données composées à partir de données “à plat” (comportement “unflatten” de l’API).Par exemple, un appel depuis w.c.s. en mentionnant le slug du rôle parent comporterait le payload DELETE suivant :

{"parent/slug": "role-lambda"}

(À noter que "role-lambda" peut alors correspondre à la valeur d’une variable w.c.s. dans l’interface clé-valeur du définition du payload d’un appel Webservice w.c.s.)

# Créer un rôle

Créer un rôle

La création d'un rôle se fait avec le WebService accessible à l'adresse/api/roles/via la méthodeHTTP POSTen soumettant un document JSON décrivant le rôle à créer.

name | nom | oui | chaîne quelconque

Exemple

POST /api/roles/ HTTP/1.1 

{
    "name": "Foo" 
}

{
    "name": "Foo",
    "uuid": "99aa781541e84b51b47c9e379bc282a8"
}

HTTP/1.1 400 BAD REQUEST

{
    "errors": {
        "name": [
            "Ce champ est obligatoire." 
        ]
    },
    "result": 0
}

Créer ou obtenir un rôle

Il est également possible d'effectuer l'opération hybride "get or create" : recherche d'un rôle selon certains attributs et création du rôle uniquement si la recherche échoue. L'opération se fait sur la même l'adresse que la création d'un rôle/api/roles/via la méthodeHTTP POSTen soumettant un document JSON décrivant le rôle à rechercher/créer. Par rapport à la création simple il faut ajouter un ou plusieurs paramètres get_or_create=nom-de-l'attribut dans la query string, pour indiquer sur quels attributs doit se baser la recherche.

Exemple

POST /api/roles/?get_or_create=name HTTP/1.1 

{
}

200 OK

{     
      "name": "Foo",
      "ou": "default",
      "slug": "foo",
      "uuid": "99aa781541e84b51b47c9e379bc282a8"
}

Mettre à jour ou obtenir un rôle

Sur le même principe que le "get or create", il est possible d'effectuer l'opération hybride "update or create" : recherche d'un rôle selon certains attributs avec création du rôle si la recherche échoue et mise à jour du rôle si la recherche réussit. Il faut ajouter un ou plusieurs paramètres update_or_create=nom-de-l'attribut dans la query string, pour indiquer sur quels attributs doit se baser la recherche.

Exemple :

POST /api/roles/?update_or_create=name HTTP/1.1 

{
    "name": "Foo",
    "slug": "foobar" 
}

200 OK

{
    "ou": "default",
    "slug": "foobar",
    "uuid": "99aa781541e84b51b47c9e379bc282a8"
}

# Créer un utilisateur

Créer un utilisateur

La création d'utilisateur se fait avec le WebService accessible à l'adresse/api/users/via la méthodeHTTP POSTen soumettant un document JSON décrivant l'utilisateur à créer. Tous les attributs définis pour un profil d'utilisateur peuvent être définis dès la création.

first_name | prénom | oui | chaîne quelconque
last_name | nom | oui | chaîne quelconque
email | adresse de courriel | oui | courriel
username | nom d'utilisateur | non | chaîne quelconque
send_registration_email | Envoyer un courriel à l'utilisateur contenant un lien lui permettant de saisir son mot de passe et finaliser la création de compte. Cette option n'a de sens que si l'attribut email est renseigné | non | true
send_registration_email_next_url | Adresse sur laquelle rediriger l'utilisateur après la phase d'enregistrement. Cette option n'a d'intérêt que si l'option send_registration_email est activée. | non | URL valide
ou | identifiant (slug) de l'OU (Organizational Unit, collectivité) | non | slug d'une OU existante

Exemple

POST /api/users/ HTTP/1.1 

{
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "gender": 1,
    "birthdate": "1981-06-01",
    "birthplace": "Marseille",
    "birthcountry": "France",
    "preferred_username": "john",
    "address_city": "New-York",
    "send_registration_email": "True",
    "send_registration_email_next_url": "http://www.entrouvert.com" 
}

{
        "sub": "8e7f200b4bb447fa8a91cd03c0f0ade3",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "date_joined": "2017-03-20T13:16:44.991343Z",
        "modified": "2017-03-20T13:16:44.991343Z",
        "is_active": true
}

{
        "last_name": [
        ]
    },
}

Créer ou obtenir un utilisateur

Il est également possible d'effectuer l'opération hybride "get or create" : recherche d'un utilisateur selon certains attributs et création de l'utilisateur uniquement si la recherche échoue. L'opération se fait sur la même l'adresse que la création d'utilisateur/api/users/via la méthodeHTTP POSTen soumettant un document JSON décrivant l'utilisateur à rechercher/créer. Par rapport à la création simple il faut ajouter un ou plusieurs paramètres get_or_create=nom-de-l'attribut dans la query string, pour indiquer sur quels attributs doit se baser la recherche.

Exemple :

POST /api/users/?get_or_create=email HTTP/1.1 

{
    "last_name": "Doe" 
}

200 OK

{
}

Mettre à jour ou obtenir un utilisateur

Sur le même principe que le "get or create", il est possible d'effectuer l'opération hybride "update or create" : recherche d'un utilisateur selon certains attributs avec création de l'utilisateur si la recherche échoue et mise à jour de l'utilisateur si la recherche réussit. Il faut ajouter un ou plusieurs paramètres update_or_create=nom-de-l'attribut dans la query string, pour indiquer sur quels attributs doit se baser la recherche.

Exemple :

POST /api/users/?update_or_create=email HTTP/1.1 

{
}

200 OK

{
}

# Modifier un utilisateur

Modifier un utilisateur

La modification d'utilisateur se fait avec le WebService accessible à l'adresse/api/users/<uuid>/ via la méthodeHTTP PUT ou PATCHen soumettant un document JSON décrivant les attributs à modifier.

Exemple

PATCH /api/users/8e7f200b4bb447fa8a91cd03c0f0ade3/ HTTP/1.1 

{
    "email": "john@doe.com" 
}

200 OK

{
        "uuid": "8e7f200b4bb447fa8a91cd03c0f0ade3",
        "email": "john@doe.com",
}

# Ajouter des relations d’héritage entre rôles

Ajouter des relations d’héritage entre rôles

L’ajout d’une relation de parenté à un rôle cible se fait en connaissant l’UUID de ce rôle.On peut procéder à cet ajout soit en mentionnant l’UUID, le slug, ou le nom du rôle parent (pour cette dernière option, le nom doit être unique).

Cet ajout se fait via le verbe POST sur l’URI

en mentionnant en payload POST, soit l’UUID

soit le nom

En retour, l’endpoint renvoie la liste des rôles parents directs pour le rôle, comme c’est le cas del’endpoint de liste des parents.

Si cet appel doit être fait depuis w.c.s., par exemple à l’aide de l’action Webservice, les données de payload doivent être mentionnées en gabarit Django et donc il n’est pas possible de construire un dictionnaire en valeur du dictionnaire principal de payload (c’est-à-dire qu’aucune imbrication n’est possible).Dans ce cas, il convient d’utiliserla syntaxe spécifique à Authenticpour reconstruire des données composées à partir de données “à plat” (comportement “unflatten” de l’API).Par exemple, un appel depuis w.c.s. en mentionnant le slug du rôle parent comporterait le payload POST suivant :

{"parent/uuid": "abc"}

(À noter que "abc" peut alors correspondre à la valeur d’une variable w.c.s. dans l’interface clé-valeur du définition du payload d’un appel Webservice w.c.s.)

# Forcer le changement de mot de passe d’un utilisateur

Forcer le changement de mot de passe d’un utilisateur

L’endpoint/api/users/<uuid>/ atteint via les méthodesHTTPde modification de la ressource ciblée (POST, PUT, PATCH) accepte un paramètre force_password_reset permettant de forcer le changement de mot de passe de l’usager à sa prochaine connexion.

Exemple

POST /api/users/8e7f200b4bb447fa8a91cd03c0f0ade3/ HTTP/1.1 

{
    "email": "john@doe.com",
    "first_name": "john",
    "last_name": "doe",
    "force_password_reset": true
}

Lors de sa prochaine connexion, l’usager créé ou modifié ici se verra redirigé vers une page lui imposant de définir un nouveau mot de passe.

À noter que cette option force_password_reset peut fonctionner conjointement aux optionsget_or_createetupdate_or_create.

# Gestion en masse des utilisateurs membres  d'un rôle

Gestion en masse des utilisateurs membres  d'un rôle

Plutôt que de procéder utilisateur par utilisateur, il y a possibilité de faire des opérations sur un ensemble d'utilisateurs avec le WebService accessible à l'adresse/api/roles/<role_uuid>/relationships/members/.

Paramètres : une liste d'utilisateurs identifiés par leur uuid

Exemple de paramètres

{
    "data": [
        {"uuid": "6805d2b4f4ab4b6c94a28588a46bb40a"},
        {"uuid": "12e4a3f2fdc241968a102bcbf22f4edf"}
    ]
}

Ajouter des utilisateurs dans un rôle

Via la méthode POST.

Exemple

POST  /api/roles/debb96a7ff5d486fb323e3edbeb8f0f7/relationships/members/  HTTP/1.1 

{
    "data": [
    ]
}

HTTP/1.1 201 Created

{
    "detail": "Utilisateurs ajoutés au rôle avec succès",
    "result": 1
}

Définir l'ensemble des utilisateurs appartenant à un rôle

Via la méthode PATCH ou PUT. Cette méthode ajoute les utilisateurs passés en paramètre dans le rôle correspondant. Les utilisateurs déjà présents dans le rôle mais qui ne sont pas passés en paramètre seront retirés du rôle.

Exemple

PATCH  /api/roles/debb96a7ff5d486fb323e3edbeb8f0f7/relationships/members/  HTTP/1.1 

{
    "data": [
    ]
}

{
    "detail": "Utilisateurs assignés au rôle avec succès",
}

# Liste les relations d’héritage d’un rôle

Liste les relations d’héritage d’un rôle

Connaissant l’UUID d’un rôle, vous pouvez obtenir la liste de ses rôles parents en appelant l’URI

/api/roles/<UUID du rôle>/relationships/parents/

(vous devez bien sûr vous authentifier et disposer des droits de liste de rôles, nécessaires à l’appel de cet endpoint).

Par exemple, pour un rôle d’UUID "abc" ayant deux autres rôles pour parent, l’appel

/api/roles/abc/relationships/parents/

renvoie les données JSON suivantes

{
    "err": 0,
    "data": [
        {
            "parent": {
                "uuid": "def",
                "name": "Role 1",
                "slug": "role-1",
                "ou": null,
                "service": null
            },
            "direct": true
        },
        {
                "uuid": "ghi",
                "name": "Role 2",
                "slug": "role-2",
            },
        }
    ]
}

Un paramètre de querystring ‘all’ permet par ailleurs d’obtenir la liste de tous les parents (directs ou indirects).

# Retirer un utilisateur d'un rôle

Retirer un utilisateur d'un rôle

Retirer un utilisateur d'un rôle se fait avec le WebService accessible à l'adresse/api/roles/<role_uuid>/members/<user_uuid> via la méthodeHTTP DELETE.

Exemple

DELETE /api/roles/22de997677fa4ec5adbe2c6e505862fa/members/12e4a3f2fdc241968a102bcbf22f4edf/  HTTP/1.1 

200 Ok

{
    "detail": "Utilisateur retiré du rôle",
}

# Changer de statut automatiquement

Changer de statut automatiquement

L'action « Saut automatique » suscite la transition d'un statut à un autre en fonction d'un critère que l'administrateur fonctionnel peut fixer.

Si plusieurs de ces critères sont combinés, ils devront tous être remplis pour que la transition ait lieu.

Il est possible d'ajouter un marqueur sur le statut courant lors d'un saut de workflow, pour permettre ensuite un saut de retour direct vers celui-ci.  L'objectif est de permettre d'afficher un bouton « Revenir au statut précédent » aux agents traitant lorsque l'on souhaite leur permettre une action de ce type plutôt qu'un retour vers un statut particulier et fixe. Pour activer le marqueur : dans les paramètres de l'action de saut, onglet « Avancé », cocher la case « Poser un marqueur qui permettra de revenir au statut actuel »..

Édition

Quel que soit le critère qui déterminera le changement automatique du statut, l'administrateur fonctionnel doit, dans un premier temps, sélectionner au sein d'une liste déroulante, le statut de destination que le saut automatique configure.

Condition

Le changement de statut peut être conditionné par une expression Django, à l'instar d'uneNouvelle pagede formulaire dont l'affichage dépend d'unecondition.

Un saut de statut peut aussi être déclenché par la valeur d'un des champs du formulaire de la demande saisie par l'usager ou par la valeur d'un des champs du profil de l'usager.

Attention : la condition déclenchant ou pas le saut est calculée uniquement lors de l'entrée de la demande dans le statut. Pour qu'elle soit réévaluée périodiquement, il faut ajouter unsaut avec expiration.

Imaginons une condition pour l'action saut automatique qui soitform_var_lu_par_tartenpion == "Oui".Quand la demande arrive dans le statut en question, tartenpion n'a pas lu,form_var_lu_par_tartenpion == "Non", le saut n'est pas exécuté.Et il ne le sera jamais s'il n'y a pas une expiration qui oblige à réévaluer la condition plus tard.

L'expiration permettra de réévaluer la condition périodiquement, et de voir à un moment, que la donnée de traitement form_var_lu_par_tartenpion est passée à "Oui", le saut automatique sera alors exécuté.

Un saut vers un statut peut être provoqué par un système externe, tel que le système de paiement de la collectivité, grâce à uneAPI autorisant le traitement d'une demande d'usager.

Les utilisateurs autorisés à déclencher doivent être spécifiés.

Expiration

Un délai d'expiration peut également être configuré pour automatiser un changement de statut. Sans expiration, la condition de saut n'est pas réévaluée périodiquement, mais uniquement à l'entrée dans le statut.

Exemples d'usage du critère « Expiration » :pour automatiser un saut vers le statut « Relance », prévu pour signaler à l'agent traitant que la demande tarde à être traitée, l'administrateur fonctionnel peut estimer une durée de traitement critique à partir de laquelle il considère utile de relancer le gestionnaire.

Options

Onglet Avancé > champ Identifiant

Lorsqu'un saut a l'identifiant 'foo', on peut écrire des conditions qui vérifient :

* que la demande est passée à un moment par ce saut :"foo" in form_jumps;
* que la demande est arrivée sur un statut via ce saut :form_latest_jump == "foo"Remarque: Cette vérification fonctionne uniquement si tous les sauts menant à ce statut possèdent un identifiant.

* Studio
* Les tutos

# Les éléments graphiques de base à fournir

Les éléments graphiques de base à fournir

1- Le logo de la collectivité

Élément attendu : le fichier image du logo de la collectivité.Il sera affiché à la fois en mode desktop et mobile, ainsi son poids doit être optimisé et sa version choisie pour rester lisible même dans un petit format.Format : .jpg, .png, .svg

2- Les couleurs

Élément attendu : une couleur principale et une ou deux couleurs secondaires.Une ressource bien utile :https://htmlcolorcodes.com/fr/Format : code hexadécimal

3- Les polices de caractères

Élément attendu : une police principale et une police secondaire.Utiliser de préférence une police de caractère sous licence libre. Sinon, il est nécessaire de transmettre les fichiers fonts appropriés et de s'assurer que la collectivité possède bien les droits d'utilisation pour une diffusion web.

4- Les styles des éléments de texte

Élément attendu : descriptif (police, taille du texte et couleur) pour les éléments suivants :

* les titres (H1, H2, H3, H4) ;
* le contenu : body ;
* les liens (un lien normal, non visité ; un lien survolé par la souris ; un lien qui a déjà été visité) ;

Étapes d’un formulaire

La page formulaire va reprendre automatiquement les styles qu’Entr’ouvert aura défini au niveau typographique et chromatique.

Les étapes d‘un formulaire peuvent être affichées à gauche  ou à droite du formulaire.

Disposition des boutons de navigation

Éternel débat (c’est notre serpent de mer ;-), la collectivité peut choisir si elle le souhaite l'ordre des boutons Suivant / Précédent ou inversement.

Nom des agents dans l'historique

Nativement Publik affiche le nom de l’agent dans l’historique de la demande, conformément au « Code des relations entre le public et l'administration ».Toutefois, si une collectivité souhaite désactiver l'affichage du nom, il est possible de le faire et cela s'appliquera, systématiquement, à toutes les démarches.

Ce qui n'est pas modifiable

Les champs de formulaire répondent à la logique générale de la charte graphique (typo, espacement…).toutefois, nous attirons votre attention sur le fait que certaines fonctionnalités ne sont pas possibles dans Publik.

* pas de « placeholder » dans les champs de formulaire (que ce soit les libellés de champs ou des textes d’aide) ;
* les libellés des champs sont forcément placés au dessus des champs ;
* pas de notion de "groupe de champs" qui permettrait deregrouper des champs dans un même formulaire pour leurattribuer une mise en forme particulière ;
* pas d'intégration de code « javascript » dans le champ commentaire des formulaires.

Exemples d'intégrations graphiques natives

Clisson Sèvre et Maine AggloAffichage desktop / affichage mobile

ArpajonAffichage desktop / affichage mobile

Header¶

Bandeau

L’en-tête du portail citoyen peut intégrer le logo et une image de fond. Les éléments de connexion (en haut, à droite) sont fixes.

Menu principal

Ce menu est composé des « entrées de pages » paramétrées dans Publik. Le menu peut renvoyer vers des pages éditoriales gérées dans Publik ou peut être de simples liens vers un autre site. Le menu sera positionné en dessous du bandeau.

À noter qu’il n’est pas possible d’insérer de Fil d’Ariane.

Pied de page¶

Le pied de page est fixe sur l’ensemble du site, il est composé d’une cellule texte. Entr’ouvert définira la couleur du fond du pied de page et la couleur du texte. Le texte en lui-même sera éditable par vous dans le backoffice.

Remarque : ne mettez pas de liens vers les réseaux sociaux (ni dans le pied de page, ni ailleurs), Publik n’est pas un site de communication mais un outil de GRU, il se veut respectueux de la vie privée.

Barre latérale¶

Les templates de Publik permettent de construire des pages en utilisant en standard les compositions suivantes, soit :

* deux colonnes ;
* deux colonnes et une barre latérale ;
* une colonne ;
* une colonne et une barre latérale.

Il est possible de personnaliser les élements suivants de la barre latérale :

* la position (droite ou gauche) ;
* la largeur (en pixel).

Zone de recherche¶

Publik peut intégrer une zone de recherche. Celle-ci est obligatoirement positionnée dans une zone « administrable », c’est-à-dire dans une des colonnes composant la zone de contenu (et donc ni dans le header, le menu ou le footer).Elle est souvent positionnée en barre latérale.

# Les "cookies" ou "traceurs"

Les "cookies" ou "traceurs"

Chaque module logiciel de Publik pose un cookie de session. Sa durée de vie est déterminée par la collectivité (durée des sessions des utilisateurs). Le fournisseur d'identité pose aussi un cookie qui persiste jusqu'à la fermeture du navigateur ou la fermeture de la session en cours.

Aucun de ces cookies ne nécessite de déclaration (ils ne servent pas au traçage des activités de l'utilisateur, mais seulement à des fins techniques d'authentification et de sécurité).

Pour approfondir :

Conseil de la CNIL :

[> Cookies et traceurs : comment mettre mon site web en conformité ?](https://www.cnil.fr/fr/cookies-et-traceurs-comment-mettre-mon-site-web-en-conformite)

Si Matomo est activé, des statistiques de fréquentation sont également collectées, ces statistiques sont réalisées en anonymisant les adresses IP. Matomo est configuré pour être exempté de consentement en conformité avec la réglementation.

Liste des cookies ou traceurs utilisés par Publik

sessionid-

Chaque module logiciel de Publik pose un cookie de session, dont le nom commence par "sessionid-" puis un suffixe généré pour chaque instance de l'application. Sa durée de vie est déterminée par la collectivité (durée des sessions des utilisateurs).

csrftoken-

Des cookies dont le nom commence par "csrftoken-" peuvent également être posés, pour assurer la sécurité des modules. Ces cookies contiennent un jeton opaque.

a2-opened-session-nnnnnn

Le fournisseur d'identités pose un cookie nommé "a2-opened-session-nnnnnn" sur la racine des domaines pour annoncer aux autres services qu'une session existe, ce cookie persiste jusqu'à la fermeture du navigateur ou la fermeture de la session en cours (i.e. il est supprimé à la déconnexion comme le cookie de session), il ne contient rien permettant de suivre l'utilisateur.

cookie-test

Le fournisseur d'identités pose aussi un cookie "cookie-test" pour vérifier le bon fonctionnement des cookies (contient juste la chaine "1").

a2_just_logged_out

Selon les configurations il peut également poser un cookie "a2_just_logged_out" pour ne pas rejouer une connexion automatique (ici aussi, quand il est posé c'est uniquement avec la chaine "1" comme valeur).

Matomo

Si jamais le module Matomo de Publik est activé, des cookies préfixés parpklui sont associés. Le module Matomo est configuré selon les préconisations de la CNIL et il est exempté de consentement, les statistiques récoltées sont réalisées en anonymisant les adresses IP.

* https://www.cnil.fr/sites/default/files/typo/document/Configuration_piwik.pdf
* https://www.cnil.fr/fr/solutions-pour-les-cookies-de-mesure-daudience

Cette action n'est disponible que lorsque l'on a, au préalable, configuré lesniveaux de criticité.

Elle permet de faire varier la criticité :

* vers le niveau supérieur par rapport au niveau en cours
* vers le niveau inférieur par rapport au niveau en cours
* vers un niveau particulier de criticité, indiqué explicitement

Il peut être intéressant de créer, par exemple, un statut « Augmentation de la criticité » dans lequel on aura uniquement deux actions : une action de modification de la criticité vers le niveau supérieur et une action de changement de statut automatique vers le statut d'origine. Dans le statut d'origine si on peut alors avoir une action de changement de statut baptisé « augmenter la criticité » et qui pointe vers le statut « Augmentation de la criticité ». Un clic sur le bouton correspondant aura ainsi pour effet d'augmenter la criticité en restant sur le même statut.

* Studio
* Les tutos

# Suppression du code de suivi

Suppression du code de suivi

Cette action permet de supprimer le code de suivi associé à une demande pour renforcer la sécurité. Il existe un réglage "Remplacer par un nouveau code de suivi".

* Studio
* Les tutos

# Création d'une demande

Création d'une demande

L'action « Création d'une demande » permet de créer une demande ou un brouillon de demande à partir de la demande qui est en train d'être traitée.

Le numéro et le résumé de la sous-demande créée sont affichés dans l'historique de la demande mère.

Édition

Les différentes options et paramétrages :

* « Créer en tant que brouillon » : si coché, la nouvelle demande sera initialisée en brouillon, l'usager devra la compléter puis la valider. Utilisé quand des informations complémentaires sont nécessaires.
* « Formulaire » : choisir la démarche à initialiser.
* «Correspondance automatique des champs par leurs identifiants» : si coché, permet de préremplir les champs qui portent le même identifiant avec la saisie effectuée dans la démarche en cours en traitement (par exemple, form_var_nom,...)
* «Saisie backoffice» : Permet d'enregistrer la demande comme une demande saisie en backoffice.
* « Utilisateur associé à la demande » permet de garder l'utilisateur originel (celui de la demande/fiche mère), d'enlever cet utilisateur ou encore de le remplacer par un autre défini par ungabarit.
* «Conserver les infos de soumission» : si coché, la nouvelle demande reprend certaines informations de la demande initiale (contexte, canal,...). Cette option concerne la saisie back-office.
* « Identifiant » : si l'identifiant est renseigné, on peut accéder aux informations du formulaire "enfant", par exemple {{form_links_identifiant_form_url}}.
* «Inclure la nouvelle demande dans l’historique du formulaire» : si coché, Publik ajoute dans l'historique un lien vers la nouvelle demande et le gabarit du résumé de la demande concernée.

Une fois que le formulaire est sélectionné et que l'action est enregistrée, une liste des champs apparaît pour permettre le préremplissage des champs du nouveau formulaire avec les valeurs saisies dans la démarche en cours de traitement.

Mettre en pratique

Consulter le tuto« Mettre en place la création d'une demande avec préremplissage des données et des pièces justificatives »

* Studio
* Les tutos

# Action de workflow « Commentaire »

Action de workflow « Commentaire »

L'action Commentaire sera prochainement

[dépréciée](https://doc-publik.entrouvert.com/admin-fonctionnel/elements-deprecies/)

. Dès à présent, elle peut être avantageusement remplacée par l'action

[Formulaire](https://doc-publik.entrouvert.com/admin-fonctionnel/fabrique-de-workflows/les-actions-de-workflow/elements_afficher-un-formulaire/)

, qui permet de créer un formulaire de workflow avec notamment des champs de type texte long. Ces champs peuvent ensuite être affichés dans l'historique grâce à l'action

[Message dans l'historique](https://doc-publik.entrouvert.com/admin-fonctionnel/fabrique-de-workflows/les-actions-de-workflow/elements_enregistrer-dans-le-journal/)

.

L'action« Commentaire » permet qu'une demande d'usager en cours de traitement puisse faire l'objet d'observations.

Si un identifiant est donné au commentaire, ce dernier est disponible dans une variable du type {{comment_identifiant}}.

Via cette variable, le commentaire peut être utilisé dans les étapes ultérieures du worfklow pour alimenter des documents, des mails, etc.

Pour qu'un commentaire soit utilisable, il doit être enregistré. Pour cela il faut cliquer sur le bouton « Ajouter le commentaire » (ou autre libellé configuré en éditant l'action).

Il est aussi possible d'utiliser cette action en conjonction avec un «Saut à la soumission».

Édition

Les étapes d'édition de l'action « Commentaire » sont les suivantes :

* Indiquer le libellé du commentaire.
* Préciser le texte du bouton de validation d'un commentaire.
* Ajouter une mention susceptible de guider l'utilisateur habilité à commenter une demande d'usager.
* Pointer, au sein d'une liste déroulante, chaque fonction, et/ou rôle d'utilisateur habilité(s) à commenter une demande d'usager.
* Saisir le « Nom de variable » du champ « Commentaire ».
* Rédiger un texte informatif pour expliciter aux agents confrontés au champ « Commentaire » ce qu'induit l'ajout d'un commentaire.

* Studio
* Les tutos

# Envoyer un SMS

Envoyer un SMS

L'action « SMS » a pour effet d'automatiser l'envoi d'un sms. Elle est renseignée avec un gabarit contenant un numéro de téléphone ou en indiquant que c'est le demandeur qui recevra le SMS.

Un champ prérempli avec le mobile de l'usager sera considéré comme étant le numéro du demandeur.

Édition

Les étapes d'édition de l'action « SMS » sont les suivantes :

* Saisir le numéro de téléphone de l'utilisateur à qui est destiné le SMS  (cela ne peut pas être directement un champ du profil de l'usager comme pour envoyer un courriel), il est donc impératif de prévoir un champ texte dans le formulaire du type « Numéro de téléphone sur lequel vous souhaitez-recevoir un sms », champ qui peut, lui, être prérempli depuis les données du compte.Publik assure la gestion des différents formats de numéros de téléphone mobile. i.e. les caractères non signifiants tels espaces, points seront ignorés (0601010101, 06 01 01 01 01, 06.01.01.01.01... sont acceptés pour l'envoi du sms).
* Saisir le « Corps » du SMS. Le « Corps » du SMS peut comporter des variables.

Nota bene : cette action est visible uniquement sur les installations ayant un connecteur SMS activé (abonnement auprès d'un opérateur de télecom nécessaire, soit via Entr'ouvert, soit en direct). Pour ajouter un connecteur, suivez ce tutoriel :Configuration de l'option "Envoi de SMS".

Nom de compteur

Vous pouvez renseigner un nom de compteur qui sera ensuite utilisé dans une cellule de typeGraphe pour visualiser les données statistiques, pour regrouper le nombre de SMS par « Nom de compteur » par exemple.

* Studio
* Les tutos

# Modification d’une fiche

Modification d’une fiche

Pour apprendre à utiliser les fiches, consultez «Stocker l'information».

Cette action permet de modifier une ou plusieurs fiche(s) :

* Soit le ou les fiches liées à la demande en cours
* Soit des fiches dont l'identifiant est précisé (via un gabarit renvoyant un objet liste Django comme par exemple {{ cards|objects:"MODELE-DE-FICHE"|filter_by:"IDENTIFIANT-CHAMP"|filter_value:"VALEUR" }} )

Pour modifier la fiche à partir de laquelle s'exécute l'action de modification on utilisera le gabarit {{ form_internal_id }}

Édition

« Formulaire » : choisir le type de fiche (modèle de fiche) à modifier.

Une fois que le formulaire est sélectionné et que l'action est enregistrée, une liste de champs apparaît pour permettre la modification des champs de la fiche avec les valeurs saisies dans la démarche en cours de traitement.

Association d'une demande à une fiche

Lorsque la fiche à modifier a été créée par l'action « Création d'une fiche » à partir de la même demande, il n'y a rien à paramétrer : le lien se fait automatiquement entre la demande et la fiche cible.

Lorsque la fiche cible n'a pas été créée par la demande en cours, il faut relier la demande à une fiche existante.

Pour ce faire, il faut utiliser un champ de type liste alimenté par une source de données définie automatiquement par le gabarit de résumé du modèle de fiche (voirDévelopper des applications métier avec Publik)

Avec, par exemple, un modèle de fiche « Établissements scolaires » ayant un champ dont l'identifiant est form_var_nom, le fait d'indiquer {{form_var_nom}} dans le gabarit du résumé suffit à créer automatiquement une source de données nommée « Établissements scolaires » contenant le nom de tous les établissements scolaires enregistrés via ce modèle de fiche.

Ce champ va donc prendre la valeur d'un élément de cette liste, qui correspond à une fiche. Cela suffit pour relier une demande à une fiche (ou deux fiches entre elles). Ce champ liste peut être défini dans le formulaire ou en donnée de traitement dans le workflow.

Pour continuer l'exemple précédent, si un champ de type liste  « form_var_etablissement » est défini dans la démarche et que ce champ est alimenté par la source de données « Établissements scolaires », alors il devient possible de modifier la fiche de l'établissement sélectionné à partir de la demande utilisant ce champ.

* Studio
* Les tutos

# Action « Géolocaliser »

Action « Géolocaliser »

Vous pouvez utiliser l'action de géolocalisation dans un workflow pour attacher des coordonnées géographiques aux demandes. L'information est mise à disposition dans les variables

form_geoloc_base_lat

pour la latitude et

form_geoloc_base_lon

pour la longitude. Elles peuvent alors être réutilisées ultérieurement (affichage sur une autre carte, etc.).

Ces données peuvent avoir différentes provenances :

* être issues des champs « Carte » ou « Fichier » (métadonnées attachées à une photographie)
* être géocodées depuis une adresse.

Géocodage à partir d'une adresse

* dans l'action de workflow choisir « Adresse »
* rentrer en paramètres les données d'une adresse présente dans la demande (cette adresse sera géocodée via une API - Nominatim ou une éventuelle API fournie avec le SIG de la collectivité). Le champ « Adresse » doit donc être complété comme suit : {{form_var_numero}} {{form_var_voie}}, {{form_var_commune}}

Pour optimiser le résultat du géocodage, il est possible d'ajouter le code postal, le n°, voire l'intitulé de la voie, etc. Si certains champs sont facultatifs dans le formulaire, et qu'il ne sont pas remplis par l'usager, il convient d'envoyer à l'API une valeur vide et non "None". Il faut donc filtrer ces données facultatives avec |default : {{form_var_num_rue|default:""}} {{form_var_adresse|default:""}}, {{form_var_code_postal}} {{form_var_ville}}

Géocodage à partir des données « latitude » et « longitude » issues d'un champ « Carte »

Dans ce cas ce sont les données « latitude » et « longitude » issues d'unchamp de type « Carte »qui sont récupérées.

* dans l'action de workflow choisir «Nom de la variable carte».
* Remplir ce paramètre avec une expression de type 'gabarit' faisant référence au champ « Carte ». Exemple : Si la carte concernée a pour identifiant « carte » alors l'expression à indiquer est {{form_var_carte}}.

Géocodage à partir des données « latitude » et « longitude » issues d'une photographie

* dans l'action de workflow choisir «Nom de la variable photo»
* le paramètre est une expression pointant une variable tirée d'un champ de type « Fichier » ; le fichier ainsi pointé doit être une image contenant des métadonnéesEXIFgéographiques. Le champ «Nom de la variable photo» doit être complété avec l'identifiant du champ concerné comme suit : {{ form_var_photo_raw }}

Écraser la géolocalisation existante

« Écraser la géolocalisation existante » permet de ré-attribuer des coordonnées géographiques en cas de succession de plusieurs actions « Géolocalisation », il faut alors ordonner ces actions de la moins précise à la plus précise.

Exemple : une première action « Géolocalisation » va attribuer des coordonnées géographiques depuis le curseur positionné par l'internaute dans une carte du formulaire (potentiellement un champ obligatoire) puis une deuxième action « Géolocalisation » écrasera ces coordonnées, précédemment enregistrées, avec des coordonnées calculées depuis les méta-données EXIF d'une photographie uploadée avec le formulaire (potentiellement un champ optionnel). Bien évidemment dans ce cas, si aucune photo n'est présente dans le formulaire, les coordonnées restent inchangées, ce seront celles du pointeur sur la carte.

* Studio
* Les tutos

# Formulaire (action)

Formulaire (action)

L'action « Formulaire », peut être nécessaire pour demander des informations supplémentaires à l'usager qui a introduit une demande, ou pour qu'un agent complète la demande de l'usager avec des informations internes.

À l'instar d'un « cadre réservé à l'administration », typique des formulaires papier, « Formulaire » peut permettre à un agent de joindre à la demande d'un usager des données internes.

Enregistrer le formulaire

Par défaut le formulaire dispose d'un bouton « Valider » non personnalisable.

Une option permet toutefois de ne pas afficher ce bouton et on utilisera alors à la place un «

[Saut manuel](https://doc-publik.entrouvert.com/admin-fonctionnel/fabrique-de-workflows/les-actions-de-workflow/action_transition-manuelle/)

» qui permet d'afficher dans l'interface un bouton dont on peut choisir le texte (par exemple « Enregistrer » et sur lequel on peut mettre une aide contextuelle.

Attention ce saut manuel doit être positionné après le formulaire dans la liste des actions, sans cela les données du formulaire ne seront pas enregistrées.

Récupérer les données du formulaire

Les données du formulaire sont intégrées à la demande et on peut les récupérer en utilisant une variable du type :

* form_workflow_form_MON-FORMULAIRE_var_MON-CHAMP

Plusieurs passages par un même formulaire

Si le formulaire est rempli plusieurs fois, chaque passage est indexé (avec 0 pour le premier passage). Cela permet de retrouver la valeur des champs pour chaque passage avec une variable du type :

* form_workflow_form_MON-FORMULAIRE_INDEX_var_MON-CHAMP

Édition

Les étapes d'édition de l'action « Formulaire » sont les suivantes :

* Pointer et ajouter chaque fonction et/ou rôle d'utilisateur destiné à saisir le formulaire, au sein d'une liste déroulante.
* Attribuer un identifiant au formulaire à afficher.Rappel :Publik dispose d'un système générique appelévariables de substitutionqui permet de faire référence, à l'aide d'une formule, à la valeur d'un champ saisi au sein d'un formulaire. Pour accéder à la valeur d'un champ, il faut préciser le formulaire au sein duquel la valeur a été saisie; et le champ, au sein de ce formulaire, dont la valeur doit être exploitée.
* Éditer les champs du formulaire, en cliquant sur le lien «Modifier les champs ». La création de champs se déroule alors exactement comme pour  un formulaire classique (mais les champs de type « Page » ne sont pas disponibles)

* Studio
* Les tutos

# Permettre l'édition

Permettre l'édition

L'action « Édition », permet qu'une demande d'usager en cours de traitement soit modifiée. Il convient d'utiliser cette possibilité avec parcimonie et toujours dans un statut à part : il faut pouvoir tracer sans ambiguïté le fait qu'il ne s'agit plus de la demande originelle du citoyen mais d'une demande modifiée par un agent.

L'édition va permettre d’associer un usager à une demande ou fiche. Cela concerne uniquement les demandes ou fiches qui ne sont pas encore liées à un usager au moment de l’édition.

Les données initiales de la demande (avant l'action d'édition) sont automatiquement enregistrées et apparaissent dans le journal de la demande. Elles peuvent aussi être stockées dans des données de traitement si nécessaire.

Limiter l'édition à une ou plusieurs pages

Il est possible de limiter l'action à une page donnée, ou bien de la faire démarrer à une page donnée (en incluant toutes les pages suivantes).

Pour cela il faut commencer pardonner, sur le formulaire, un identifiant à la page concernée.

Dans l'action d'édition on indique ensuite l'identifiant de la page et on choisit si l'action va concerner uniquement cette page ou bien cette page et toutes celles qui suivent.

Attention: l'action édition permet d'éditer l'ensemble des champs affichés sur la page éditée. Mais il peut y avoir des champs dans les pages ultérieures qui sont conditionnés par les valeurs éditées. Si leur condition d'affichage n'est plus vérifiée suite à l'édition, ces champs seront vidés de leur valeur. Par exemple, si je modifie la demande pour indiquer « Non » à la place de « Oui » à la question « possédez-vous un vélo ? », le champ « Taille des roues » qui était conditionné par la réponse « Oui » et situé sur une page ultérieure, sera vidé de sa valeur.

Édition

Les étapes d'édition de l'action « Édition » sont les suivantes :

* Sélectionner chaque fonction habilitée à éditer la demande.
* Spécifier le statut de destination de la demande à l'issue de son édition.
* Indiquer le texte du bouton sur lequel l'agent va cliquer pour éditer une demande.
* Indiquer éventuellement l'identifiant d'une page pour limiter l'édition (ou la faire démarrer) à cette page.
* Rédiger le texte d'information qui explicitera au gestionnaire chargé du traitement de la demande ce qu'induit l'action « Édition ».

* Studio
* Les tutos

# Attribuer une fonction de traitement

Attribuer une fonction de traitement

L'action « Liaison fonction/rôle »,  permet de changer, à une étape du workflow, le ou les rôles attribués à une fonction de traitement existante. Par exemple, cela va permettre de changer le destinataire (l'agent en charge du traitement) de la demande.

Cette action est souvent appelé « Dispatch » car elle va permettre de distribuer une demande à des agents différents selon un critère donné. L'action va permettre au choix d’attribuer un rôle particulier à la fonction, d'ajouter un nouveau rôle à la fonction en plus du ou des rôle(s) existant(s), de retirer un rôle à la fonction.

Plutôt que d'indiquer un rôle donné, il est possible de « construire » dynamiquement le rôle qui sera associé à la fonction. Pour cela il faut sélectionner « Autre : » dans la liste déroulante et indiquer la variable qui contient le nom du rôle auquel la fonction doit être associé, par exemple {{ form_var_role_calcule }}.

Attention, le nom de la variable doit correspondre très exactement au libellé du rôle visé (majuscules, espaces, tirets, accents...).

Si la réponse d'un usager à une question du formulaire « type de problème constaté » il a répondu « Éclairage », la demande ira au service concerné. S'il a répondu « Trou dans la chaussée », elle partira vers un autre service.

Liaison simple

La liaison simple est à utiliser lorsque l'on souhaite lier la fonction à un rôle donné.

Liaison multiple

La liaison multiple est à utiliser lorsque souhaite associer la fonction à des rôles différents selon la valeur d'une variable.

En imaginant que le champ « Variable » contienne {{ form_var_type }}, je vais indiquer en dessous les rôles correspondant aux différentes valeurs de {{ form_var_type }}.

Lier la fonction à un utilisateur

L'action va permettre de lier directement un utilisateur à une fonction, cela se fait en paramétrant le rôle sur un gabarit calculé (en choissisant « Autre : » en bas de la liste déroulante des rôles), qui doit pointer l’utilisateur (ex: {{ session_user }}), son identifiant (ex: {{ session_user_nameid }}), voire son adresse électronique (ex: {{ session_user_email }}).

Édition

Les étapes d'édition de l'action « Liaison fonction/rôle » sont les suivantes :

* Choisir dans la liste déroulante la fonction à attribuer
* Choisir manuelSélectionner le rôle qui va désormais être attribué à la fonction concernée
* Choisir automatiqueIndiquez le nom de la variable sur base de laquelle le rôle sera sélectionnéIndiquez pour chaque valeur de la variable quel est le rôle qui sera attribué à la fonction (exemple : si la variable form_var_type_probleme prend la valeur voirie, alors la fonction destinataire prend le rôle « voirie »)

Utilisation d'un gabarit django

Dans le cas d'action « multiple », il est possible d'utiliser un gabarit Django dans le champ « Variable ».

* Studio
* Les tutos

# Rattachement d’un usager à une fiche

Rattachement d’un usager à une fiche

Cette action permet de lier ou délier un utilisateur et une fiche en prenant en compte soit :

* Les fiches liées à la demande
* Une fiche ou une liste de fiches particulières dont on précisera le ou les identifiants

Pour cibler plusieurs demandes, il faut que le gabarit fournisse la requête, fournir une chaîne avec des identifiants séparés par des virgules ne fonctionnera pas.

{{ cards|objects:"MODELE-FICHE"|filter_by:"CHAMP"|filter_value:VALEUR }}

* Studio
* Les tutos

# Recevoir un courriel quotidien unique (obsolète)

Recevoir un courriel quotidien unique (obsolète)

Ce type de champ est déprécié. On constate que les gens qui ne veulent pas recevoir de courriel à 
chaque demande, sont souvent sur la plate-forme et n'ont pas besoin de 
ce récapitulatif.

L'action« Courriel récapitulatif quotidien » permet d'envoyer quotidiennement, le matin, du lundi au vendredi,  la liste des demandes d'usagers passées par le statut dans lequel se trouve l'action, peu importe le statut actuel, à l'exception des demandes depuis supprimées. Seules les demandes qui sont passées,après l'envoi précédent, par le statut dans lequel se trouve l'action sont concernées.

Le message contient la liste des URL des demandes concernées et leur statut actuel.

Le message peut contenir des demandes venant de différentes démarches, y compris avec des workflows différents, les demandes sont alors triées par démarche.

Les mails sont envoyés aux rôles et pas aux personnes ayant ce rôle. Cela signifie que ça ne va fonctionner qu'avec des rôles pour lesquels un mail a été renseigné explicitement.

Édition

Pour éditer l'action « Courriel récapitulatif quotidien », l'administrateur fonctionnel doit simplement sélectionner, dans une liste déroulante, à qui sera envoyer ce récapitulatif.

* Studio
* Les tutos

# Redirection web

Redirection web

Cette action envoie le navigateur de l'utilisateur vers l'URL spécifiée (cette URL peut être externe à Publik).

Si par exemple on décide d'utiliser cette action dès la première étape du workflow, l'usager ne verra pas le journal de la demande, il sera directement redirigé vers l'URL spécifiée.

* Studio
* Les tutos

# Création d’une fiche

Pour apprendre à utiliser les fiches, consultez «Stocker l'information»

L'action « Création d'une fiche » permet de créer automatiquement une fiche dans Publik Studio à partir d'une demande.

Cette action va permettre :

* de créer une nouvelle fiche,
* de remplir les champs de la fiche à partir des informations du formulaire ou des données issues du traitement,
* de lier la fiche cible à la demande d'origine.

Édition

Dans l'onglet « Avancé », l'option « Correspondance automatique des champs par leurs identifiants » va permettre de remplir automatiquement les champs de la fiche avec les champs qui portent le même nom dans le formulaire, sans avoir à les préciser un par un.

* « Formulaire » : choisir le type de fiche (modèle de fiche) à créer.
* « Identifiant » : si l'identifiant est renseigné, on peut accéder aux informations de la fiche « enfant » , par exemple {{form_links_IDENTIFIANT_form_url}}.
* « Utilisateur associé à la fiche » permet de garder l'utilisateur originel (celui de la demande/fiche mère), d'enlever cet utilisateur ou encore de le remplacer par un autre défini par ungabarit.

Une fois que le formulaire est sélectionné et que l'action est enregistrée, une liste des champs apparaît pour permettre le remplissage des champs de la fiche avec les valeurs saisies dans la démarche en cours de traitement.

* Studio
* Les tutos

# Retirer un rôle à l’utilisateur

Retirer un rôle à l’utilisateur

L’action « Retrait d’un rôle » a pour effet la soustraction d’un rôle à un utilisateur (usager ou agent, donc) dont la demande atteint le statut qui contient cette action.

Édition

L'édition de l'action « Retrait d’un rôle » se réduit à la sélection du rôle à ôter à l'usager.

* Studio
* Les tutos

# Ajouter un rôle à l’utilisateur

Ajouter un rôle à l’utilisateur

L'action « Ajout d'un rôle » permet de doter l'usager d'une demande en cours d'instruction, d'un rôle supplémentaire lorsque sa demande atteint un statut particulier.

Exemple d'usage de l'action«Ajout d'un rôle» :

Une demande d'enregistrement d'une association culturelle est destinée à intégrer un workflow qui prévoit le statut « Accepté » auquel est affectée l'action « Ajout d'un rôle ».

Si elle atteint ce statut, l'usager qui l'a introduite se verra attribué un rôle supplémentaire, celui de « Membre d'une association culturelle ».

Ce rôle va s'aditionner au(x) rôle(s) existant(s) de l'usager, pas s'y substituer.

Édition

Pour éditer l'action « Ajout d'un rôle », l'administrateur fonctionnel doit simplement sélectionner, dans une liste déroulante, le rôle à ajouter de l'usager qui a introduit une demande.

* Studio
* Les tutos

# Modifier le profil de l'usager

Modifier le profil de l'usager

Cette action permet d'aller mettre à jour les données du profil du demandeur.  On pourra, par exemple, mettre à jour l'adresse du profil quand un usager soumet un formulaire de changement d'adresse.

L'ensemble des champ du profil sont disponibles lorsqu'on édite l'action, il suffit de leur faire correspondre une variable ou une expression pour modifier les champs en question.

Je vais pouvoir associer une donnée de traitement à une variable :

Nom : {{form_var_nom}}

Ou bien à un expression python

Adresse : ="Numéro" + {{form_var_numero}} + " " + {{form_var_rue}}

* Studio
* Les tutos

# Workflow externe

Workflow externe

Cette action permet de déclencher une action globale sur un workflow cible à partir d'un appel réalisé par un autre workflow. L'action va s'appliquer au choix :

* sur des demandes ou fiches préalablement reliées entre elles. C'est le cas lorsque la demande ou la fiche cible est créée par les actions «Création d'une demande» ou «Création d'une fiche» ou qu'elles sont reliées entre elles via un champ de type liste (voir le principe ici : «Modification d'une fiche»).
* sur des demandes ou fiches dont on spécifie explicitement  les identifiants (on peut utiliser ici un objet liste Django pour désigner une liste de fiches, par exemple {{ cards|objects:"MODELE-DE-FICHE"|filter_by:"IDENTIFIANT-CHAMP"|filter_value:"VALEUR" }}

Sur le workflow cible : paramétrage préalable d'une action globale

Uneaction globaledoit préalablement être paramétrée avec un déclencheur « Appel externe ».

« Identifiant » : définir un identifiant de l'action globale

« Rôles » : pour autoriser un rôle à déclencher l'action et la rendre interactive.

Sur le workflow à l'initiative de l'action : paramétrage d'une action « Workflow externe »

« Formulaire / Modèle de fiche » : choisir le formulaire ou le modèle de fiche « cible » sur lequel va s'exécuter l'action globale.

« Action » : choisir l'action globale à exécuter. Les actions globales listées sont celles qui ont été préalablement définies avec un déclencheur « Appel externe » sur le workflow cible. Cet appel externe doit être renseigné au niveau de «Rôles requis pour déclencher via un appel HTTP», il faut sélectionner « Appels signés aux API » pour que l'appel ne soit pas ouvert à tous.

Variables « caller_form_… » pour accéder à l'appelant

Quand l'action globale est déclenchée sur la demande ou la fiche ciblée, la demande ou la fiche qui a déclenchée l'action est vue sous le nom « caller_form » (demande ou fiche appelante). Dans les actions exécutées, il est donc possible d'utiliser n'importe quelle variable de la demande appelante en remplaçant le suffixe « form » par « caller_form ».

Par exemple, {{ caller_form_number }} représente le numéro de la demande appelante, ou {{ caller_form_backoffice_url }} est son URL en backoffice.

Ces variable caller_form_… sont disponibles uniquement le temps de l’appel, elles ne sont donc pas visibles dans la vue d’inspection.

* Studio
* Les tutos

# Permettre de joindre un fichier

Permettre de joindre un fichier

L'action Fichier joint sera prochainement

, qui permet de créer un formulaire de workflow avec notamment des champs de type fichier.

L'action « Fichier joint »,  permet qu'une demande d'usager en cours de traitement soit complétée par un document ou une image ajoutée par le demandeur ou l'agent traitant.

Cette action peut être utilisée pour alimenter une donnée de traitement.  Si parmi lesdonnées de traitementdu workflow existe au moins un champ de type « fichier », vous aurez dans l'action « fichier joint » la possibilité d'associer l'action à cette donnée de traitement.

Édition

Les étapes d'édition de l'action « Fichier joint » sont les suivantes :

* Pointer, au sein d'une liste déroulante, chaque fonction et/ou rôle, habilité(e/s) à joindre un document en pièce-jointe.
* Déterminer si joindre le fichier est obligatoire, ou non.
* Indiquer le titre du bouton qui enclenchera le chargement du fichier
* Saisir le texte du bouton qui permettra aux rôles autorisés à joindre un fichier.
* Rédiger une remarque, susceptible d'aider les utilisateurs autorisé à joindre un fichier, en indiquant, par exemple, la liste des formats de fichiers acceptés et/ou la taille minimale et/ou maximale du fichier requis, etc.
* Rédiger un texte d'information susceptible d'expliciter le but du bouton « Joindre un fichier ».
* Inclure dans l'historique du formulaire : cela signifie que l'usager et les agents traitants pourront y accéder dans la suite du traitement. Cela permet aussi d'y accéder pour l'envoyer par mail, sans passer par une donnée de traitement.
* Choisir si le fichier doit être envoyé dans le porte-document : l'usager pourra y accéder dans son compte et éventuellement le réutiliser pour d'autres démarches.

* Studio
* Les tutos

# Changer de statut à la soumission

Changer de statut à la soumission

L’action

Saut à la soumission

est obsolète et sera bientôt

[dépréciée](http://https://doc-publik.entrouvert.com/admin-fonctionnel/elements-deprecies/)

.

Dès maintenant, il est recommandé de la remplacer par un

[Saut manuel](http://https://doc-publik.entrouvert.com/admin-fonctionnel/fabrique-de-workflows/les-actions-de-workflow/action_transition-manuelle/)

.

Procédure de remplacement

Lorsque le statut contient un Formulaire

* Supprimer le Saut à la soumission
* Ajouter un Saut manuel
* Modifier les paramètres avancés de l’action Formulaire et cocher la case :« Ne pas inclure de bouton « Valider » »Sans ce bouton, la validation ne pourra se faire qu’avec le saut manuel.

Lorsque le statut contient une action Commentaire et/ou Fichier joint

* Pour l’action Commentaire : vider le champ « Texte du bouton » pour empêcher l’affichage d’un bouton
* Pour l’action Fichier joint : vérifier que la case « Afficher le bouton » est décochée

Lorsque le saut à la soumission contient une condition d'exécution de l'action sur une valeur récupérée dans le même statut

Lorsque le saut est conditionné par une valeur d'une formulaire dans le même statut. Cette valeur ne peut être évaluée dans le même statutSolution :

* Ajouter un Saut manuel vers un nouveau statut (cf. ci-dessous)
* Ajouter un statut intermédiaire qui contiendra des actions Saut automatique sur lesquelles s'appliqueront les conditions d’exécution. Ce statut doit être paramétré pour ne jamais être affiché dans l'historique : Options > Affichage du statut dans l’historique : Jamais affiché

Lorsque le saut à la soumission contient une condition d'exécution de l'action sur une valeur non récupérée dans le même statut

Lorsque les sauts sont conditionnés par des valeurs ne dépendant pas du formulaire dans le même statut, la solution est de remplacer le Saut à la soumission par un Saut manuel en reprenant la même condition d’exécution.

L'action « Saut à la soumission » est prévue pour diriger une demande vers un statut particulier lorsqu'un formulaire, un commentaire ou un fichier joint sont validés.

Il est possible d'ajouter un marqueur sur le statut courant lors d'un saut de workflow, pour permettre ensuite un saut de retour direct vers celui-ci.  L'objectif est de permettre d'afficher un bouton « Revenir au statut précédent » aux agents traitant lorsque l'on souhaite leur permettre une action de ce type plutôt qu'un retour vers un statut particulier et fixe. Pour activer le marqueur : dans les paramètres de l'action de saut, onglet « Avancé », cocher la case « Poser un marqueur qui permettra de revenir au statut actuel ».

Édition

Trois actions sont concernées par le changement de statut à la soumission :

* Fichier joint
* Commentaire.

Pour ces 3 actions, l'administrateur fonctionnel peut décider qu'elles vont déclencher un changement de statut, « à la soumission » du formulaire.

En configurant, dans l'action de saut à la soumission, le statut de destination, on décide du statut dans lequel va se retrouver la demande une fois que le bouton aura été cliqué.

* Studio
* Les tutos

# Anonymiser

Après instruction d'une demande, il peut être souhaité d'en conserver une trace à des fins statistiques, tout en lui retirant toute information à caractère personnel, pour respecter les règles de protection de la vie privée des usagers, conformément aux recommandations de la CNIL et du RGPD.

L'action « Anonymisation », permet de supprimer les données personnelles d'usagers saisies au sein de formulaires de demandes clôturées, à l'issue d'un délai à définir. La suppression des données personnelles consiste en l'effacement de tous les champs pour lesquels l'option anonymisation est cochée et la suppression de tous les fichiers liés à la demande ;

La meilleure façon de configurer l'action d'anonymisation est de la positionner dans une «Action globale» avec un déclencheur automatique 90 jours après le traitement. Cette action pourra ainsi s'appliquer sur tous lesstatuts « finaux », c'est-à-dire les statuts dans lesquels la demande a été traitée, sans devoir déplacer les demandes dans un autre statut.

Données affectées par une anonymisation

En plus des données saisies dans le formulaire pour lesquelles l'option est cochée, l'anonymisation de la demande provoque l'effacement d'un certain nombre de données :

* les données liées au compte de l'usager :id de l'usager,nom / prenom ...,
* les données enrichies dans le workflowles données de traitement (sauf champs de type liste pour lesquels l'option d'anonymisation est décochée),les commentaires saisis par les agents dans les actions de type "commentaire",les données saisies dans les formulaires de workflow (pour lesquelles l'option est cochée).

Publik conserve donc :

* date de dépôt de la demande,
* statut précédent (donc dernier statut avant anonymisation),
* id de la demande,
* code de suivi de la demande,
* rôles liés aux fonctions du workflow,
* les infos de géolocalisation s'il y en a,
* les données de la demande pour lesquelles l'option n'est pas cochée

Les demandes et fiches ayant fait l'objet d'une anonymisation finale ne sont plus affichées dans les listings des fiches et des demandes. Toutefois, elles restent incluses dans les exports. De plus, les demandes anonymisées de manière définitive ne figurent plus dans la vue globale.

En revanche, l'anonymisation intermédiaire ainsi que celle supprimant uniquement l'association entre la demande ou la fiche et l’usager ne les retirent pas des listings.

Anonymisation intermédiaire

Par défaut l'anonymisation est dite « finale », toutes les données personnelles sont effacées. Mais vous pouvez configurer l'action pour qu'elle ne soit qu'« intermédiaire », ce qui va permettre d'opérer un tri parmi les données personnelles qui doivent être conservées et celles qui peuvent être anonymisées (chaque champ peut être configuré pour décider s'il est conservé ou pas lors d'une anonymisation intermédiaire).

Dans le workflow on peut ajouter un statut « Archivage intermédiaire » et y ajouter l'action d'anonymisation Intermédiaire à une étape précédent l'anonymisation finale.

À noter que l'anonymisation intermédiaire ne délie pas la demande et le demandeur.

Pour que les demandes ne soient plus consultables par les agents instructeurs mais par des personnes spécialement habilitées, vous pouvez coupler l'action d'anonymisation intermédiaire avec une action «Liaison fonction/rôle».

🔗Prendre connaissance du cycle de vie des données - source CNIL

Retirer l’association entre la demande/fiche et l’usager

Cela permet la dé-liaison entre la demande et l’usager associé. C'est utile par exemple pour les comptes personnes morales : une démarche est effectuée par quelqu'un qui quitte ensuite l'association, il ne faut plus que ce quelqu'un soit associé à la demande concernée.

Quand l'option est cochée, il n'y pas de suppression de données donc, mais uniquement suppression de la liaison entre le demandeur et la demande.

Anonymisation d'un bloc de champs inclus dans un formulaire

L'anonymisation est définie champ par champ dans le paramétrage du bloc de champs.

Dans le formulaire où est inclus le bloc de champs, si l'option d'anonymisation choisie pour le bloc est :

* "Donnée supprimée lors d’une action d’anonymisation finale", alors les réglages définis dans le bloc de champs sont supplantés et l'ensemble de ses champs seront anonymisés ;
* "Donnée conservée après une action d’anonymisation", alors les réglages définis dans le bloc de champs s'appliquent et les données seront ou non conservées en fonction des options spécifiées dans le paramétrage du bloc.

* Studio
* Les tutos

# Supprimer

Supprimer

L'action« Suppression » a pour effet la suppression de la demande de l'usager.

Il est utilisé le plus souvent pour supprimer des demandes ancienne. Cela peut-être automatisé en faisant un « changement de statut automatique » avec une limite de temps quelconque (par exemple 3 ans) depuis un statut final vers un statut « Suppression » qui aurait « Suppression» comme unique action.

L'action de suppression n'est pas réversible. Ce ne devrait donc pas être une action manuelle ordinaire proposée aux agents traitants. Il vaut mieux permettre à ces derniers de « rejeter » une demande plutôt que de la supprimer. On garde ainsi la trace de la demande.

Édition

L'édition de l'action « Suppression » se résume à la validation de l'action.

* Studio
* Les tutos

# Envoyer un courriel

Envoyer un courriel

Comme son nom l'indique, l'action « Courriel » a pour effet d'envoyer d'un courriel.

Afin de ne pas avoir à réécrire fréquemment les mêmes courriels, il est fortement conseillé de fabriquer des modèles, par exemple un

modèle d'accusé de réception

ou d'accusé d'enregistrement. En cliquant sur « Modèle de courriel » en haut de la page d'accueil des workflows, il est possible de fabriquer et de stocker ces messages types, pour les rendre utilisables dans l'action d’envoi de courriel, par un simple clic. Il est possible de dupliquer les modèles de courriel pour commencer un nouveau modèle en se basant sur un modèle existant.

Édition

Les étapes d'édition de l'action « Courriel » sont les suivantes :

* Pointer, au sein de la liste déroulante une fonction destinée à recevoir le message. Un envoi multi-destinataires est possible en cliquant sur « Ajouter un rôle » ;
* Saisir le « Sujet » du courriel, qui peut comporter des variables selon lasyntaxe des templates;
* Saisir le « Corps » du courriel. Le corps de l'email, en texte brut, peut comporter desvariableset des conditions d'affichage décrites dans lasyntaxe des templates;
* Il est possible d'optimiser la mise en formedu message

L'envoi à une adresse spécifique est également possible après choix « Autre : » situé à la fin de la liste du choix du destinataire. Il est possible d'indiquer directement une adresse, ou d'utiliser un template (par exemple{{form_var_destinataire}}).

Il est possible de mettre plusieurs destinataires dans « Autre : » en séparant les adresses courriels par une virgule.

Envoi d'un courriel à l’usager demandeur

Lorsque l'action est paramétrée pour envoyer un courriel à l'usager, c'est-à-dire au demandeur de la démarche, l'adresse de destination utilisée est :

* soit le courriel saisi dans le formulaire, dans le premier champ « courriel » avec préremplissage depuis le champ utilisateur courriel ;
* soit le courriel renseigné dans le profil du compte si le champ n'est pas renseigné.

Il est donc important de prévoir un champ « courriel »avec préremplissagepour les formulaires pouvant être complétés sans compte usager.

D'une façon générale, il est préférable de toujours afficher un tel champ « courriel » dans les formulaires afin de signaler au demandeur qu'il sera informé de la suite du traitement de sa demande au travers de cette adresse. Il pourra, à ce moment de la saisie, corriger cette adresse le cas échéant.

Joindre un fichier

Tous les fichiers utilisés dans le formulaire ou le workflow peuvent être joints à un courriels.

* Action de courriel/ Onglet « Avancé »/ Champ «Fichiers attachés (gabarits) »

Le gabarit utilisable dans cette zone diffère en fonction de l'endroit d'où provient le fichier à joindre (en prenant l'exemple d'un fichier dont l'identifiant est « fichier ») :

* Fichier dans la demande ou en donnée de traitement :{{ form_var_FICHIER }}
* Fichier d'un formulaire de workflow :{{ form_workflow_form_FORMULAIRE_var_FICHIER }}
* Fichier provenant d'une action « Fichier joint » ou « Création de document » :{{ form_attachments_FICHIER }}.Attention, le fichier doit impérativement être joint à l'historique de la demande (c'est une option des actions concernées) pour que cela fonctionne.

Lorsqu'elles existent, les données de traitement de type fichier apparaissent dans une liste déroulante sous la mention «  Fichiers attachés »

Mettre des « boutons d’action » dans un courriel

Il est possible d'insérer, dans un courriel envoyé, des boutons d'action, c'est-à-dire des boutons qui apparaîtront dans le corps du message et permettront au lecteur de réaliser une action en cliquant dessus. Pour insérer, par exemple, un bouton « Valider », on mettra dans le modèle du courriel :

{% action_button "terminer" label="Valider" delay=7message="Confirmez-vous la validation ?"done_message="Votre validation a bien été prise en compte; merci de votre participation."%}

Dans cet exemple,« terminer »désigne l'identifiant d'uneaction de saut manuel(il faut donc mettre un identifiant sur cette action au préalable) pointant vers le statut Terminer.

«label»est obligatoire et indique le texte du bouton.

« delay »est facultatif et indique une durée de validité en jours. Si ce paramètre n'est pas présent, le bouton expire après trois jours.

« message» est facultatif et indique le message qui sera affiché à l'utilisateur sur la page de confirmation, après le clic sur le bouton dans le courriel.

«done_message» est facultatif et indique le message qui sera affiché à l'utilisateur après la confirmation de l'action.

Optimiser la mise en forme du message

Le message est saisi sous forme de texte brut. Il sera transformé en format HTML. Il est également possible d'utiliser le langage ReStructuredText pour améliorer la mise en forme.

* http://docutils.sourceforge.net/docs/user/rst/quickstart.html
* http://docutils.sourceforge.net/docs/user/rst/quickref.html
* http://docutils.sourceforge.net/rst.html

Saut de ligne

Pour forcer le saut de ligne, il suffit de laisser une ligne vide entre deux parties de texte. Vous obtenez alors 2 paragraphes distincts, séparés par une ligne vide.

Si vous souhaitez avoir un retour à la ligne sans ligne vide, utilisez le symbole | puis un espace en début de ligne, (ainsi qu’une ligne vide au-dessus et en dessous du paragraphe concerné) :

| ce texte
| apparaîtra sur plusieurs lignes
| même s'il n'y a pas de lignes vides pour marquer le retour à la ligne.

Gras et italique

Mettre un texte entre 2 asterisques le rendra en italique, entre 4 asterisques le rendra en gras.

*italique* =>italique

**gras** =>gras

Titres

Il faut souligner le texte d'un titre pour le mettre en forme.

titre de niveau 1
=================

titre de niveau 2

Hyperliens

Les url seront automatiquement traduites en liens, comme http://www.test.fr

Pour donner un libellé autre qu'une URL à un lien, il faut utiliser la syntaxe suivante (en oubliant pas le caractère underscore à la fin) :

Ceci est un `lien vers le site d'Entr'ouvert <https://www.entrouvert.com/>`_.

qui donnera :

Ceci est unlien vers le site d'Entr'ouvert.

Listes

Le schéma suivant :

* une liste
 - sous liste item 1
  + sous sous liste
  + sous sous liste 2
  + sous sous liste 3
 - sous liste item 2
* ensuite
 - autre sous liste 
* enfin

donnera

* une listesous liste item 1sous sous listesous sous liste 2sous sous liste 3sous liste item 2
* ensuiteautre sous liste
* enfin

Il est également possible d'utiliser une liste numérotée :

1. premièrement...
2. deuxièmement...
3. troisièmement...

Pour les listes ou les titres, il doit y avoir un saut de ligne au-dessus et en dessous du texte concerné pour que la mise en forme soit effective.

* Studio
* Les tutos

# Changer de statut manuellement

Changer de statut manuellement

L'action« Saut manuel », implique l'intervention d'ungestionnairepour faire évoluer les demandes atteignant le statut de workflow qui contient cette action. Elle provoque l'apparition d'un bouton dans l'interface de traitement des demandes.

Cette action peut aussi être utilisée pour créer desboutons d'actions dans un courriel.

Édition

Les étapes d'édition de l'action « Saut manuel » sont les suivantes :

* Donner un libellé au saut manuel, celui-ci sera affiché sur le bouton que le gestionnaire de la demande aura à activer pour provoquer le saut de statut.
* Sélectionner, au sein d'une liste déroulante la(les) fonction(s) autorisée(s) à changer manuellement le statut d'une demande.
* Sélectionner, au sein d'une liste déroulante, le statut qui sera atteint après le saut.
* Ajouter un texte informatif (optionnel) pour expliciter, à l'attention du gestionnaire, ce qu'induit ce saut manuel en termes fonctionnels.

Options

Des paramétrages supplémentaires du « Saut manuel » sont accessibles :

* volet « Général » :Demander une confirmation: permet d'afficher un message (personnalisable) et d'exiger une confirmation avant le déclenchement du saut.
* volet « Avancé » :Ignorer le formulaire: permet de ne pas tenir compte de la non complétion des champs obligatoires d'un formulaire lors du saut manuel. Cas d'usage fréquent, lorsque dans mon workflow je suis en train de construire l'interface de traitement, je conçois un formulaire (action « Formulaire ») et je veux mettre un bouton (une action « Saut manuel ») « Annuler » à côté de ce dernier. Si mon formulaire contient des champs obligatoires non remplis, mon bouton « Annuler » affichera une erreur parce que j'essaie de changer de statut alors que les champs obligatoires ne sont pas remplis. Cocher l'option « Ignorer le formulaire » permet d'éviter cela, mon saut s'effectuera même si les champs obligatoires ne sont pas remplis.Poser un marqueur qui permettra de revenir au statut actuel: permet de garder en mémoire le statut depuis lequel le saut manuel est déclenché. Il sera alors possible de revenir facilement à ce statut depuis le statut de destination.  L'objectif est de permettre d'afficher un bouton « Revenir au statut précédent » aux agents traitant lorsque l'on souhaite leur permettre une action de ce type plutôt qu'un retour vers un statut particulier et fixe.Imaginons un statut « Échange avec l'usager » auquel on peut accéder soit depuis le statut « Traitement en cours » soit depuis le statut « Dialogue interne », avec des sauts qui ont la case cochée. Sortir de ce statut avec un saut vers  « statut marqué précédemment » permettra de retourner vers le statut d'origine.Condition d’exécution de l’actionIdentifiant

* Studio
* Les tutos

# Enregistrer un message dans l’historique

Enregistrer un message dans l’historique

L'action « Message dans l'historique » a pour effet l'inscription d'un message, dans le déroulé même de l'historiqued'une demande d'usager.

Cette action permet de rédiger un texte (contenant éventuellement des variables, du contenu dynamique) qui intégrera l'historique d'une demande, accessible aussi bien à l'usager de la demande qu'au(x) gestionnaire(s) habilités à traiter la démarche dont elle résulte.

Le texte  issu de l'action « Message dans l'historique » figurera toujours dans l'historique d'une demande même après un changement de statut. Pour un texte informatif et ponctuel, le recours à l'action «Alerte» est préférable.

Il est possible d'utiliser des balises HTML dans le message si on encadre l'ensemble par des balises <div>...</div>

Une option permet de restreindre l’affichage du message à une fonction ou encore à un rôle de l’usager.

Modèles de messages

Il est possible de fabriquer des modèles de messages, c'est-à-dire des messages qui pourront être réutilisés d'un workflow à l'autre, comme pour les modèles de courriels. Depuis la page d'accueil des workflows, un bouton « Modèles de messages  » en barre latérale permet d'accéder à l'interface dédiée pour concevoir et catégoriser ces messages.

Quand on configure une action de message dans l'historique, on peut alors choisir un des modèles existant au lieu d'écrire un nouveau message.

Une zone de saisie « Fichiers attachés (gabarits ou expressions Python) » apparaît quand on clique sur le « + » sous le corps du message. Elle permet de joindre un fichier

[de la même façon qu'on le ferait pour une action de courriel](https://doc-publik.entrouvert.com/admin-fonctionnel/fabrique-de-workflows/les-actions-de-workflow/elements_envoyer-un-email/#joindre-un-fichier)

mais aussi de pointer un fichier généré à l'extérieur de Publik, par une application tierce liée à Publik via un webservice.

Édition

L'étape d'édition de l'action « Message dans l'historique » est la suivante :

* Message, vous permet de rédiger le contenu du message à afficher.  Dans le corps du message, du code html, ainsi qu'un certain nombre de variables peuvent être saisis.

* Studio
* Les tutos

# La répétition des actions d'un statut de workflow

La répétition des actions d'un statut de workflow

⚙️ Accès dans le BO :Studio > Workflows > 👉 un workflow > 👉 un statut > Options > Répétion

L'optionRépétitionpermet d'exécuter les actions d'un statut en boucle,  fonction d'un ensemble de valeurs issues d’une liste multiple, d’une requête ou des occurrences d’un bloc de champs.

Paramétrer la répétition des actions

Dans les options du statut, onglet Répétition :

* Indiquez le Gabarit produisant les éléments sur lesquels répéter les actions.Pour répéter les actions autant de fois qu'il y a d'éléments dans une liste à choix multiples ou d'occurrences dans un bloc de champs, indiquez simplement la variable du champ concerné, par exemple :{{ form_var_IDENTIFIANT }}.Il est également possible d'utiliser les filtres de requêtes, par exemple{{ cards|objects:"slug-modele-fiche"|filter_by:"nom"|filter_value:"entrouvert" }}.
* Sélectionnez le Statut cible en fin de répétition.

Récupérer les valeurs d'un champ

Depuis un bloc de champ

Lorsque le gabarit produisant les éléments sur lesquels répéter les actions est un bloc de champ contenant un champ ayant pour identifiant « nom » , la syntaxe{{ status_loop.current_item.nom }}permettra de récupérer la valeur du champ « nom » de l'occurrence en cours d'itération.

Avec un filtre de requête

Lorsque le gabarit produisant les éléments sur lesquels répéter les actions est un filtre de requête permettant par exemple de filtrer des fiches d'un modèle de fiche contenant un champ ayant pour identifiant « courriel », la syntaxe{{ status_loop.current_item|get:"form_var_courriel" }}permettra de récupérer la valeur du champ « courriel » de la fiche en cours d'itération.

Comprendre la variable status_loop

Lors de l’exécution des actions, il peut être utile d'accéder à l’élément en cours de traitement. Cet élément est disponible via la variablestatus_loop.current_item. Par exemple, pour une liste à choix multiples contenant les valeursAetB,{{ status_loop.current_item }}renverraAlors de la première itération etBlors de la seconde.

La variablestatus_loopoffre également des informations utiles sur l'itération en cours :

* {{ status_loop.index }}: renvoie le numéro de l’itération, en commençant à compter à 1.
* {{ status_loop.index0 }}: renvoie le numéro de l’itération, en commençant à compter à 0.
* {{ status_loop.first }}: retourneTruesi l’itération est la première.
* {{ status_loop.last }}: retourneTruesi l’itération est la dernière.

Outils de test

Dans l'inspection des données d'une demande, vous avez accès à l'outils de test qui permet de tester les valeurs retournées.Et aussi...Sur la page principale du workflow, dans la liste des statuts, une icône permet de distinguer les statuts sur lesquels une répétition est configurée.Dans le schéma du workflow il sera indiqué lorsqu'une une répétition est configurée et que le saut correspond à une fin de répétition.

* Studio
* Les tutos

# Champ nouvelle page

Champ nouvelle page

Composition de formulaires multi-pages

Le champ « Nouvelle page » permet de générer un formulaire multi-pages.

Autrement dit, le champ « Nouvelle page » permet de regrouper et d'afficher par page, un ensemble dechamps à saisir.

Pour ce faire, le champ « Nouvelle page » doit précéder les champs du formulaire censés appartenir à cette page.

Lorsque l'on fait un formulaire multiplage, le premier champ doit impérativement être un champ de type page.

Pour marquer la pagination des champs, que ce soit surla page d'édition des champsou dans l'aperçu du formulaire visualisable sur la pagedétailde ce formulaire, le champ "Nouvelle page" se distingue des autres champs par sa mise en forme, dont le retrait est accentué pour bien signifier leur appartenance à la page.

Surle portail citoyen, chacune des pages du formulaire est signalée par sonlibellé, en marge du formulaire, pour fournir aux usagers (etagents d'accueil) une vue d'ensemble des pages du formulaire et leur indiquer leur progression parmi celles-ci.

Limiter l'affichage à une page : afin de travailler sur une page spécifique sans être importuné par les autres pages, on peut cliquer sur« limiter l'affichage à cette page » dansla page d'édition des champs. Cela permet en particulier de créer de nouveaux champs directement dans la page concernée et non pas en fin de formulaire.

Propriétés spécifiques du champ Nouvelle page

Condition

Cette propriété permet de n'afficher au demandeur que les pages qui l'intéressent. Apprenez à créer unformulaire conditionnel.

Condition de sortie (de page)

Les conditions peuvent aussi être écrites « en sortie de page » pour contraindre la saisie de telle ou telle façon avant de passer à la page suivante. Tant que la condition n'est pas satisfaite, il est impossible de passer à la page suivante ; un message d'erreur s'affiche à l'usager pour l'informer ce qu'il doit faire (plus de détails sur la pageformulaire conditionnel).

Le message d’erreur d’une condition de sortie de page accepte les gabarits.

* Studio
* Les tutos

# Champ Nombre

Champ Nombre

Le champ« Nombre »est conçu, entre autres, pour faciliter la saisie et l’affichage des chiffres dans un formulaire, en particulier sur mobile. Voici ses principales caractéristiques :

Fonctionnalités principales :

* Saisie simplifiée :Affiche un clavier numérique sur mobile.Accepte les chiffres et les caractères spéciaux pour les nombres décimaux. Par exemple,0.2sera automatiquement converti en0,2pour respecter la syntaxe française.
* Options de configuration :Limitation aux entiers :vous pouvez limiter la saisie aux nombres entiers.Valeurs minimales et maximales :La valeur minimale par défaut est0, mais elle peut être définie comme négative si nécessaire.Aucune valeur maximale n’est définie par défaut, mais vous pouvez en spécifier une, y compris négative.Tableaux de traitement :vous pouvez réaliser des tris sur des valeurs numériques dans les tableaux de traitement.

* Studio
* Les tutos

# Guide de l’administrateur technique

Guide de l’administrateur technique

Pour les personnes gérant l'ensemble des paramètres techniques de la plate-forme et la connexion aux applications tierces.

Guide de l'administrateur technique

* Déploiement
* Déclaration d’un service SAML

# Le pointage des inscriptions à un évènement

Le pointage des inscriptions à un évènement

Le système depointagepermetde suivre la présence ou l'absence des personnes ayant effectué une réservation pour un évènement.

Configurer les paramètres du pointage

⚙️ Accès dans le BO :Agendas > 👉 un agenda de type Évènements > Paramétrage > Paramètres du pointage

Dans le paramétrage d'un agenda de type Évènements, onglet Paramètres du pointage, il est possible de configurer plusieurs options :

Filtres

Cette option permet d'ajouter des critères personnalisés sur lesquels les réservations pourront ensuite être filtrées depuis l'écran de pointage.Ces critères sont définis à partir de données supplémentaires (extra_data) attachées aux réservations, sous forme de paires donnée/valeur, séparées par des virgules.

Exemple

* Paramétrage de l'agenda en BO : une fois l'agenda sélectionné, choisir "Paramétrage" dans le menu kebab puis "Paramètres du pointage". Indiquer les clés des extra_data, ici une seule clé, "regime".
* Dans le formulaire de réservation, configurer un champ liste proposant les valeurs possibles pour ce filtre, par exemple "Végétarien" et "Allergique".
* Dans le workflow, indiquer au niveau de l'action webservice de réservation le paramètre "regime" et sa valeur, ici {{ form_var_regime }}
* Dans l'écran de pointage, des boutons radio apparaîtront désormais pour chaque valeur (Végétarien,Allergique), permettant de sélectionner uniquement les réservations correspondant à ces critères.

Gabarit

Vous pouvez ajouter un gabarit supplémentaire pour les données de l’usager, afin de définir précisément la manière dont les réservations s'affichent dans le listing de pointage.Par exemple, vous pouvez configurer le gabarit pour afficher des informations complémentaires, telles que les allergies alimentaires, directement sous le nom de l’usager.

Autres options

* Possibilité de basculer automatiquement l’évènement comme étant pointé une fois toutes les réservations pointées.
* Possibilité d'interdire le pointage des réservations une fois l’évènement marqué comme pointé.
* Possibilité d'activer le pointage des réservations sur les évènements à venir.

Pointer les inscriptions

⚙️ Accès dans le BO :Agendas > 👉 un agenda de type Évènements > 👉 un évènement > Pointage

Les agendas disposent d’un écran dédié, accessible via un bouton depuis la page d’accueil d’un événement. Cet écran permet de gérer les réservations des participants et d’indiquer leur présence ou leur absence. Il comporte un compteur intégré qui récapitule le nombre de réservations pointées en présence et en absence.

* Pointage rapide :une option « Marquer toutes les réservations non précisées » permet d'appliquer en un seul clic un statut à toutes les réservations non encore traitées.
* Validation du pointage :une fois le pointage terminé, un bouton permet de marquer l’évènement comme étant pointé. L’évènement reçoit alors une étiquette « Pointé » dans le listing.

Le pointage peut être réinitialisé si besoin.

Configurer le rapport de pointage

⚙️ Accès dans le BO :Agendas > 👉 un agenda de type Évènements > Rapport de pointage

Pour utiliser le rapport de pointage, il est nécessaire d’ajouter certains paramètres dans le webservice de réservation, à savoir :

* user_external_id
* user_first_name
* user_last_name

Il est possible de générer un rapport de présence/absence téléchargeable au format CSV en indiquant une date de début, une date de fin, le mode d'affichage des dates, des activités, etc.Il est également possible de grouper par cléapparaissant dans extra_data.

Dans le workflow, vous pouvez enrichir l'action de webservice de réservation en ajoutant les paramètres suivants :

* presence_callback_url:{{ form_api_url }}hooks/presence/
* absence_callback_url:{{ form_api_url }}hooks/absence/

Ces paramètres pourront ensuite être utilisée via une action globale déclenchée par un appel externe ayant par exemple pour identifiantpresence. Cela peut être particulièrement utile pour :

* mettre à jour une données de traitement, comme le statut de présence ;
* faire avancer automatiquement la demande vers un nouveau statut dans le workflow.

Agendas

* Studio
* Les tutos

# Assigner un utilisateur à un rôle métier

Assigner un utilisateur à un rôle métier

Il faut pour cela disposer des permissions associées aux rôles "Administrateur des rôles" et "Administrateur des utilisateurs" donc, le plus souvent, avoir le rôle d'administrateur fonctionnel (pour plus d'informations sur la distinction entre rôles techniques et rôles métier voir ici :https://doc-publik.entrouvert.com/admin-fonctionnel/gerer-les-roles/les-principes/).

Cette page traite de l'assignation d'un utilisateur à un rôle métier et de la suppression de cette assignation.

Deux possibilités pour faire l'assignation d'un utilisateur à un rôle, dans la partie Utilisateur ou dans la partie Rôle.

Vial'interface Utilisateur

* Dans le back office, menu latéral gauche, /Utilisateurs,
* Cliquer sur la fiche d'un utilisateur dans la liste proposée,
* Dans le menu latéral de droite, bouton « Modifier les rôles »,
* Sélectionner/désélectionner le ou les rôles à attribuer/désattribuer.

Vial'interface Rôle

* Dans le back office, menu latéral gauche, /Rôles,
* Cliquer sur la fiche d'un rôle métier dans la liste proposée,
* Dans le champ « Ajouter au rôle : » entrer le nom ou le prénom de l'utilisateur auquel on veut donner ce rôle,
* Dans la liste des comptes utilisateurs proposés, sélectionner le compte utilisateur auquel attribuer ce rôle,
* Cliquer sur le bouton « Ajouter ».

* Studio
* Les tutos

# Gérer le gabarit dans la barre latérale

Gérer le gabarit dans la barre latérale

Pour définir le gabarit des informations à afficher dans cet espace, il faut aller sur la liste des utilisateurs et dans le menu « bullet », sélectionner « Configuration avancée de gestion des utilisateurs ». Dans la fenêtre qui s'ouvre, indiquez votre texte, cela peut être du HTML et des gabarits.

<strong>L’usager {{ object.get_full_name }} peut se voir attribuer des rôles 
temporaires. 
Cliquez <a href="https://votre-instance/backoffice/data/devmutu-roles-temporaires">ici</a> 
pour en savoir plus.</strong>

Ou encore :

{% with mycards=cards|objects:"devmutu-roles-temporaires"|filter_by_user:object.uuid|filter_by_status:"Donner le rôle" %}
{% if mycards %}
<ul>
{% for card in mycards %}
<li><a href="{{ card|get:"url"}}">{{ card|get:"digest" }}</a></li>
</ul>
{% endif %}
{% endwith %}

Attribution de rôles temporaires

L'exemple ci-dessus reprend l'usage de rôles temporaires.

Il est possible de gérer l'attribution et le retrait de rôles de manière automatique avec l'application « Gestion des rôles temporaires »téléchargeable sur le catalogue.

Ces rôles sont stockés dans un modèle de fiche, le gabarit dans la fiche utilisateur pointe vers la liste des fiches.

Les tutos

* Paiement

* Studio
* Les tutos

Déclaration d'un service SAML

SAML (pourSecurity Assertion Markup Language) est un standard définissant un protocole pour échanger des informations liées à la sécurité; il propose notamment le nécessaire pour assurer l'authentification unique (en anglaissingle sign-onou SSO) sur le web.

Un service SAML est défini par un fichier de métadonnées (metadata)  qui décrit les URL et options concernant divers aspects du protocole.

Pour déclarer un nouveau service SAML, depuis la page d'administration technique d'Autentic, choisissez d'ajouter un « Fournisseur SAML » et complétez le formulaire :

* Identifiant est le nom du service tel que vous voulez le voir présenté aux usagers;
* Identifiant court est un identifiant interne;
* Collectivité permet d'attacher le service à une collectivité particulière;

La suite du formulaire concerne la description technique du service.  Si les métadonnées du service sont disponibles d'une URL publique, elle peut être renseignée ici, cela facilitera ensuite les mises à jour en cas de changement. Dans tous les cas, placez le fichier de métadonnées du service dans le champ.

La clé publique du service est normalement reprise dans le fichier de métadonnées, si ce n'était pas le cas, il est possible de poser ici cette information au format PEM. Le certificat SSL et les la chaine de certificat vers l'autorité de certification sont optionnels et doivent couramment être laissés vides.

Dans la section suivante, il est possible de régler des options de fonctionnement du service, les métadonnées peuvent en fait décrire plusieurs services, la première case à cocher permet de dire que le premier doit être activé, ce sera généralement le seul, il faut donc cocher la case.

Le règlement d'options de fournisseur de service permet de régler des options supplémentaires par rapport au protocole, ceux-ci seront décrits dans une autre page de la documentation (TODO).

Dans la dernière partie du formulaire, il est possible de définir des attributs supplémentaires qui seront passés lors de la phase d'authentification, généralement ceux-ci auront déjà été définis au niveau du règlement d'options et cette partie peut ainsi être laissée vide.

# Déploiement

Déploiement

Le déploiement des différents modules de Publik est géré depuis l'écran "Système", dans la section "Sites".  Un service s'ajoute en choisissant le module souhaité et en lui fournissant un titre, un identifiant et l'URL où il doit être déployé.

Alternativement, le déploiement peut être géré en ligne de commande via la commande "cook", en passant la définition du déploiement dans un fichier au format JSON.

Ce fichier liste les différentes étapes de déploiement, par exemple :

{
  "steps": [
    {"create-hobo": {
      "url": "https://admin.example.net/"
    }},
    {"create-authentic": {
      "url": "https://login.example.net/",
      "title": "Login"
    }}
}

Il est possible définir des variables qui permettront d'assurer des substitutions à l'intérieur même du fichier, en utilisant la syntaxe${variable}:

{
  "variables": {
    "domain": "example.net"
  },
  "steps": [
      "url": "https://admin.${domain}/"
    }},
      "url": "https://login.${domain}/",
    }}
}

Les variables peuvent également être chargées depuis un fichier externe :

{
  "load-variables-from": "variables.json",
  "steps": [
    }},
    }}
}

Actions

La première action doit nécessairement fournir la définition du service de déploiement, c'estcreate-hobo:

{"create-hobo": {
    }},

Les actions suivantes sont alors les déploiements des différents autres modules, via les commandescreate-authentic,create-combo,create-wcs,create-passerelle,create-fargo,create-welco,create-chrono,create-corbo,create-bijoe. Ces commandes prennent en paramètres obligatoires le titre et l'adresse du service et de manière optionnelle un identifiant (slug), un squelette et une série de variables.

{"create-combo": {
      "url": "https://backoffice.example.net/",
      "title": "Example",
      "template_name": "portal-agent",
      "slug": "portal-agent"
    }}

Les autres actions disponibles permettent de définir le fournisseur d'identités à utiliser; sans paramètre passé, ce sera le premier service Authentic déployé :

{"set-idp": {}}

De créer le super-administrateur du système; si un mot de passe n'est pas passé, il sera généré automatiquement et affiché sur la console.

{"create-superuser": {
      "username": "admin",
      "email": "admin@example.net",
      "password": "admin"
    }}

De définir l'intégration graphique à utiliser :

{"set-theme": {
      "theme": "example"
    }}

D'ajouter, activer ou désactiver des attributs pour le profil des usagers :

{"set-attribute": {
      "name": "phone",
      "label": "Téléphone",
      "order": 10,
      "asked_on_registration": true
    }},
    {"disable-attribute": {
      "name": "country"
    }}

Et de définir des paramètres globaux au système :

{"set-variable": {
      "name": "city_name",
      "label": "Nom de la ville",
      "value": "Trifouilly"
    }}