Documentation en ligne

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) des connecteurs existants.

Aller chercher des informations dans un fichier tableur est relativement aisé, vous pouvez construire une source de données et élaborer ensuite des requêtes avancées.

Enfin, il est possible de développer de nouveaux connecteurs webservices, 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)
 
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 visible parmi la 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ées raw du 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": [
      {"id": "1", "text": "rue du Château"},
      {"id": "3", "text": "place Denfert-Rochereau"}
    ]
  }
 
En plus des deux clés id et text obligatoires, on peut ajouter d'autres valeurs, par exemple :
    
  GET /liste-des-rues/
  {
    "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 :
    
  {
    ...
    "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 :
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 de credentials ; ç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?
  Host: logiciel-enfance
  {
    "name_id": "abc123def987",
    "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 (cf https://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
  Accept: application/json
  
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.
 
  POST /inscriptions/newsletter/14/jump/trigger/validate
  Host: demarches.example.net
  Accept: application/json
  Content-Type: application/json
  {"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 un appairage pré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 :

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.

Single Sign On (SSO)

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 : 

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

Dernière mise à jour le 3 avril 2023 14:10 — Éditer