Projet

Général

Profil

API du module de recherche de Combo

Publik, au travers de son logiciel Combo, peut présenter à l'utilisateur un champ texte permettant d'effectuer une recherche. L'utilisateur tape une requête comme dans un moteur de recherche classique, Combo va alors interroger un ou plusieurs moteurs et en afficher les résultats. Des moteurs de recherche sont directement intégrés à Publik :
  • recherche dans les demandes
  • recherche dans les utilisateurs
  • recherche dans les pages du portail
  • recherche de code de suivi

Le module de recherche peut être étendu à d'autres systèmes dès qu'ils proposent un webservice compatible. Ce document détaille le format du webservice attendu.

Requête

Le système de recherche de Combo va lancer une requête HTTP GET sur une URL, en lui envoyant en paramètre (query-string) la chaîne de caractère saisie par l'utilisateur :

GET https://example.net/search/?q=foobar

Le nom du paramètre "q" est en fait libre, dans les exemples qui suivent nous continuerons à l'appeler "q". "foobar" est la chaîne de caractère saisie par l'utilisateur.

Combo peut également envoyer un paramètre contenant l'email de l'utilisateur effectuant la recherche. Cela permet au système tiers de ne renvoyer que les résultats pertinents pour cet utilisateur. Exemple de requête :

GET https://example.net/search/?email=login@example.org&q=foobar

Ici encore le paramètre "email" peut être nommé autrement.

Dans des intégrations plus fortes, si le système tiers est déjà lié à Publik par un SSO, il est possible d'envoyer dans la requête l'identifiant de fédération (sub ou NameID).

Réponse

La requête GET doit recevoir une réponse en JSON, sous la forme suivante :

GET https://example.net/search/?q=foobar

200 OK
Content-type: application/json

{
  "err": 0,
  "data": [
    {
      "url": "https://files.example.net/dossier/3/",
      "text": "Dossier foobar",
      "description": "Dossier numéro <b>3</b>, en date du <i>10/12/2019</i>" 
    },
    { ...objet2... }, ...
  ]
}
  • err est un entier, 0 indique que tout s'est bien passé. Toute autre valeur est interprétée comme une erreur
  • data est une liste des objets trouvés, dans l'ordre de pertinence
  • chaque objet est un dictionnaire contenant les clés/valeurs suivantes
    • text : nom de l'objet, sur une seule ligne, qui sera affiché à l'utilisateur effectuant la recherche
    • url : l'URL de l'objet, typiquement un lien vers la page du système tiers qui va afficher l'objet
    • description (optionnel) : une description plus longue, autorisant un peu de formatage HTML si besoin

Personnalisation de l'affichage des résultats

Un objet peut contenir d'autres clés dont les valeurs sont jugées utiles à présenter à la personne qui fait une recherche. Par exemple sur une recherche d'usager, on pourrait avoir :

  "data": [
    {
      "url": "https://users.example.net/user/3/",
      "text": "Ferdinand Poitevin",
      "first_name": "Ferdinand",
      "last_name": "Poitevin",
      "dob": "1860-10-09",
      "phone": "+33123456789",
      "mobile": "+33612345678",
      "address": "169 rue du Château, Paris" 
    }, ...

Ces valeurs peuvent être utilisées pour personnaliser le rendu des résultats. Un gabarit sera programmé dans Combo pour afficher le résultat du moteur.

Personnalisation en fonction de l'usager

Combo peut envoyer un paramètre « email=... » lors de la recherche. Dans ce cas, les résultats peuvent être modulés en fonction de cet email, qui représente utilisateur qui effectue la recherche.

Il peut être décidé :
  • de ne pas remonter certains objets résultats qui ne doivent pas être affichés à l'utilisateur
  • de ne pas donner certains détails sur certains résultats
  • de ne pas indiquer d'URL si l'objet n'est en fait pas accessible à l'utilisateur (on lui affichera juste que l'objet existe)
  • de changer l'ordre de pertinence
  • etc.

Exemple de rendu

Formats disponibles : PDF HTML TXT