Principe d’interfaçage entre eCOS® et DATAKISS

DATAKISS est une solution SaaS conçue pour aider les clients à préparer la sectorisation future de leur force de vente. Cette solution nécessite des données relatives aux magasins, aux utilisateurs, aux domiciles et à l'organisation. Elle permet de créer de nouveaux secteurs ou régions, de supprimer des secteurs ou régions existants, ainsi que de modifier des secteurs en ajoutant ou en retirant des magasins. Il est possible d'y créer plusieurs scénarios, mais un seul peut être validé par le client.

Dans le cadre du partenariat entre EXTERNIS et DATAKISS, nous avons décidé d’interfacer nos solutions afin de simplifier les processus pour les administrateurs. Cette intégration permet une quasi-élimination des traitements via des fichiers Excel. Désormais, toutes les interactions se font par le biais d’appels API, sans aucun échange de fichiers entre les applications.

DATAKISS récupère depuis eCOS® les informations suivantes :

• Structure organisationnelle actuelle
• Utilisateurs actuels
• Lieux de livraisons actuels + géolocalisation + fréquence de visite
• Domiciles des utilisateurs
• Rattachement Lieu de livraison / Utilisateur actuel
• Informations théoriques transmisses par DATAKISS lors de la précédente sectorisation : 
  • Fréquence de visite théorique
  • Temps de visite moyen
  • Nombre de kilomètres théoriques
  • Nombre de jours terrain
  • Nombre de semaines travaillées
  • Nombre d’heures travaillés par jour

La solution eCOS® étant une solution terrain, elle dispose des données actuelles. De son côté, DATAKISS traite les données futures. Les deux solutions fonctionnent de manière indépendante en termes de bases de données.

Lorsque la future sectorisation élaborée dans DATAKISS est validée, les équipes d’EXTERNIS prennent en charge la réorganisation demandée par le client. Une fois les nouveaux utilisateurs et organisations créés dans eCOS®, la sectorisation validée dans DATAKISS est récupérée, permettant ainsi d’établir le lien entre les lieux de livraison et les utilisateurs.

eCOS® récupère depuis DATAKISS les informations suivantes :

• Nouveaux utilisateurs
• Nouveaux lieux de livraisons
• Rattachement lieux de livraisons - utilisateurs
• Informations théoriques renseignées dans DATAKISS : 
  • Fréquence de visite théorique
  • Temps de visite moyen
  • Nombre de kilomètres théoriques
  • Nombre de jours terrain
  • Nombre de semaines travaillées
  • Nombre d’heures travaillés par jour

Gestion d’un nouvel utilisateur créé dans DATAKISS : Lors de l’importation de la sectorisation, il est nécessaire d’établir un lien avec un utilisateur existant dans la base eCOS®.

Gestion d’un nouveau lieu de livraison : Si la référence du lieu dans DATAKISS correspond à celle présente dans eCOS®, le rapprochement est effectué automatiquement. Dans le cas contraire, le lieu sera ignoré.

Initialisation d'un nouveau client

EXTERNIS et DATAKISS définissent une correspondance pour leur client respectif. Chacun doit communiquer un code unique permettant d’identifier le client dans son système.

Exemple :

Mise en place du client « DEMOCLIENT »

DEMOCLIENT	ID client

EXTERNIS crée un utilisateur spécifique sur la plateforme client (nom d’utilisateur : datakiss) et communique à DATAKISS le nom d’utilisateur et le mot de passe.
EXTERNIS fournit également une clé API unique à utiliser pour la connexion.

De son côté, DATAKISS crée un utilisateur spécifique sur la plateforme client (nom d’utilisateur : externis) et communique à EXTERNIS le nom d’utilisateur et le mot de passe. DATAKISS doit également activer les permissions nécessaires pour le client concerné.

Principe d'authentification

Les APIs eCOS® sont disponibles sur 2 environnements : 

• Environnement de test (QA)
• Environnement de production (PROD) 

Chaque environnement possède une URL racine, représentée dans la documentation par <root> (exemple : <root>/Auth/Logon)

Les APIs sont toutes protégées par un Token, à l’exception de l’API d’authentification (logon) qui elle peut être appelée de manière anonyme.

DATAKISS doit appeler en premier l’API logon pour obtenir ce Token. Il doit ensuite être passé dans l’entête (header) de toutes les requêtes HTTPS pour l’appel des autres APIs.

Un fichier de configuration côté EXTERNIS existe permettant selon les environnements d’utiliser les bons environnements et APIs de DATAKISS. Il faut bien penser à le remplir correctement avant la mise en place.

Connexion DATAKISS → eCOS®

Pour se connecter sur eCOS®, DATAKISS doit réaliser 2 étapes : 

• S’identifier sur notre système : pour récupérer une entité User représentant le user « DATAKISS »
• Se connecter sur la plateforme du client: pour récupérer une version complétée du User, avec les infos utiles pour consommer le reste des APIs.

APIs :

• <root>/Auth/Logon 
• <root>/Auth/LogonApplication

API POST : 

<root>/Auth/Logon  (username, password, customer, apiKey)
@username =  xxx  
@password = xxx 
@customer = xxx
@apiKey =  xxx

Pour le Customer, c’est le nom de la plateforme eCOS® qui est attendu.

Connexion eCOS® → DATAKISS

Pour se connecter sur DATAKISS, eCOS® aura une Clé API fournit par DATAKISS

Chaque méthode appelée doit contenir la clé API + le Client Name qui correspond à notre nom du client eCOS® ou correspondance via une configuration de mapping possible.

DATAKISS doit donner la permission pour le client concerné avant un appel API sinon l’appel sera rejeté.

Informations techniques

• Authentification : création d'un utilisateur DATAKISS sur eCOS® spécifique à chaque plateforme client
• L’échange des données se fait uniquement via API, pas d’échanges de fichiers
• La référence et l’ID eCOS® d’un lieu seront envoyés comme clés et devront être renvoyés
• L’identifiant et l’ID eCOS® d’un user seront envoyés comme clés et devront être renvoyés
• Pour la fréquence de visite au lieu, on exportera la valeur paramétrée côté eCOS® calculée sur 1 an (52 semaines – 365 jours)
• Gestion multi organisations (CS-Promoteur pour le même lieu), On duplique les lieux autant de fois qu’il y a d’organisations rattachées au lieu (même référence eCOS®)
• Lors de l’envoi des datas de eCOS® vers Datakiss, eCOS® recevra l’ID_Scenario et devra le conserver. Cet ID pourra évoluer et eCOS® doit pouvoir le mettre à jour

Evolutions futures

Dans un futur proche, les informations théoriques DATAKISS seront utilisées dans les reports eCOS® afin de comparer le théorique au réel. Nous vous informerons des évolutions via les releases notes.