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 erreurdata
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 rechercheurl
: l'URL de l'objet, typiquement un lien vers la page du système tiers qui va afficher l'objetdescription
(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.