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.

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

      
flowchart LR
    S[Serveur SFTP
    

• Une DDH Connection décrit un serveur SFTP, le dossier à relever et la fréquence de relève.
• Chaque fichier relevé crée une DDH Inbound File. Un fichier déjà reçu, avec le même contenu, n'est pas repris.
• Une DDH Mapping décrit un format de fichier et le type de document à créer. Pour chaque fichier, Data Hub choisit la première correspondance active de la connexion dont le motif de nom de fichier correspond. Sans correspondance, le fichier passe au statut Skipped.

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

1. Ouvrez l'espace Dokos Data Hub, puis DDH Connection, et créez une connexion.
2. Saisissez un Title, par exemple Transporteur.
3. Dans l'onglet Connection, renseignez Host, Port (22 par défaut) et Username.
4. Choisissez l'Authentication Method : Password, SSH Key ou SSH Certificate. Renseignez le secret correspondant.
5. Dans l'onglet Paths, renseignez le Remote Path, le dossier à relever, par exemple /depot/livraisons.
6. Renseignez Archive Path pour y déplacer les fichiers traités, et Error Path pour les fichiers en échec. Ces deux champs sont facultatifs.
7. Dans l'onglet Schedule & Retention, renseignez File Pattern pour ne relever que certains fichiers, par exemple LIVRAISONS_*.csv.
8. 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.
9. 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

1. Ouvrez DDH Mapping et créez une correspondance.
2. Saisissez un Title et choisissez la Connection Transporteur.
3. Dans l'onglet File Identification, choisissez le File Format CSV.
4. Renseignez File Name Pattern (regex) : ^LIVRAISONS_.*\.csv$. Ce motif est une expression régulière. Laissez-le vide pour accepter tous les fichiers de la connexion.
5. Réglez File Encoding, CSV Delimiter et CSV Has Header selon le fichier.
6. Dans l'onglet Target, choisissez la Target DocType « Suivi colis ».
7. 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.
8. Dans l'onglet Field Mappings, ajoutez une ligne par champ : la colonne source dans Source Path, le champ cible dans Target Field.
9. Pour traduire le code statut, ajoutez une ligne dans Code List Mappings. Elle utilise une liste de codes.
10. Enregistrez.

Au passage suivant, chaque ligne du fichier crée une fiche « Suivi colis ».

Référence des correspondances

Formats de fichier

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

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 :

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

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.