FTP - synchronisation patrimoine par fichiers plats

﻿
FTP - principe et format﻿
IntentPlatform ne met pas d'espace FTP à disposition des clients. La plateforme créé un connecteur pour chaque client avec la configuration appropriée, ceci permettant à la fois de garantir l'étanchéité des données et d'assurer un fonctionnement indépendant.
Concernant l'import des fichiers, il est prévu que les fichiers soient déposés dans deux répertoires indépendants, un pour les éléments de patrimoine \assets et un autre pour les équipements \equipments
﻿
Format des fichiers﻿
Il y a au total 4 types de fichiers, variant en fonction du type d'objet concernés (patrimoine bâti ou équipements) et des actions requises :
﻿
Patrimoine : il existe 3 types de fichiers, utilisés pour la mise à jour du patrimoine, un pour les opérations de type CRUD (CReation / Update / Decommissionning), un pour les migrations et le dernier pour les partages.﻿Equipements : les équipements ne sont pas concernés par les migrations, et le partage des équipements reprend à l'identique le format de fichier des partages d'éléments de patrimoine. Il ne reste donc qu'un format de fichier correspondant aux opérations de type CRUD.
﻿
Les fichiers sont tous dotés d'une première colonne indiquant l'action à effectuer. Pour les fichiers de partage et de migration, spécifique, cette information est redondante et n'est présente que pour uniformiser la compréhension humaine des fichiers et faciliter leur lecture.
﻿
Le tableau suivant liste les 4 actions présentes et le nom du fichier associé.
Opération
postfixe du fichier
description
CREATE (pour un élément de patrimoine
_ASSET_CRUD
opération par défaut : création d'un NOUVEL élément de patrimoine
CREATE (pour un équipement)
_EQUIPMENT_CRUD
opération par défaut : création d'un NOUVEL équipement
UPDATE (pour un élément de patrimoine)
_ASSET_CRUD
mise à jour (y compris tag libres)
UPDATE (pour un équipement)
_EQUIPMENT_CRUD
mise à jour (y compris tag libres)
SHARE
_SHARE
partage sur un contrat
MIGRATE
_MIGRATE
déplacement d'un élément de patrimoine dans la hiérarchie patrimoniale
Pour des raisons de simplification, le format du fichier d'import initial du patrimoine (fichier CSV avec double-en-tête et partage des colonnes entre "PATH" et "TAG) n'a pas été conservé. Il a été remplacé par un fichier CSV à simple en-tête.
﻿
Format CSV
﻿
Le format CSV (Comma Separated Values, ou "valeurs séparées par des virgules") est un format au final assez mal maîtrisé parce que peu contraint.
Trois problèmes récurrents sont associés à ce format :
﻿
1) la confusion de séparateur : certains logiciels, dans leur version française, à l'instar de Microsoft﻿® Excel remplacent la virgule de sépararation par un point virgule. Ce remplacement est transparent pour l'utilisateur mais rend le fichier incorrect. Il faut bien veiller à ce que la séparation des valeurs soit la virgule. Cela implique par ailleurs que le séparateur numérique des décimales soit le point.
﻿
2) les chiffres avec un zéro en tête : la prise en compte des chiffres commençant par 0 peut être problématique, beaucoup de logiciels interprètent incorrectement la valeur (soit lors de la lecture, soit lors de l'écriture) et la traduisent en valeur numérique, donc sans les 0. La solution consiste à correctement ajouter des guillemets ( en utilisant le caractère anglo-saxon : " ) pour encadrer la valeur, afin qu'elle soit interprétée comme une valeur de type texte.
﻿
3) les chaines de caractères : Pour encadrer une chaine de caractères, il est requis d'utiliser les guillemets à l'anglo-saxonne : " (double quote) pour encadrer les valeurs de texte.
﻿
A l'exception des opérations nécessitant un format de fichier spécifique, comme les migrations et les partages, un même fichier peut comporter plusieurs types d'opérations. En revanche, rien n'empêche d'avoir un fichier par opération si cela simplifie leur génération.
﻿
Decommissionnement
﻿
Il n'y a pas d'opération spécifique pour le décommissionnement d'un élément de patrimoine ou d'un équipement. L'opération est effectuée en mettant à jour (opération UPDATE) la valeur Intent_decommissioning_date avec la date de sortie de l'élément.
Il est à noter qu'il n'existe pas d'opération de suppression d'un élément du patrimoine.
﻿
Tableau des valeurs pour le fichier CRUD des éléments de patrimoine :
Nom du champ
	valeur
commentaire
intent_action*
CREATE / UPDATE
action concernant la ligne
intent_reference*
libre
référence unique de l'élément de patrimoine
parentPath*
concaténation du path de l'élément auquel se rattache l'élément en cours, avec l'ensemble des codes séparés par "/"
simplification du fonctionnement du fichier d'import
code*
libre
code de l'élément
label
libre
libellé de l'élément
category
libre
catégorie de l'élément (titre de l'élément dans la hiérarchie patrimoniale)
intent_type
libre
type de l'élément
intent_address_way
libre
numéro et nom de la rue
intent_address_zip
libre
code postal
intent_address_city
libre
ville
intent_address_complement
libre
complément de l'adresse
intent_address_country
code du pays
pays
intent_longitude
nombre (entre -180 et 180)
longitude de l'élément
intent_latitude
nombre (entre -90 et 90)
latitude de l'élément
intent_surface
nombre ( > 0,0001)
surface de l'élément
intent_contacts
vCard (v3)
le(s) contacts associés à l'élément de patrimoine
intent_decommissioning_date
date (format ISO8601)
date de sortie de l'élément du patrimoine client
intent_commissioning_date
date (format ISO8601)
date d'entrée de l'élément dans le patrimoine client
[tag libre]
texte
toute valeur dont le nom ne commence pas par intent_ est considérée comme un tag libre.
champ obligatoire*
﻿
Mise à jour (UPDATE) et Gestion des tags libres
﻿
Chaque ligne doit contenir l'ensemble des tags, cela signifie que chaque mise à jour va écraser l'ensemble des tags puis enregistrer les valeurs placées dans la ligne du fichier.
Cela signifie que pour retirer une valeur, il suffit de ne pas la faire figurer dans la ligne de mise à jour.
Cela implique aussi que la mise à jour d'un élément doit contenir TOUS les tags déjà présent sur cet élément. Tout tag omis sera considéré comme "à effacer" pendant la mise à jour.
Contact sur un élément de patrimoine
﻿
Vous pouvez indiquer 1 ou plusieurs contacts sur un élément de patrimoine. Dans votre fichier, la vCard devra contenir les \n ou les \r\n
﻿
﻿ Plus d'explications sur les contacts d'un élément de patrimoine ﻿
﻿
Tableau des valeurs pour le fichier CRUD des équipements :
﻿
Nom du champ
	valeur
commentaire
intent_action*
CREATE / UPDATE
action concernant la ligne
intent_reference*
libre
référence unique de l'élément de patrimoine
intent_type
libre
type de l'élément
installationReference
référence d'un élément de patrimoine existant
référence de l'élément de patrimoine auquel l'équipement est physiquement rattaché﻿(exemple : bâtiment @)
usageLinkReferences
liste (utilisant la , comme séparateur et les "..." pour encadrer la chaine de caractères) de références d'élément de patrimoine existant
référence(s) de(s) élément(s) de patrimoine déservis par l'équipement
label
libre
libellé de l'élément
intent_address_way
libre
numéro et nom de la rue
intent_address_zip
libre
code postal
intent_address_city
libre
ville
intent_address_complement
libre
complément de l'adresse
intent_address_country
code du pays
pays
intent_contacts
vCard (v3)
le(s) contacts associés à l'élément de patrimoine
intent_latitude
nombre (entre -90 et 90)
latitude de l'élément
intent_longitude
nombre (entre -180 et 180)
longitude de l'élément
intent_decommissioning_date
date (format ISO8601)
date de sortie de l'élément du patrimoine client
intent_commissioning_date
date (format ISO8601)
date d'entrée de l'élément dans le patrimoine client
[tag libre]
texte
toute valeur dont le nom ne commence pas par intent_ est considérée comme un tag libre.
champ obligatoire*
﻿
Tableau des valeurs pour les fichiers de type SHARE :
Nom de la valeur
valeur
commentaire
intent_action*
SHARE / UNSHARE
intent_reference*
référence d'un élément de patrimoine ou d'un équipement existant
référence de l'élément à partager
intent_contract_reference*
référence d'un contrat existant
référence du contrat sur lequel on va partager l'élement de partimoine ou l'équipement
champ obligatoire*
﻿
Partage unitaire
Le partage d'un élément n'implique pas le partage de ses fils (éléments situés en dessous dans la hiérarchie) ou des éléments rattachés.
Il est nécessaire de partager unitairement l'ensemble des éléments figurant au contrat
﻿
﻿
Partage du patrimoinePartage du patrimoine
Tableau des valeurs pour les fichiers de type MIGRATE :
Nom de la valeur
valeur
commentaire
intent_action*
MIGRATE
intent_reference*
référence d'un élément de patrimoine existant
référence de l'élement à migrer
parentPath*
concaténation du path de l'élément auquel se rattache l'élément en cours, avec l'ensemble des codes séparés par "/"
fullpath de l'élement sous lequel on va migrer l'élément de patrimoine concerné.
champ obligatoire*
﻿
Règles de nomage﻿
Il n'y a pas à proprement parler de règle de nomage, en dehors du postfixe conseillé. En revanche, afin de rendre les échanges et le traitement des rapports d'exécution plus faciles, nous proposons la règle suivante :﻿[DOMAIN]SynchronisationPatrimoine[DATE]_[POSTFIXE].csv
Avec :﻿[DOMAIN] le nom de l'entité cliente sans espace (par exemple : ToitSocialHabitat).﻿[DATE] la date de dépot du fichier, respectant le format AAAA-MM-JJ.﻿Et [POSTFIXE] la valeur correspondant au type de fichier, tel que décrit dans le tableau ci-dessus.
﻿
Suivi d'exécutionIl vous est possible de suivre l'avancement du traitement des fichiers de votre serveur FTP/SFTP avec notre API Jobs.
﻿
URL
/api/jobs/v1/jobs
verbe HTTP
POST
﻿
Un JSON de retour
{
    "_links": {
        "self": {
            "href": "https://api.hubintent.com/api/jobs/v1/jobs?since=2020-10-13"
        }
    },
    "_embedded": {
        "jobs": [
            {
                "id": 28024,
                "filename": "1602489960000_ToitSocialHabitat_SynchronisationPatrimoine_2020108.csv",
                "status": "done",
                "nLinesToProcess": 514,
                "nProcessedLines": 514,
                "creationDate": "2020-10-13T10:10:19+02:00",
                "lastUpdateDate": "2020-10-13T10:27:14+02:00",
                "_links": {},
                "source": {
                    "id": "xxxxxda-9f34-413e-9a0b-b0fa4fxxx",
                    "protocol": "ftp",
                    "type": "asset",
                    "label": "Synchronisation des assets"
                }
            }
        ]
    },
    "total": 1
}
﻿
Le champ status vous indique l'état de traitement du fichier :
to do : A traiter
pending : En cours
done : Traité
error : En erreur
Si votre fichier est en erreur, le JSON vous indiquera les erreurs rencontrées.
﻿
Bonnes et mauvaises pratiques﻿
De manière générale, la synchronisation du patrimoine et des équipements est à configurer en fonction de la fréquence de mise à jour du patrimoine "dans la vraie vie". Il est très rare de se retrouver en situation d'urgence pour la mise à jour d'un patrimoine et, dans la plupart des cas de figure, un fonctionnement hebdomadaire sera largement suffisant, d'autant plus qu'une fréquence d'exécution trop rapide pourrait avoir comme conséquence, en cas d'erreur dans un fichier, d'empiler des exécutions en erreur, et donc des rapports d'exécutions multiples.
﻿
Exécution séquentielle
﻿
La lecture et donc la prise en compte des lignes se fait séquentiellement, de haut en bas. Cela signifie qu'il convient de vérifier qu'il n'y a pas de contradictions entre plusieurs lignes du fichier, par exemple une opération UPDATE placée avant l'opération CREATE du même élément.
De manière générale, il est de toute manière préférable de ne placer qu'une seule ligne concernant un élément de patrimoine ou un équipement par fichier.
Volumétrie
﻿
Les opérations de synchronisation par fichier plat ne sont pas prévues pour permettre un import initial ou des opérations sur l'ensemble du patrimoine.
Elles sont à réserver à des opérations de synchronisation du patrimoine, par exemple en relation avec un logiciel de gestion du patrimoine, de type ERP.
﻿
Dans la même logique, les fichiers à envoyer en entrée du processus sont des fichiers différentiels, c'est à dire listant uniquement les modifications apportées au patrimoine depuis la synchronisation précédente.
﻿
Le non-respect de ces règles entraînerait immédiatement la déconnexion du connecteur FTP et l'arrêt de la synchronisation.
Contacts vides
﻿
Il convient de ne pas insérer de contacts vides au format vcard, ceci occasionnant des problèmes d'interprétation des contacts.
Si un élément de patrimoine n'a pas de contact associé, la cellule correspondante devra rester vide.