FAQ statique

Configuration FAQ statique

Description Générale

Dans un but de construction d’un portail de connaissances ou d’une FAQ, il peut être intéressant de lister toutes les thématiques disponibles ou les sous-thématiques liées à une thématique parent ou encore faire référencer le contenu de la base de connaissances sur un moteur de recherche. Pour tous ces cas, la génération d’une FAQ statique est nécessaire.

Ce que nous appelons FAQ Statique est la génération d’information à partir d’un extrait de la base de connaissances à un instant précis, sans actualisation du contenu par une API en temps réel.

1- BotId

Pour appeler l’API, un BOTID est obligatoire. Ce botID est trouvable sur le BMS dans le menu Paramètres > API > Accès aux APIs. Chaque bot a son propre BotId.

2- Process

Afin de générer une FAQ Statique, qu’il s’agisse de simples thématiques, de sous-thématiques ou des connaissances, il est toujours nécessaire de travailler à partir du fichier XML de base de connaissances.

Pour cela, nous allons diviser l’explication des sections suivantes selon deux axes :

Le premier pour le téléchargement du fichier XML de base de connaissances
Le second pour l’analyse du fichier XML afin d’en ressortir les informations intéressantes (nom des thématiques, sous-thématiques, connaissances…)

3- Téléchargement du fichier XML

3.1. Endpoint URL

Le endpoint de l’API est présent sur chaque serveur :

https://<serveur>/servlet/api/bot/knowledgebase/export

L’URL se compose également de deux paramètres :

botUUID : ID du bot à interroger
excludeGalleryContent : valeur pour indiquer si la galerie doit être exportée dans le fichier XML ou non (true pour ne pas exporter la galerie ; false pour exporter la galerie)

Enfin, il est également nécessaire de passer un token d'autorisation. Ce token d’autorisation est calculé de manière classique selon la méthode HTTP Basic (https://en.wikipedia.org/wiki/Basic_access_authentication).

Les login et mots de passe dont vous aurez besoin pour calculer le token sont ceux du BMS de dydu, cela signifie que ce ne sont pas vos identifiants SSO si vous utilisez le SSO pour vous connecter au BMS.

Exemple :

curl -X GET
 "https://<serveur>/servlet/api/bot/knowledgebase/export/<botId>/true" -H 
 "accept: application/xml" -H  "Authorization: authorizationToken"

3.2. Retour de l'API

Si la requête est valide, l’API retourne un fichier au format XML.

3.3. Limites

L’export de base de connaissances est limité à un seul export simultané par utilisateur pour des raisons de performance.

4- Analyse du fichier XML

Le fichier XML de base de connaissances contient de nombreuses informations.

Dans les prochains paragraphes, nous ne traiterons que des balises suivantes :

tags
knowledgesGroups

Les autres balises du fichier XML ne sont pas couvertes par cette documentation.

4.1. Lister les thématiques

La liste des thématiques est contenue au sein de la balise “tags”. La balise “tags” est composée d’une ou plusieurs balises “tag”.

Chaque balise “tag” est composée de la façon suivante :

Nom du tag

Description

Une seule balise id est présente pour indiquer l’id interne de la thématique

tagValue

Il y a autant de balises tagValue que de langues définies dans le bot.

Chaque balise comporte 2 attributs :

language : La langue dans laquelle est définie le libellé
value : Libellé de la thématique dans la langue spécifiée

Exemple :

<tags>
    <tag color="166da3">
      <id>1357</id>
      <tagvalue language="French" value="Nom de la thématique 1" translated="true"/>
      <tagvalue language="English" value="Name of Tag #1" translated="true"/>
    </tag>
    <tag color="ffffff">
      <id>1234</id>
      <tagvalue language="French" value="Nom de la thématique 2" translated="true"/>
      <tagvalue language="English" value="Name of Tag #2" translated="true"/>
    </tag>
</tags>

Pour la liste des thématiques, il faut lister l’ensemble des balises “tag” et lire la balise “tagValue” pour la langue souhaitée.

4.2. Lister les sous-thématiques

La liste des thématiques et sous-thématiques est contenue au sein de la balise “tags”. La balise “tags” est composée d’une ou plusieurs balises “tag”.

Chaque balise “tag” est composée de la façon suivante :

Nom du tag

Description

Une seule balise id est présente pour indiquer l’id interne de la thématique

tagValue

Il y a autant de balises tagValue que de langues définies dans le bot.

Chaque balise comporte 2 attributs :

language : La langue dans laquelle est définie le libellé
value : Libellé de la thématique dans la langue spécifiée

tag

Il y a autant de balises “tag” que de sous-thématiques directes.

Chaque sous-thématique peut également contenir des sous-thématiques.

C’est une structure récursive.

Exemple :

<tags>
    <tag color="166da3">
      <id>1357</id>
      <tagvalue language="French" value="Nom de la thématique 1" translated="true"/>
        <tag color="1a2b3c">
            <id>14890</id>
            <tagvalue language="French" value="Nom de la thématique 3"/>
            <tag color="000000">
                <id>13567</id>
                <tagvalue language="French" value="Nom de la thématique 4"/>
            </tag>
        </tag>
    </tag>
    <tag color="ffffff">
      <id>1234</id>
      <tagvalue language="French" value="Nom de la thématique 2" translated="true"/>
    </tag>
</tags>

Pour la liste des thématiques et sous-thématiques, il faut lister l’ensemble des balises “tag” et de lire la balise “tagValue” pour la langue souhaitée.

4.3. Lister toutes les connaissances

L’ensemble des connaissances sont incluses dans le noeud “knowledgesGroups”. La balise “knowledgesGroups” contient autant de noeuds “knowledgesGroup” que de connaissances.

Chaque noeud de type “knowledgesGroup” est composé de la façon suivante :

Nom du tag

Description

conditions

Ensemble des conditions qui peuvent déclencher tout ou partie d’une connaissance (intentions, condition pour une réponse complémentaire …)

knowledges

Ensemble des réponses de la connaissance (il peut y avoir plusieurs blocs de réponses s’il y a un arbre de décision)

popularity

Valeur interne dydu.

Pour lister les connaissances, il est préférable de lister d’abord les réponses puis les conditions.

Pour cela, il faut parcourir l’ensemble des connaissances, c'est-à-dire les nœuds “knowledgesGroup”, puis parcourir les réponses, c'est-à-dire le noeud “knowledges” qui contient lui même des noeuds “knowledge”.

Pour lister toutes les connaissances, il faut appliquer la même procédure :

Etape fonctionnelle

Etape technique

1. Parcourir toutes les connaissances

1. Parcourir tous les noeuds “knowledgesGroup”

2. Parmi les blocs de réponses, identifier la réponse liée à la question “racine”

2.1 Au sein du noeud “knowledges”, parcourir tous les noeuds “knowledge”

2.2 Trouver le noeud “knowledge” ayant un seul noeud “condition”

3. Identifier la question “racine” associée

3.1 Noter l’ID du noeud “condition” identifié à l’étape précédente

3.2 Au sein du noeud “knowledgesGroup”, parcourir le noeud “conditions”

3.3 Au sein du noeud “conditions”, parcourir les noeuds “simplecondition”

3.4 Identifier le noeud “simplecondition” ayant le même ID que l’ID noté en 3.1

Exemple ci-dessous avec un noeud “knowledgesGroup”:

2.1 1 noeud “knowledge” trouvé

2.2 Le noeud “knowledge” contient un noeud “conditions” qui contient 1 seul noeud “condition”

3.1 Notons l’id 419891

3.2 1 seul noeud “conditions”

3.3 1 seul noeud “simplecondition”

3.4 Le noeud “simplecondition” dispose bien de l’id 419891

<knowledgesGroup deleteTreeBeforeImport="false">
  <conditions>
    <simplecondition id="419891" rewordable="true" followingRefocusForbidden="false" trigger="true" contextualTrigger="false" persistentId="287023" faqExport="false">
      <conditionLanguage language="French" strict="false" optionalInFormulation="false" matchingType="None">
        <reword>Arbre de décision</reword>
        <sentences>
          <string>Arbre de décision</string>
        </sentences>
        <keywords/>
        <exclusions/>
        <bounceConditions/>
      </conditionLanguage>
    </simplecondition>
  </conditions>
  <knowledges>
    <knowledge id="419229">
      <actions>
        <action id="846322" garbageExclusive="false">
          <url></url>
          <botId>460</botId>
          <status>PUBLISHED</status>
          <sentence>Souhaitez vous consulter un arbre de décision ?</sentence>
          <language>French</language>
          <consultationSpace>754</consultationSpace>
          <sidebarTitle></sidebarTitle>
        </action>
      </actions>
      <conditions>
        <condition id="419891"/>
      </conditions>
      <tagId>20337</tagId>
      <creationTime>2020-10-05 17:16:48.0</creationTime>
      <lastModificationTime>2020-10-05 17:16:48.0</lastModificationTime>
    </knowledge>
  </knowledges>
  <popularity>0.0</popularity>
</knowledgesGroup>

4.4. Lister toutes les connaissances avec leur thématique

Dans les “actions” d’une connaissance, l’information de la thématique est présente via le “tagId”. Il est ensuite nécessaire via la liste des thématique d’associer cet Id au nom de la thématique pour récupérer la liste des connaissances avec leur thématique.

Exemple du tagId dans une connaissance :

knowledge > tagId

<knowledge id="408279">
  <actions>
    <action id="832305" garbageExclusive="false">
      <url></url>
      <botId>391</botId>
      <status>PUBLISHED</status>
      <lastModificationAccountId>558</lastModificationAccountId>
      <lastModificationTime>2019-10-28 12:02:18.0</lastModificationTime>
      <sentence>OK</sentence>
      <ignoreInAnalytic>false</ignoreInAnalytic>
      <language>French</language>
      <allowOnInvalidDate>false</allowOnInvalidDate>
      <complementaryAnswers/>
      <lockTextField>false</lockTextField>
      <keepPopinMinimized>false</keepPopinMinimized>
      <consultationSpace>613</consultationSpace>
      <sidebarTitle></sidebarTitle>
      <sidebarContent></sidebarContent>
      <sidebarWidth>500</sidebarWidth>
      <sidebarHeight>410</sidebarHeight>
      <stepIndex>0</stepIndex>
      <templateData>{}</templateData>
      <sidebarTemplateData>{}</sidebarTemplateData>
    </action>
  </actions>
  <conditions>
    <condition id="408943"/>
  </conditions>
  <tagId>9487</tagId>
  <creationTime>2019-10-28 12:02:08.0</creationTime>
  <lastModificationTime>2019-10-28 12:05:30.0</lastModificationTime>
</knowledge>

Récupération de la valeur de cette thématique dans la liste des thématique :

tags > id > value

<tags>
    <tag color="166da3">
      <id>8010</id>
      <tagvalue language="French" value="_Livechat" translated="true"/>
      <tagvalue language="Polish" value="_Livechat" translated="false"/>
    </tag>
    <tag color="c21473">
      <id>9487</id>
      <tagvalue language="French" value="Tests" translated="true"/>
      <tagvalue language="Polish" value="Tests" translated="false"/>
    </tag>
  </tags>

5- Annexes

5.1. Groupes de formulations

Les groupes de formulations sont présents dans le noeud “matchingGroups” - il n’y a qu’un seul élément de ce type. Les catégories de groupes de formulations sont quant à elles présentes dans le noeud “matchingCategories” - il n’y a qu’un seul élément de ce type.

Voyons comment est structuré un groupe dans formulations dans le XML :

Chaque groupe de formulations est défini au sein d’un noeud “group”, qui contient :

Un attribut “externalId” : Id interne du groupe de formulation. C’est cet ID qui est utilisé dans la base de connaissance, par les formulations qui utilisent le groupe de formulations.
Un noeud “categories” :
- Il contient un seul noeud de type “GroupCategoryMap” :
  - Il contient un seul noeud de type “categoryId” dont la valeur est l’ID de la categorie de groupe de formulations.
Un noeud “groupValues” :
- Ensemble de noeuds de type “groupValue” qui défini le titre du groupe de formulations par langue.
- Chaque “groupValue” contient deux attributs :
  - language : Langue dans laquelle est défini le titre
  - value : Titre du groupe de formulations
Un noeud “formulations” :
- Ensemble de noeuds de type “formulation” qui défini une formulation d’un groupe de formulations
- Chaque “formulation” contient plusieurs attributs, dont :
  - sentence : La formulation. Si la formulation contient elle même des groupes de formulations, seul l’ID de ces groupes sera présent
  - keyword : Défini si la formulation est de type keyword
  - language : Défini dans quelle langue est la formulation

5.2. Connaissances

5.2.1. Comprendre les conditions

La structure du noeud “conditions” est composée de différents noeuds :

simplecondition : noeuds de type intention simple (avec formulations, keywords, exclusions…)
pushcondition : noeuds de type condition pour le ciblage comportemental
apicondition : noeuds de type condition de contexte

Ces noeuds sont constitués des mêmes attributs mais un seul est important pour nous :

l’attribut “id” : il s’agit d’un ID interne qui permet de faire le lien entre les réponses que nous verrons plus tard et les conditions pour déclencher ces réponses.

Ces noeuds contiennent également d’autres noeuds de type “conditionLanguage”.

Il y a autant de noeud “conditionLanguage” qu’il y a de conditions par langues. Ils sont composés de la façon suivante :

Nom du tag

Description

Reword

Défini le titre de l’intention

Uniquement disponible pour simplecondition et pushcondition

sentences

Défini les formulations de l’intention. Ce noeud contient autant de noeuds “string” que de formulations

Non utilisé pour la FAQ Statique

Uniquement pour simplecondition

keywords

Défini les keywords de l’intention

Non utilisé pour la FAQ Statique

Uniquement disponible pour simplecondition

exclusions

Défini les exclusions de l’intention

Non utilisé pour la FAQ Statique

Uniquement disponible pour simplecondition

bounceConditions

Défini les conditions de rebond

Non utilisé pour la FAQ Statique.

Uniquement disponible pour simplecondition

optionalpart

Défini la condition de contexte (dans les noeuds “captureCondition”)

Non utilisé pour la FAQ Statique

Uniquement disponible pour apicondition

5.2.2.Comprendre les réponses

La structure du noeud “knowledges” est composée d’autant de noeuds “knowledge” qu’il y a de blocs de réponses dans la connaissance.

Chaque noeud “knowledge” est constitué des noeuds suivants :

actions : Noeud contenant les noeuds relatifs à la réponse
conditions : Noeud contenant les éléments qui déclenchent ce bloc de réponse
tagId : (facultatif) Indique l’id de la thématique parente
creationTime : Indique la date et l’heure de la création de ce bloc
lastModificationTime : Indique la date et l’heure de la dernière modification de ce bloc

Le noeud actions peut contenir les informations suivantes :

Nom du tag

Description

url

Url

status

Indique le statut de la réponse (Draft, Disabled, Published…)

sentence

Indique la réponse principale

language

Indique la langue de la réponse

consultationSpace

Indique l’id de l’espace de consultation

sidebarTitle

Indique le titre du panneau latéral s’il est défini

sidebarContent

Indique le contenu du panneau latéral s’il est défini

sidebarWidth

Indique la largeur du panneau latéral s’il est défini

sidebarHeight

Indique la hauteur du panneau latéral s’il est défini

5.2.3. Lister toutes les phrases générales

Les phrases générales sont présentes via le noeud botProfileAnswers.

Chaque phrase générale est défini dans un noeud “botProfileAnswer”, qui contient notamment :

Un élément “key” : Défini le type de la phrase générale. Il s’agit de valeurs internes dydu
Un élément “language” : Défini la langue de la phrase générale
Un élément “consultationSpace” : Défini l’ID de l’espace de consultation de la phase générale
Un élément “sentences” : Noeud contenant lui même un noeud “string” qui contient la phrase générale

On y retrouve notamment les réponses pour les cas : Réponse aux phrases incomprises (garbage) et Trop de phrases incomprises (toomanygarbages)

5.2.4. Lister toutes les préférences du bot

Les préférences d’un bot sont listées dans le noeud botPreferences.

5.2.5. Lister tous les espaces de consultation

Les espaces de consultation sont disponibles dans le noeud consultationSpaces.

PrécédentFAQ SuivantFAQ dynamique

Dernière mise à jour il y a 11 mois