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 :