Guide de démarrage pour les connecteurs (limité à certains partenaires)

***Les connecteurs sont limités à certains de nos partenaires technologiques. Si vous souhaitez établir une connexion entre votre système et votre projet Dialog Insight, notre équipe pourra vous proposer une solution qui correspondra à vos besoins et à votre structure de données.***

Les connecteurs servent à connecter des données de votre système vers un projet Dialog Insight à l'aide du endpoint Connector.MergeObject des services Web. Pour la destination de données, vous pouvez utiliser la structure standard e-commerce de Dialog Insight ou une structure personnalisée. 

Dans cet article, vous verrez comment mettre en place la structure nécessaire pour la connexion à l'aide d'un exemple dans lequel nous connecterons des données d'une liste de contacts ET d'une liste de transactions.

Étape 1 : Créer la destination pour les contacts

Dans Dialog Insight, commencez par créer un projet qui servira à recevoir et héberger votre liste de contacts :

Pour l'exemple présenté dans cet article, nous allons utiliser l'adresse courriel comme clé unique. Vous pourriez toutefois utiliser le numéro de client/membre ou un autre type de clé pour la gestion des doublons. 

Vous pourriez aussi avoir une structure multi-projets (CDP) pour une gestion plus avancée de vos contacts.
→ En savoir plus sur la structure CDP
Selon la structure des données à récupérer de votre système externe, vous pourriez ajouter des champs supplémentaires s'il manque des champs dans la structure de base du projet ou modifier les champs existants pour les adapter à votre cas.
→ Voir comment ajouter ou modifier des champs

Pour consulter la liste des champs générés lors de la création du projet, rendez-vous dans Projet → Gestion des données → Champs de projet.

Étape 2 : Créer la destination pour les transactions

Pour recevoir vos données de transactions, il faut créer une table qui servira à héberger vos transactions dans Dialog Insight. Vous avez 2 options pour créer cette table. 

Étape 3 : Ajouter des scripts de transformation

Les scripts de transformation vont convertir les données reçues dans le endpoint (Connector.MergeObject) avant de les envoyer à la liste de contacts ou la table de transactions. La plupart du temps, notre équipe vous fournira un script de transformation lors de l'accompagnement initial. Vous pourriez toutefois créer un script vous-même ou modifier un script existant, alors nous vous explierons comment faire.  

Créer ou éditer un script de transformation
Rendez-vous dans Projet → Gestion des données et, sous Intégrations, cliquez sur Configurations avancées :

Rendez-vous dans la section Scripts. Si vous voulez créer un nouveau script, cliquez sur Créer. 

Pour ajouter du contenu à un script (déjà existant ou que vous venez tout juste de créer), cliquez sur Consulter au bout de la ligne de ce script.

Ajoutez les scripts dans l'éditeur (voir les exemples plus bas) :

Après avoir ajouté le script, cliquez sur Sauvegarder et sur Publier en production. Retournez ensuite dans la liste des scripts et créez un autre script pour les transactions. 

Modèles de scripts de transformation
Ces scripts sont présentés à titre d'exemples et sont à adapter à votre cas.

// Exemple de script de transformation pour Contact
datasource contacts = context.Payload;
datasource contactListUpdater = System.Operations.ContactListUpdaters.GetCurrent();
datasource mapping = System.Operations.Mappings.Get(contactListUpdater, "ContactMapping");

foreach (contact in contacts)
{
    datasource contactDataSource = system.SourceHelper.CreateCollection();
    
    // Section Identification
    contactDataSource.SetValue("email", contact.email);
    contactDataSource.SetValue("firstName", contact.firstName);
    contactDataSource.SetValue("lastName", contact.lastName);
    
    // Section Coordonnées
    contactDataSource.SetValue("address", contact.address);
    contactDataSource.SetValue("app", contact.appartment_number);
    contactDataSource.SetValue("city", contact.city);
    contactDataSource.SetValue("province", contact.province);
    contactDataSource.SetValue("country", contact.country);
    contactDataSource.SetValue("postalcode", contact.postal_code);
    contactDataSource.SetValue("phone", contact.home_phone);
    contactDataSource.SetValue("mobile", contact.mobile_phone);
    
    // Application du mapping et chargement des données
    datasource mappedContact = mapping.MapWithMappingBase(contactDataSource);
    contactListUpdater.Merge(mappedContact);
}

// Exemple de script de transformation pour Transaction (la table standard de Dialog Insight)
datasource transactionPayload = context.Payload;

datasource transactionUpdater = System.Operations.RelationalTableUpdaters.GetByCode("ECommerce_Transaction");
datasource mapping = System.Operations.Mappings.Get(transactionUpdater, "TransactionMapping");

foreach (trx in transactionPayload)
{
    datasource trxDataSource = system.SourceHelper.CreateCollection();
    
    trxDataSource.SetValue("id", trx.id);
    trxDataSource.SetValue("email", trx.email);
    trxDataSource.SetValue("status", trx.status);
    trxDataSource.SetValue("price", trx.price);
    
    // Application du mapping et chargement des données
    datasource mappedtrx = mapping.MapWithMappingBase(trxDataSource);
    transactionUpdater.Merge(mappedtrx);
}

Étape 4 : Créer la correspondance des champs (Mappings)

Rendez-vous dans Projet → Gestion des données et, sous Intégrations, cliquez sur Configurations avancées. Dans la section Mappings, vous devrez ajouter un mapping pour les contacts et un autre pour les transactions :

Exemple de correspondance pour ContactLégende 

Étape 5  : Ajouter les MergeObjectHandlers

Rendez-vous dans la page de gestion des MergeObjectHandlers (MOH) en utilisant cette URL :
https://app.dialoginsight.com/fe/ofc4/mergeobject

Dans cette interface, ajoutez un MOH pour Contact ET un autre pour Transaction :

Étape 6 : Tester la connexion

Vous pouvez maintenant tester si votre connexion fonctionne en vous rendant dans l'interface en utilisant une des URL suivants :
Canada : https://app.dialoginsight.com/webservices/

France : https://app.mydialoginsight.com/webservices/

Authentification

Pour s'authentifier avec la partie AuthKey, vous devez au préalable :

• Créer une clé pour les services Web
• Vérifier que vous avez une des permissions suivantes :
  • Tous les services
  • Connector
  • Connecter.MergeObject

→ En savoir plus sur l'authentification

// Échantillon pour tester la connexion des transactions
{				
"AuthKey": {		
 "idKey": 5335,				
 "Key": "abcdefghijklmnopkrstuvwxyz"			
 },				
 "idProject": 11111,
 "objectCommand": Transaction/Update,		
 "Data": 
 [
     {			
     "id": "TX-1001",			
     "email": "jeandupont@dialoginsight.com",	
     "status": 1,				
     "price": 18.25			
     },			
     {			
     "id": "TX-1002",			
     "email": "jeffduval@dialoginsight.com",			
     "status": 2,			
     "price": 15.50			
     }				
 ]			
}