myfab File Interface
Module permettant l'export ou l'import de données d'Open-Prod.
Documentation utilisateurs
Documentation technique et fonctionnelle balayant l'ensemble du module, de son installation à son utilisation en passant par son paramétrage et sa maintenance.
Présentation
1. Objectif
Afin d’échanger des données avec Open-Prod, les applications tierces ont besoin d’une interface du côté de l’ERP permettant ces communications.
Le module mFI permet de procéder à ces échanges de fichiers à plat, qui peuvent être exportés depuis l’ERP puis consommés par les applications tierces, ou bien générés par les applications tierces puis importés dans l’ERP. Ces fichiers sont déposés dans un dossier partagé entre l’ERP et les applications tierces.
2. Format d'échange
Plusieurs formats de fichiers d’échanges existent (ex : XML, XLSX, etc.). Le format JSON est conseillé car :
- Léger visuellement (contrairement au XML et ses balises par exemple).
- Simple à comprendre.
- Illustre aisément une arborescence de données (contrairement au CSV par exemple).
Le module supporte toutefois d’autres formats courants : le CSV et le TXT (un CSV avec comme séparateur une tabulation).
Voici un schéma décrivant comment est construit un fichier en format JSON :
Installation
1. Installation des modules myfab
Avant d'installer myfab FileInterface ou tout autre module myfab, il convient de s'assurer que les sources ont été déployées sur le serveur.
L'installation du module s'effectue depuis l'onglet Configuration > Application d'Open-Prod. Dans la barre de recherche, taper "myfab". Le module myfab File Interface, ou mFI sera présent. Cliquer sur "Installer". A savoir que l'installation du module myfab Base inclut également l'installation de myfab File Interface.
2. Configuration des droits
Une fois l'installation terminée, il faut donner les droits à l'utilisateur / aux utilisateurs concerné(s). Pour cela, aller dans Configuration > Utilisateurs. Choisir les utilisateurs et cocher les cases surlignées ci-dessous. Terminer en sauvegardant les modifications, puis actualiser la page.
Mise à jour
La maintenance et les mises à jour des modules myfab se déroulent principalement depuis votre serveur via un terminal.
La commande app-manager permet de mettre à jour les modules myfab dans leur ensemble. Se référer à la section dédiée pour plus de détails quant à son utilisation.
MAJ depuis interface OPP
Paramétrage
Une fois le module mFI installé, l'interface de paramétrage est accessible depuis Configuration > APIs myfab (tout en bas de la liste déroulante sur la gauche de l'écran.
Paramétrage Exports fichiers
1. Configuration générale Export
La première étape consiste à créer un nouvel Export. Pour cela cliquer sur le bouton "Créer".
À l’arrivée sur la vue formulaire de l’export, on distingue de haut en bas deux parties distinctes :
- La zone de configuration, qui contient les champs permettant d’indiquer quels enregistrements on souhaite exporter, dans quel dossier, sous quel format, etc.
- La zone de monitoring, qui permet d’avoir une visualisation des fichiers présents dans le dossier d’export (une fois celui-ci configuré), ainsi qu’un historique des exports réalisés.
On peut désormais saisir un nom pour l'Export.
Puis, créer le répertoire dans lequel les exports vont se déverser. Ce répertoire correspond à un dossier physique sur la machine virtuelle Open-Prod. S’il n’existe pas, il sera créé.
2. Configuration fichier d'export
Dans l'onglet "Fichier" on peut paramétrer :
- Le format d’export (entre JSON, CSV et TXT).
- Le caractère de séparation (uniquement en CSV).
- Le caractère de quoting (uniquement en CSV et TXT).
- Une extension personnalisée (ex : si on échange des fichiers avec un MES, celui-ci attend du CSV avec pour extension .xcsv, il faut donc configurer une extension personnalisée xcsv).
- La génération physique des fichiers ou non (pour tester sans générer de fichiers sur le serveur).
Ne pas oublier d'activer la génération physique des fichiers si l'on souhaite aller au delà des tests.
3. Configuration du modèle à exporter
De retour dans la configuration principale, ajouter un modèle à exporter. Choisir le modèle désiré (dans notre exemple, "res.partner", puis comme indiqué, cliquer sur "Sauvegarder & fermer", puis sauvegarder le formulaire en entier avant d’aller plus loin.
4. Configuration des champs du modèle à exporter
Retourner en modification de l'export, puis cliquer sur le modèle à exporter. Le formulaire ci-dessous s'affiche. Il permet de modifier le modèle et les champs du modèle ainsi que les modèles enfants (cf paramétrage avancé). Cliquer sur le bouton "Ajouter un élément" pour ajouter un champ à exporter.
Un nouveau formulaire s'affiche. Il liste tous les champs du modèle choisi. Sélectionner le ou les champ(s) à exporter puis cliquer sur le bouton "Sélectionner". Sauvegarder à nouveau l'entièreté de l'export pour valider les modifications.
A ce stade le module est prêt pour réaliser des exports de données.
5. Paramétrage de l'exécution automatique des exports
Se référer au paramétrage avancé.
6. Options de filtrage
6.1. Filtrage des enregistrements à exporter
Une fois les modèles et champs à exporter sélectionnés, il est possible d'appliquer des filtres qui s'appliqueront lors de l'export. Pour cela, retourner en modification sur le modèle à exporter puis cliquer sur l'onglet "Filtrage".
Deux solutions de filtrage sont possibles :
-
- Affecter une limite de nombre d’enregistrements à exporter (exemple : je ne veux exporter que dix éléments).
- Affecter un filtre spécifique sur un champ du modèle (exemple : je ne veux exporter que les enregistrements qui ont pour nom "Toto").
6.2. Filtrage sur champ
Pour ajouter un filtre sur un champ du modèle, cliquer sur "Ajouter un élément".
Cliquer sur "Chercher plus" dans la liste déroulante pour afficher la liste des champs. Dans le formulaire "Champ à filtrer", sélectionner le ou les champs qui vont servir à appliquer un filtre.
6.3. Opérateurs de comparaison
Quand le champ à filtrer est sélectionné, choisir parmi la liste déroulante l'opérateur de comparaison et noter la valeur de comparaison. Dans l'exemple qui suit, le filtre permettra de ne sélectionner que les partenaires ayant pour nom "toto", sans tenir compte de la casse (c'est à dire qu'il ne tient pas compte de la majuscule). Attention à bien sauvegarder l'entièreté des formulaires avant de poursuivre.
Voir ci-dessous une description des opérateurs de comparaison disponibles.
| Opérateur de comparaison | Usage | Description |
|---|---|---|
| like | [('input', 'like', 'open')] | Renvoie les résultats contenant le texte recherché - sensible à la casse (caractères génériques - '%open%'). Ex : open, opensource, openerp, Odooopenerp |
| not like | [('input', 'not like', 'open')] | Renvoie les résultats ne contenant pas le texte recherché - sensible à la casse (caractères génériques - '%open%'). Ex : Openerp, Opensource, Open, Odoo, odoo, OdooOpenerp |
| =like | [('name', '=like', 'open')] | Renvoie les résultats contenant exactement le texte recherché (='open') - sensible à la casse Ex : open |
| ilike | [('name', 'ilike', 'open')] | Renvoie les résultats contenant le texte recherché - insensible à la casse (caractères génériques - '%open%'). Ex : Openerp, openerp, Opensource, opensource, Open, open, Odooopenerp, OdooOpenerp |
| not ilike | [('name', 'not ilike', 'open')] | Renvoie les résultats ne contenant pas le texte recherché - insensible à la casse (caractères génériques - '%open%'). Ex : Odoo, odoo |
| =ilike | [('name', '=ilike', 'open')] | Renvoie les résultats contenant exactement le texte recherché (='open') - insensible à la casse Ex : Open, open |
| in | [('value1', 'in', ['value1', 'value2'])] | L'opérateur "in" vérifiera que la valeur1 est présente ou non dans la liste des termes de droite |
| not in | [('value1', 'not in', ['value2'])] | L'opérateur "not in" vérifiera que la valeur1 est absente dans la liste des termes de droite |
| = | [('input', '=', 'open')] | Renvoie les résultats contenant exactement la valeur recherchée (='open') - sensible à la casse Ex : open |
| != | [('input', '!=', 'open')] | Renvoie les résultats qui ne correspondent pas à l'entrée donnée (autre que - 'open'). Ex : tous les autres enregistrements que 'open' |
| > | [('input', '>', '10')] | Renvoie tous les résultats plus grands que la valeur entrée (toutes les valeurs plus grandes que la valeur - '10'). Ex : 11, 12, 13... |
| >= | [('input', '>=', '10')] | Renvoie tous les résultats plus grands ou égaux que la valeur entrée. Ex : 10, 11, 12, 13 |
| < | [('input', '<', '10')] | Renvoie tous les résultats plus petits que la valeur entrée (toutes les valeurs plus petites que la valeur - '10'). Ex : 9, 8, 7… |
| <= | [('input', '<=', '10')] | Renvoie tous les résultats plus petits ou égaux que la valeur entrée Ex : 10, 9, 8, 7… |
Paramétrage Imports Fichiers
1. Configuration générale Import
La première étape consiste à créer un nouvel Import. Pour cela cliquer sur le bouton "Créer".
Comme pour l'export, on peut voir les deux parties "Configuration" et "Monitoring".
- Saisir un nom pour l'Import.
- Puis, sélectionner ou créer le répertoire dans lequel seront déposés les fichiers à importer. Ce répertoire correspond à un dossier physique sur la machine virtuelle Open-Prod. S’il n’existe pas, il sera créé.
2. Configuration fichier d'export
Dans l'onglet "Fichier" on peut paramétrer :
- Le format ou l'extension du fichier d’import (entre JSON, CSV et TXT).
- Le type d'encodage entre UTF-8 ou CP1252.
Une application tierce ou un utilisateur peuvent désormais déposer sur ce répertoire des fichiers à importer dans Open-Prod. Les imports seront réalisés en cliquant sur le bouton "Lancer" ou par l'exécution automatique via un cron.
3. Paramétrage de l'exécution automatique des imports
Se référer au paramétrage avancé.
Paramétrages avancés
1. Configuration d'un champ relationnel
Il existe trois types de champs relationnels dans Open-Prod :
- many2one : mon modèle est lié par ce champ à un seul enregistrement d’un autre modèle, et cet autre modèle contient un champ one2many qui traduit la relation inverse.
Ex : un contact est lié à un seul pays, et dans le sens inverse un pays peut être lié à une multitude de contacts.
- one2many : mon modèle est lié par ce champ à une multitude d’enregistrements d’un autre modèle, et cet autre modèle contient un champ one2many qui traduit la relation inverse.
Ex : un produit peut être lié à une multitude de lignes de commande de vente, et dans le sens inverse une ligne de commande de vente n’est liée qu’à un seul produit.
- many2many : mon modèle est lié par ce champ à une multitude d’enregistrements d’un autre modèle, et cet autre modèle contient un champ many2many qui traduit la relation réciproque.
Ex : un partenaire peut être lié à une multitude de catégories, et réciproquement une catégorie peut être liée à une multitude de partenaires.
2. Configuration de l’export d’un champ relationnel
Concrètement, cela veut dire qu'il est possible de paramétrer l'export de champs d'un modèle relié au modèle initialement paramétré pour l'export.
Pour cela, revenir sur la s"lection des champs de partenaire à exporter et sélectionner un champ relationnel. Dans l'exemple ci-dessous, il s'agit du champ country-id qui est un champ "many2one". Valider la sélection puis enregistrer l'entièreté du formulaire.
Pour poursuivre dans cet exemple, si l'on revient sur le formulaire de configuration d’export du modèle Partenaire, on voit que le modèle Pays a été ajouté automatiquement à la liste des configurations des modèles enfants.
Ce modèle enfant est paramétrable au même titre que le modèle parent, et l'on peut donc sélectionner des champs de ce modèle à exporter.
En cliquant sur le modèle Pays en modification, on retrouve la même interface de configuration que pour le modèle parent, mais cette fois pour le modèle enfant. Cette structure est récursive : ainsi, il est possible d'exporter des champs relationnels de champs relationnels de champs relationnels… et ce à l’infini.
3. Modifications de champs à l'export
Lors d'un export, il est possible de paramétrer des exécutions de modifications. On peut par exemple modifier certains champs ou bien déclencher une méthode particulière.
Retourner en modification de l'export et du modèle à exporter. Aller dans l'onglet Setters. Pour ajouter un champ à modifier, cliquer sur Ajouter un élément. Dans le formulaire qui s'ouvre, sélectionner le ou les champ(s) à modifier puis valider la sélection.
Dans l'exemple ci-dessous, le champ Notes de chacun des enregistrements exportés se verra attribuer la valeur "Nouvelle note".
Il est également possible d'appeler une méthode Python particulière. Cela requiert des compétences en développement, il est donc préférable de se rapprocher de votre chargé de clientèle ou du service R&D de 1Life pour des demandes de ce type.
4. Exécution automatique d'un export ou d'un import
Pour pouvoir exécuter automatiquement un export, il faut utiliser le système de Cron (action planifiée) d’Open-Prod. Le bouton "Générer le cron pour cet export", surligné ci-dessous, simplifie cette création de Cron. Cliquer dessus pour créer un nouveau Cron.
Dans la fenêtre qui s'affiche, paramétrer la fréquence d'exécution de l'export puis cliquer sur "Ok". Dans l'exemple ci-dessous, le Cron va s'exécuter toutes les 5 minutes à partir du 31/08/2022 à 12h00.
Une action planifiée pour exécuter cet export est ainsi créée. Elle peut être modifiée depuis le menu « Action planifiées » d’Open-Prod. Il est également possible de la supprimer à tout moment en utilisant le bouton "Supprimer le cron pour cet export" (qui a remplacé le bouton de création utilisé plus tôt).
Les exports exécutés par l'action planifiée sont visibles dans l'onglet Historique de la section Monitoring, tout comme ceux exécutés manuellement.
Utilisation du module
1. Exécution manuelle d'un export ou d'un import
Détails
1.1. Lancement export
Pour exécuter l'export d'un modèle d'export, cliquer sur le bouton "Lancer". Le systême va extraire les données et déposer sur le répertoire de dépôt un nouveau fichier contenant ces données.
1.2. Lancement import
Pour exécuter l'import des fichiers présents sur le répertoire de dépôt, cliquer sur le bouton "Lancer". Le systême va ainsi parcourir l'ensemble du répertoire de dépôt des fichiers d'import et tenter d'intégrer les données dans Open-Prod. Une fois le ou les fichiers parcourus, ils sont supprimés du répertoire lié. On peut ensuite retrouver les tentatives d'import dans l'onglet "Historique".
1.3. Exécution automatique d'un export ou d'un import
2. Exécution automatique d'un export ou d'un import
3. Surveillance et analyse des tentatives d'export et d'import
Détails
1. Répertoire lié
Il est possible de parcourir le répertoire lié en cliquant sur le bouton "Scanner le répertoire". Cela va permettre d'afficher tous les fichiers actuellement présent sur le dossier.
En cliquant sur une ligne, on peut voir les détails du fichier : nom, emplacement, date de dernière modification et une prévisualisation du contenu de ce fichier. Fichier qu'il est possible de télécharger ou supprimer à l'aide des boutons correspondants sur la droite. Les fichiers peuvent être supprimés en cliquant sur le bouton "Supprimer" au bout de chaque ligne.
2. Historique des tentatives
Chaque exécution d'un import ou d'un export va générer une entrée dans l'onglet Historique de la section Monitoring. On peut y voir le nom du fichier, la date de début et de fin de traitement et son statut : Succès ou Echec.
3. Détails des tentatives
Comme dans l'onglet répertoire, en cliquant sur chaque ligne, cela va ouvrir une fenêtre donnant plus de détails concernant la tentative.
Pour l'export et l'import, on voit diverses informations sur la tentative, ainsi qu’une archive du fichier qui a été importé. Un tableau illustre également les enregistrements qui ont été traités lors d'un import.
Dans l'exemple ci-dessus, plusieurs partenaires ont été créés et "committed". Cette notion de "commit" rejoint celle de l’import Excel d’Open-Prod : "committed" indique si le partenaire créé a bien été injecté en BDD. Si on crée plus de 1000 enregistrements, un commit s’effectuera par défaut tous les 1000 enregistrements créés, pour des raisons techniques.
4. Détails des fichiers
Dans la section Fichier :
- en cliquant sur le nom du fichier, cela va ouvrir la fenêtre de détails du fichier. On y trouve une prévisualisation des données s'y trouvant ainsi que la méthode appliquée.
- Pour les import de fichier, l'option "Réimporter le fichier" permet de rejouer l'import de ce fichier en créant une nouvelle tentative. Dans l'exemple ci-dessous on peut voir dans l'historique deux tentatives distinctes pour un même fichier.
Exemple de mise en oeuvre
Mise en oeuvre de l'échange de fichier entre Open-Prod et un MES (Manufacturing Execution System).
Format des échanges de données de fabrication
Le document suivant décrit le format attendu des données à transmettre à Open-Prod pour intégrer les données au travers du module mFI.