Dokos Data Hub
Dokos Data Hub
Dokos Data Hub reçoit les fichiers que vos partenaires déposent sur un serveur SFTP. Il lit chaque fichier et crée les documents correspondants dans Dokos. Il convient aux échanges de données informatisés (EDI) : commandes, avis d'expédition, référentiels, relevés. Il envoie aussi des exports planifiés vers un serveur SFTP ou un stockage cloud.
L'application n'a pas encore de traduction française. Ses écrans et ses types de documents s'affichent en anglais.
Comment un fichier devient un document
- Une DDH Connection décrit un serveur SFTP, le dossier à relever et la fréquence de relève.
- Une DDH Mapping décrit un format de fichier et le type de document à créer. Son motif de nom de fichier est le seul filtre : un fichier qu'aucune correspondance active ne reconnaît reste sur le serveur, sans être téléchargé.
- Chaque fichier reconnu crée une DDH Inbound File. Un fichier déjà reçu, avec le même contenu, n'est pas repris. Data Hub choisit la première correspondance active de la connexion dont le motif correspond.
Le planificateur de tâches relève les connexions et traite les fichiers. Il doit être actif sur le site.
Prérequis
- L'application Dokos Data Hub est installée sur votre site.
- Vous avez l'adresse du serveur SFTP, un identifiant, et un mot de passe ou une clé SSH.
- Le type de document cible a un champ de type Lien nommé
ddh_inbound_file, qui pointe vers DDH Inbound File. Sans ce champ, la correspondance ne s'enregistre pas. Ajoutez-le si besoin avec un Champ personnalisé. - Si le partenaire envoie des archives (
.zip,.tar,.gz), créez d'abord un stockage DDH S3 Storage (AWS S3 ou Azure Blob Storage). Une connexion sans stockage refuse les archives.
Exemple : relever les livraisons d'un transporteur
Dokompany reçoit chaque nuit un fichier CSV de son transporteur (fictif) : LIVRAISONS_20261031.csv. Chaque ligne donne un numéro de colis, une date de livraison et un code statut (LIV, RET). Dokompany veut une fiche par colis dans un type de document personnalisé « Suivi colis », qui a le champ ddh_inbound_file.
Créer la connexion
- Ouvrez l'espace Dokos Data Hub, puis DDH Connection, et créez une connexion.
- Saisissez un Title, par exemple
Transporteur. - Dans l'onglet Connection, renseignez Host, Port (22 par défaut) et Username.
- Choisissez l'Authentication Method : Password, SSH Key ou SSH Certificate. Renseignez le secret correspondant.
- Dans l'onglet Paths, renseignez le Remote Path, le dossier à relever, par exemple
/depot/livraisons. - Renseignez Archive Path pour y déplacer les fichiers traités, et Error Path pour les fichiers en échec. Ces deux champs sont facultatifs.
- Dans l'onglet Schedule & Retention, choisissez le Schedule Type. Interval relève toutes les N minutes (Polling Interval (minutes), 5 par défaut). Cron suit une Cron Expression, par exemple
0 6 * * *pour 6 h chaque jour. - Enregistrez, puis cliquez sur Test Connection.
Le message Connection Successful confirme l'accès au dossier. Le bouton Create Test File dépose un fichier texte dans le dossier pour tester la chaîne complète.
Créer la correspondance
- Ouvrez DDH Mapping et créez une correspondance.
- Saisissez un Title et choisissez la Connection
Transporteur. - Dans l'onglet File Identification, choisissez le File Format CSV.
- Renseignez File Name Pattern (regex) :
^LIVRAISONS_.*\.csv$. Ce motif est une expression régulière. Il décide aussi des fichiers relevés sur le serveur. Laissez-le vide pour accepter tous les fichiers de la connexion. - Réglez File Encoding, CSV Delimiter et CSV Has Header selon le fichier.
- Dans l'onglet Target, choisissez la Target DocType « Suivi colis ».
- Choisissez la Duplicate Handling : Create new, Update existing ou Skip. Pour Update existing et Skip, renseignez la Match Field, par exemple le champ du numéro de colis.
- Dans l'onglet Field Mappings, ajoutez une ligne par champ : la colonne source dans Source Path, le champ cible dans Target Field.
- Pour traduire le code statut, ajoutez une ligne dans Code List Mappings. Elle utilise une liste de codes.
- Enregistrez.
Au passage suivant, chaque ligne du fichier crée une fiche « Suivi colis ».
Référence des correspondances
Formats de fichier
| File Format | Root Path | Source Path |
|---|---|---|
| CSV | Ignoré | Nom de la colonne. Sans en-tête (CSV Has Header décoché), utilisez Column Number (à partir de 1). |
| XML | Chemin de l'élément qui contient un enregistrement | Chemin relatif à l'enregistrement |
| JSON | Chemin de la liste des enregistrements | Clé relative à l'enregistrement |
| Fixed Width | Ignoré | Chaque champ est défini par Start Position et Length. |
Lignes de champs
Une ligne Field Mappings a ces options :
- Required : le fichier échoue si la valeur manque.
- Default Value : la valeur utilisée si la source est vide.
- Transform : Uppercase, Lowercase, Strip, Date (ISO), Date Format (avec un Date Format au format
strftime, par exemple%d/%m/%Y) ou Custom.
Custom exécute du code Python saisi dans la correspondance. Réservez cette option aux administrateurs.
Traduire des codes avec une liste de codes
Une ligne Code List Mappings lit un code dans le fichier et le remplace par le nom d'un document Dokos. Elle s'appuie sur une Liste de codes de Dokos. Si le code est inconnu et que Fallback to Default est coché, la valeur par défaut de la liste de codes s'applique.
Doublons et import en masse
| Duplicate Handling | Effet | Match Field |
|---|---|---|
| Create new | Crée toujours un document. | Facultatif |
| Update existing | Met à jour le document trouvé, sinon le crée. | Obligatoire |
| Skip | Ignore l'enregistrement si un document existe, sinon le crée. | Obligatoire |
Bulk Insert (bypass ORM) écrit directement en base, sans validations, sans règles de nommage et sans événements. Il accélère les gros fichiers. Il ne fonctionne pas avec Update existing.
Suivre les fichiers reçus
La liste DDH Inbound File montre chaque fichier reçu avec son statut :
| Statut | Signification |
|---|---|
| Fetched | Le fichier est relevé et attend son traitement. |
| Mapping Resolved | Une correspondance est choisie. |
| Processing | Les documents sont en cours de création. |
| Completed | Le traitement est terminé. |
| Failed | Le traitement a échoué. Le motif est dans Error Message. |
| Skipped | Aucune correspondance active ne reconnaît le nom du fichier au moment du traitement. |
Sur un fichier Failed, corrigez la correspondance, puis cliquez sur Retry. Le bouton Download raw file télécharge le fichier d'origine.
Pour traiter un fichier reçu par un autre moyen, cliquez sur Upload a document dans la liste, puis choisissez la connexion.
Erreurs fréquentes
| Message | Solution |
|---|---|
Target DocType {X} must have a field named 'ddh_inbound_file' | Ajoutez le champ lien ddh_inbound_file au type de document cible. |
Match Field is required when Duplicate Handling is set to '{X}' | Renseignez Match Field, ou choisissez Create new. |
Bulk Insert is not compatible with 'Update existing' duplicate handling. | Décochez Bulk Insert (bypass ORM), ou changez la gestion des doublons. |
Connection {X} received an archive but has no S3 Storage configured. | Renseignez Cloud Storage sur la connexion. |
Required field '{X}' has no value in source record. | Complétez le fichier, ou décochez Required sur la ligne. |
Conservation des fichiers
Cochez Auto-delete Archived Files sur la connexion pour supprimer les fichiers du dossier d'archive après Delete After (days) jours (30 par défaut). Le nettoyage a lieu une fois par jour.
Envoyer des exports planifiés
Une DDH Export produit un fichier à partir d'un rapport (Report) ou d'une requête Insights (Insights Query), puis le dépose sur une destination.
- Ouvrez DDH Export et créez un export.
- Dans l'onglet Source, choisissez le Source Type et la source. Run As User fixe les droits utilisés pour lire les données.
- Dans l'onglet File, choisissez le File Format : CSV, XLSX ou JSON. Renseignez le File Name Template.
- Dans l'onglet Destination, choisissez SFTP (avec une Connection et un Remote Directory) ou Cloud Storage (avec un Storage).
- Dans l'onglet Schedule, choisissez Manual, Interval ou Cron.
Skip If No Data n'envoie rien quand la source est vide. Chaque envoi crée une DDH Outbound File.