Modèles & champs

Un espace MADATA est un ensemble de modèles. Chaque écran de l’interface en affiche un ou plusieurs. Savoir lire cette carte, c’est savoir écrire n’importe quel appel : le reste n’est que search_read et write.

01Modèle, champ, enregistrement

Modèle: Une table métier, nommée en points : res.partner (contacts), sale.order (commandes de vente), account.move (pièces comptables).
Champ: Une colonne : name, email, amount_total. Le nom technique est stable ; le libellé affiché dépend de la langue.
Enregistrement: Une ligne, identifiée par un id entier, unique par modèle et par espace.

Trouver le modèle depuis l’écran

Dans l’espace, activez le mode développeur depuis Paramètres, puis survolez un champ : une infobulle donne le nom du modèle et celui du champ. C’est le chemin le plus rapide, et le plus sûr.

02Les modèles les plus utilisés

Domaine	Modèle	Contenu
Contacts	`res.partner`	Clients, fournisseurs, contacts. `customer_rank > 0` pour les clients, `supplier_rank > 0` pour les fournisseurs.
Contacts	`res.company`	Les sociétés de l’espace. En lecture.
Catalogue	`product.template`	La fiche article telle qu’on la saisit.
Catalogue	`product.product`	La variante réellement vendue et stockée. C’est elle que visent les lignes de document.
Ventes	`sale.order` · `sale.order.line`	Devis et commandes, et leurs lignes.
Ventes	`account.move` · `account.move.line`	Factures clients, factures fournisseurs, avoirs et écritures. Un seul modèle pour tout, distingué par `move_type`.
Achats	`purchase.order` · `purchase.order.line`	Demandes de prix et commandes d’achat.
Stock	`stock.quant`	Les quantités réellement en place, par emplacement.
Stock	`stock.picking` · `stock.move`	Réceptions, livraisons, transferts internes.
Comptabilité	`account.account` · `account.journal`	Plan de comptes et journaux.
Comptabilité	`account.payment`	Règlements clients et fournisseurs.
Caisse	`pos.order` · `pos.session`	Tickets et sessions du point de vente.
Ressources humaines	`hr.employee` · `hr.contract`	Employés et contrats.
Projets	`project.project` · `project.task`	Projets et tâches.
Relation client	`crm.lead`	Pistes et opportunités.

La liste dépend des applications installées sur l’espace : un espace sans point de vente n’a pas pos.order. Pour savoir ce qui existe réellement, demandez-le à l’espace lui-même.

03Découvrir sans deviner

Deux méthodes suffisent à explorer un espace inconnu.

pythonlister les modeles disponibles

modeles = models.execute_kw(DB, uid, CLE, 'ir.model', 'search_read',
    [[['model', 'like', 'sale.']]],
    {'fields': ['model', 'name'], 'order': 'model'})

for m in modeles:
    print(m['model'], '\t', m['name'])

pythonlister les champs d’un modele

champs = models.execute_kw(DB, uid, CLE, 'sale.order', 'fields_get', [],
    {'attributes': ['string', 'type', 'required', 'readonly', 'relation',
                    'selection', 'help']})

print(champs['state'])
# {'type': 'selection', 'string': 'Statut', 'required': True,
#  'selection': [['draft', 'Devis'], ['sent', 'Devis envoye'],
#                ['sale', 'Bon de commande'], ['cancel', 'Annule']], ...}

fields_get est la source de vérité : elle décrit l’espace tel qu’il est installé, avec ses champs personnalisés et ses listes de valeurs réelles. Une documentation générale ne peut pas faire mieux.

À garder sous la main

Appelée sans argument, fields_get renvoie tout le modèle, ce qui est volumineux. Passez attributes pour ne demander que ce qui vous intéresse, et gardez le résultat en cache le temps de votre exécution.

04Identifiants externes

Un id numérique n’a de sens que dans un espace donné. Pour désigner un enregistrement de façon stable, notamment depuis un système tiers, il existe les identifiants externes : un couple module.nom stocké dans ir.model.data.

pythonretrouver un enregistrement par identifiant externe

ref = models.execute_kw(DB, uid, CLE, 'ir.model.data', 'search_read',
    [[['module', '=', 'ma_boutique'], ['name', '=', 'client_4271']]],
    {'fields': ['res_id', 'model'], 'limit': 1})

partner_id = ref[0]['res_id'] if ref else None

C’est le moyen le plus fiable de rendre un import rejouable : au lieu de recréer un contact à chaque passage, vous cherchez son identifiant externe et vous mettez à jour l’existant. Sans cela, une reprise après incident double vos données.

05Multi-société

Un espace peut porter plusieurs sociétés. Chaque enregistrement concerné a un company_id, et chaque appel s’exécute dans le périmètre des sociétés actives pour l’utilisateur.

pythonlire dans une societe precise

factures = models.execute_kw(DB, uid, CLE, 'account.move', 'search_read',
    [[['move_type', '=', 'out_invoice'], ['state', '=', 'posted']]],
    {'fields': ['name', 'partner_id', 'amount_total'],
     'context': {'allowed_company_ids': [2]}})

Le piège des sociétés

Sans allowed_company_ids, l’appel utilise les sociétés par défaut de l’utilisateur. Un total « faux » est presque toujours un total pris sur un périmètre différent de celui qu’on regardait à l’écran. Précisez-le dès que l’espace a plus d’une société : c’est une ligne, et elle évite des heures de rapprochement.

06Ce qui appartient au portail

Utilisateurs, sociétés, applications installées et abonnement sont gérés dans le portail MADATA, qui en est la source de vérité et qui facture en conséquence. Les créer ou les modifier directement par l’API désaligne l’espace et votre abonnement. Lisez-les si vous en avez besoin ; écrivez-les depuis le portail.