Import/Export du bot
1. Objectif
Il est possible d'exporter puis d'importer - c'est-à-dire dupliquer ou cloner - un bot avec les API du BMS. Généralement, cette opération est effectuée en vue de dupliquer une instance de production vers une instance de recette ou basculer d'un serveur SaaS vers un serveur OnPremise.
2. Mode opératoire
La procédure se déroule en 4 temps (hors étape facultative) :
Lancer un export du bot
Attendre la fin de l'export du bot / Vérification du statut de l'opération
[Facultatif] Télécharger l'export du bot
Lancer l'import du bot
Attendre la fin de l'import du bot / Vérification du statut de l'import
2.1 Prérequis
Afin de pouvoir réaliser l'ensemble des étapes, il sera nécessaire de disposer :
De l'UUID du bot à exporter - bot source
De l'UUID du bot cible
Du token sur le serveur du bot à exporter (cf. Authentification "Basic HTTP")
Du token sur le serveur du bot cible (cf. Authentification "Basic HTTP") et de connaître les pages d'appel aux API de dydu.
Ces pages sont accessibles via l'adresse suivante : https://[server]/servlet/api/doc3/index.html
Par exemple, pour le serveur SaaS earth, il s'agit de : https://app1.earth.doyoudreamup.com/servlet/api/doc3/index.html. Chaque API est ensuite accessible dans sa catégorie.
2.2 Export du bot
L'export du bot s'effectue grâce à l'API Export bot data, disponible dans la catégorie Transfer Bot data.
Remplissez les champs nécessaires puis lancez l'export :
botUUID : UUID du bot à exporter (ex: "52345ac9-1804-4898-96df-5ce03d800e50")
includeGalery : true (Sauf exception si vous ne souhaitez pas exporter la galerie)
Authorization : token d'autorisation (ex : "Basic bG9naW46bW90ZGVwYXNzZQ==")
DialogsPassword : mot de passe permettant de décoder les dialogues (Remplir uniquement si vous avez activé l'option "Encrypter les dialogues" dans le BMS, sinon laissez vide). Puis cliquez sur
Execute
2.2.1 Succès
Si tout va bien, vous devriez avoir un code de retour 202 et aucun message de retour.
2.2.2 Erreurs
Si vous avez une erreur 403, avec un message de type :
"error": "Missing or invalid parameters [authentication]"
Pensez à vérifier si votre couple login / mot de passe est correct et si vous n'avez pas oublié le "Basic " avant votre token encodé.
2.3 Attendre la fin de l'export / Vérification du statut de l'opération
L'export du bot s'effectue grâce à l'API Get export bot data status, disponible dans la catégorie Transfer Bot data.
Remplissez les champs nécessaires puis lancez l'opération :
botUUID : UUID du bot à exporter (ex: "52345ac9-1804-4898-96df-5ce03d800e50")
Authorization : token d'autorisation (ex : "Basic bG9naW46bW90ZGVwYXNzZQ==")
2.3.1 Succès
Si tout se passe bien, vous devriez avoir un code retour 200 et un message de retour confirmant la bonne opération. Dans le message de retour, il sera indiqué "exportStatus" : "DONE".
Si l'export est long - dans le cadre de bases de connaissances importantes ou dialogues nombreux - le message de retour comportera "exportStatus":"PROCESSING". Dans ce cas, il faudra vérifier le statut ultérieurement (après 5-10 minutes) pour voir si l'export est terminé.
2.3.2 Erreurs
En cas d'erreur, vous aurez tout de même un code retour 200. Dans le message de retour, il sera indiqué "exportStatus":"ERROR".
La ou les raisons de ces erreurs sont détaillées dans le message. Une des raisons est le problème de synchronisation des configuration des chatbox. Vous verrez alors un message de type "configurationsStatuses":{"5588419e-2fc7-4266-97aa-bd0982d2593c":"TO_FIX". Cela explique que la chatbox ayant l'ID 5588419e-2fc7-4266-97aa-bd0982d2593c doit être fixée avant l'export.
2.4 Télécharger l'export du bot
Cette étape est facultative et non recommandée car elle ajoute de la complexité dans le processus.
Si vous souhaitez télécharger les données de votre bot, il faut utiliser l'API Get exported bot data, disponible dans la catégorie Transfer Bot data.
Remplissez les champs nécessaires puis lancez l'opération :
botUUID : UUID du bot à exporter (ex: "52345ac9-1804-4898-96df-5ce03d800e50")
Authorization : token d'autorisation (ex : "Basic bG9naW46bW90ZGVwYXNzZQ==")
Succès Si tout se passe bien, vous devriez avoir un code retour 200 et un lien qui s'affiche vous permettant de télécharger le fichier.
2.5 Import du bot
L'import du bot s'effectue grâce à l'API import bot data from url, disponible dans la catégorie Transfer Bot data.
Cette API permet d'importer un zip depuis une URL, que ce soit l'URL d'export de bots ou une URL classique type https://www.monsite.com/exports/monbot.zip.
Remplissez les champs nécessaires puis lancez l'export :
botUUID : UUID du bot cible (ex : "c3e2fc66-6139-11eb-ae93-0242ac130002")
Authorization : token d'autorisation du bot cible (ex: "Basic bm91dmVhdWxvZ2luOm5vdXZlYXVtbW90ZGVwYXNzZQ==")
Url-Authorization : token d'autorisation du bot source (ex : "Basic bG9naW46bW90ZGVwYXNzZQ==")
body : Url du zip (ex: "https://www.monsite.com/exports/monbot.zip") ou de l'API d'export (ex : "https://app1.earth.doyoudreamup.com/servlet/api/bot/exported/c3e2fc66-6139-11eb-ae93-0242ac130002")
Deux notables ici :
Il n'est possible d'importer une configuration que sur un bot existant. Si vous n'avez pas de bot, il est nécessaire d'en créer un auparavant. Si vous importez sur un bot existant, les données existantes ne seront pas supprimées. Le champ Url-Authorization n'est utile que si vous récupérez l'export depuis l'API d'export du BMS.
Succès Si tout se passe bien, vous devriez avoir un code retour 202 et aucun message de retour.
2.6 Attendre la fin de l'import / Vérification du statut de l'opération
L'import du bot s'effectue grâce à l'API Get import bot data status, disponible dans la catégorie Transfer Bot data.
Remplissez les champs nécessaires puis lancez l'opération :
botUUID : UUID du bot cible (ex : "c3e2fc66-6139-11eb-ae93-0242ac130002")
Authorization : token d'autorisation du bot cible (ex: "Basic bm91dmVhdWxvZ2luOm5vdXZlYXVtbW90ZGVwYXNzZQ==")
2.6.1 Succès
Si tout se passe bien, vous devriez avoir un code retour 200 et un message de retour confirmant la bonne opération. Dans le message de retour, il sera indiqué "importStatus":"DONE".
Ce message de retour - au format JSON - contiendra également le détails de l'import :
startDate et endDate : respectivement la date de début de l'import et la date de fin de l'import
importedKnowledges : Retour sur l'import des connaissances
importedDialogs : Retour sur l'import des dialogues
importedUsers : Retour sur l'import des utilisateurs
Si l'export est long - dans le cadre de bases de connaissances importantes ou dialogues nombreux, le message de retour comportera "importStatus":"PROCESSING". Dans ce cas, il faudra vérifier le statut ultérieurement (après 5-10 minutes) pour voir si l'export est terminé.
2.6.2 Erreurs
En cas d'erreur, vous aurez tout de même un code retour 200. Dans le message de retour, il sera indiqué "importStatus":"ERROR".
La ou les raisons de ces erreurs sont détaillées dans le message.
3. Limites de l'export / import
Cette opération d'export / import de bot fonctionne bien pour les éléments suivants :
Base de connaissances
Configuration des chatbox v4
Les utilisateurs
Les langues et espaces de consultation
mais deux points nécessitent une attention particulière.
Le premier concerne les dialogues qui ne sont pas exportés en totalité mais seulement en partie. Concrètement, l'opération d'export ne fait qu'exporter les dialogues des 30 derniers jours et il n'est pas possible d'aller au delà.
Le second point concerne les groupes de formulations de la base sociale ou de bases externes - type metabot. La liaison avec les groupes de formulations issus de bots externes n'est pas toujours conservée. Concrètement, l'utilisation de groupes de formulations de la base sociale ou de bases externes fait référence à des ID. Ces IDs ne sont pas forcément les mêmes d'un serveur à l'autre et nécessitent donc une modification manuelle. Les groupes de formulations définis au sein du bot seront bien conservés et correctement importés.
4. Logs
Les traces des imports sont disponibles une fois que l'action est terminée. Pour cela, vous pouvez vous rendre dans la section "Console" et afficher les messages en Info. Exemple :
Dernière mise à jour
