comi-odoo-ticketing/README.md

comi-odoo-ticketing

Script WAPT de surveillance des tickets Odoo Helpdesk Comitari.

Le projet interroge Odoo via JSON-RPC, compare la date de modification des tickets avec un etat local JSON, puis envoie un message Rocket.Chat via webhook quand des tickets ont change depuis la derniere verification.

Contenu du depot

Fichier	Role
setup.py	Script WAPT principal. Contient les fonctions install(), audit() et send_to_rocket().
WAPT/control	Metadata minimale du paquet WAPT.
ticketing.ini.example	Modele de configuration avec placeholders, copie dans le repertoire prive WAPT sous le nom ticketing.ini.
tests/test_ticketing.py	Tests unitaires de la logique de comparaison et de persistance d'etat.
.env	Variables d'environnement locales pour pointer vers l'installation Python/WAPT Windows.
TRAVAIL.md	Journal de travail maintenu par Codex.

Fonctionnement

1. install() copie ticketing.ini.example vers WAPT.private_dir/ticketing.ini si le fichier cible n'existe pas encore.
2. Le fichier copie doit etre renseigne sur la machine cible avec l'URL Odoo, la cle API et le webhook Rocket.Chat.
3. audit() appelle l'endpoint JSON-RPC Odoo configure dans ticketing.ini.
4. La methode Odoo appelee est helpdesk.ticket.search_read, avec les champs id et write_date.
5. Le script charge l'ancien etat depuis tickets_state.json.
6. Chaque ticket nouveau ou dont write_date a change est ajoute a la liste des tickets mis a jour.
7. Un message est envoye dans Rocket.Chat via le webhook configure dans le fichier INI prive.
8. Le nouvel etat est sauvegarde dans WAPT.private_dir/tickets_state.json.

Prerequis

• Environnement WAPT avec setuphelpers.
• Python compatible avec l'environnement WAPT cible.
• Acces reseau vers Odoo Comitari.
• Acces reseau vers Rocket.Chat Comitari.
• Dependances Python :
  • requests
  • modules standard : json, os, shutil, configparser

Configuration

La configuration sensible est centralisee dans la copie privee WAPT.private_dir/ticketing.ini. Le depot ne versionne que ticketing.ini.example, avec des placeholders :

[rocket]
webhook_url = CHANGE_ME_ROCKET_CHAT_WEBHOOK_URL

[odoo]
url = https://CHANGE_ME_ODOO_HOST
database = CHANGE_ME_ODOO_DATABASE
username = CHANGE_ME_ODOO_USERNAME
api_key = CHANGE_ME_ODOO_API_KEY
model = helpdesk.ticket
fields = id,name,stage_id,partner_id,user_id,write_date
limit = 0
order = id asc
track_chatter = true
chatter_model = mail.message

[http]
timeout = 30

[notification]
max_tickets = 50
max_message_chars = 3500
ticket_url_template = {odoo_url}/web#id={id}&model={model}&view_type=form

Au deploiement, install() copie ce modele vers WAPT.private_dir/ticketing.ini uniquement si le fichier n'existe pas deja. Il faut ensuite renseigner le fichier prive sur la machine cible. Les mises a jour du paquet n'ecrasent donc pas une configuration deja remplie.

Si une valeur obligatoire est absente ou conserve un placeholder CHANGE_ME..., l'audit echoue explicitement avec un message indiquant la cle a renseigner.

Important : ne pas renseigner de vrais secrets dans ticketing.ini.example. Le fichier local ticketing.ini est ignore par Git.

Execution

Dans un paquet WAPT, l'execution attendue passe par les hooks WAPT :

install()
audit()

Hors WAPT, le script ne peut pas etre lance tel quel sans fournir les objets et chemins attendus par setuphelpers, notamment WAPT.private_dir.

Etat local

tickets_state.json est stocke dans WAPT.private_dir et contient un dictionnaire JSON au format :

{
  "ticket_id": {
    "write_date": "date de modification du ticket",
    "last_chatter_update": "date et id du dernier message chatter"
  }
}

Le runtime lit et ecrit ce fichier dans WAPT.private_dir. Il n'est pas versionne dans le depot. Les anciens etats au format simple ticket_id -> write_date restent lisibles.

no_change_notification_state.json est aussi stocke dans WAPT.private_dir. Il garde la date de derniere notification "aucun changement" afin de ne l'envoyer qu'une fois par jour.

La cle API est utilisee comme mot de passe d'API Odoo pour authentifier username. Il est aussi possible de renseigner uid dans la section [odoo] pour eviter l'appel d'authentification.

odoo.fields controle les champs recuperes depuis Odoo pour enrichir la notification. Les champs id et write_date sont toujours ajoutes s'ils sont absents, car ils sont necessaires a la comparaison d'etat.

odoo.limit = 0 force la recuperation de tous les tickets. odoo.order = id asc stabilise la comparaison avec l'etat local.

odoo.track_chatter = true active le suivi des notes/commentaires Odoo en lisant le dernier mail.message rattache a chaque ticket. Cela permet de detecter une note ajoutee dans un ticket meme si helpdesk.ticket.write_date ne change pas.

notification.max_tickets limite le nombre de tickets affiches dans Rocket.Chat. notification.max_message_chars limite la taille totale du message pour eviter les rejets Rocket.Chat sur les gros audits. notification.ticket_url_template controle le lien d'ouverture du ticket ; les variables disponibles sont {odoo_url}, {id} et {model}.

Protocole Odoo

Le script utilise l'endpoint configure sous la forme <odoo.url>/jsonrpc avec le protocole JSON-RPC Odoo standard.

Authentification :

{
  "jsonrpc": "2.0",
  "method": "call",
  "params": {
    "service": "common",
    "method": "authenticate",
    "args": ["database", "username", "api_key", {}]
  },
  "id": 1
}

Lecture des tickets :

{
  "jsonrpc": "2.0",
  "method": "call",
  "params": {
    "service": "object",
    "method": "execute_kw",
    "args": ["database", "uid", "api_key", "helpdesk.ticket", "search_read", [[]], {"fields": ["id", "name", "stage_id", "partner_id", "user_id", "write_date"], "limit": 0, "order": "id asc"}]
  },
  "id": 1
}

Notification

Quand des tickets changent, Rocket.Chat recoit un message avec :

• une ligne compacte par ticket affiche, limitee par notification.max_tickets ;
• une taille totale limitee par notification.max_message_chars ;
• l'ID, le sujet, la personne assignee et un lien d'ouverture direct dans Odoo ;
• une ligne de resume si tous les tickets modifies ne sont pas affiches.

Exemple :

Les tickets suivants ont ete mis a jour depuis la derniere verification :
187 : Sujet : Probleme imprimante gere par Support : [cliquer ici pour ouvrir le ticket](https://odoo.example.test/web#id=187&model=helpdesk.ticket&view_type=form)
251 : Sujet : Nouveau ticket gere par Personne : [cliquer ici pour ouvrir le ticket](https://odoo.example.test/web#id=251&model=helpdesk.ticket&view_type=form)

Quand aucun ticket ne change, Rocket.Chat recoit au maximum une notification par jour :

Aucun ticket n'a ete mis a jour depuis la derniere verification.

Tests

Les tests unitaires peuvent etre executes hors WAPT :

python3 -m unittest discover -s tests

Points d'attention connus

• Les secrets doivent etre renseignes uniquement dans la copie privee WAPT.private_dir/ticketing.ini.
• Les secrets deja presents dans l'historique Git doivent etre regeneres cote Odoo et Rocket.Chat.

Prochaines ameliorations recommandees

1. Confirmer en environnement cible que l'utilisateur Odoo configure a bien acces au modele helpdesk.ticket.
2. Completer les metadonnees WAPT/control selon les conventions internes Comitari.
3. Ajouter un test d'integration manuel ou automatise sur une instance Odoo de recette.