Développement de plugins avec des paquets OPM

Développement de plugins avec des paquets OPM

Dans cette section, vous apprendrez à créer, installer et distribuer vos propres plugins sous forme de paquets OPM pour OTOBO.

---

1. Structure d’un .sopm

Le fichier SOPM (*.sopm) contient toutes les métadonnées de votre paquet :

<?xml version="1.0" encoding="utf-8"?>
<otobo_package version="1.0">
  <Name>MyExtension</Name>
  <Version>1.0.0</Version>
  <Framework>10.0.x</Framework>   <!-- Version minimale d'OTOBO -->
  <Vendor>DeinName GmbH</Vendor>
  <URL>https://github.com/dein-user/otobo-mypackage</URL>
  <License>GPL-3.0</License>
  <Description Lang="de">Extension pour des fonctions spéciales</Description>
  <ChangeLog Version="1.0.0" Date="13.06.2025 12:00:00">Première publication</ChangeLog>
  <Filelist>
    <File Location="Kernel/Config/Files/XML/MyExtension.xml" Permission="644"></File>
    <File Location="Kernel/System/MyExtension.pm"            Permission="644"></File>
    <File Location="Kernel/Modules/AgentMyPage.pm"           Permission="644"></File>
    <File Location="Kernel/Output/HTML/Standard/AgentMyPage.tt" Permission="644"></File>
    <File Location="Kernel/Language/de_MyExtension.pm"       Permission="644"></File>
  </Filelist>
</otobo_package>

• Name/Version/Framework : Identifiant unique du paquet et version compatible d’OTOBO.
• Filelist : Tous les fichiers copiés lors de l’installation.

---

2. Fichiers & structure des répertoires

Créez votre paquet dans un répertoire dédié, par exemple MyExtension/ :

MyExtension/
├─ MyExtension.sopm
├─ Kernel/
│  ├─ Config/Files/XML/MyExtension.xml
│  ├─ System/MyExtension.pm
│  ├─ Modules/AgentMyPage.pm
│  ├─ Output/HTML/Standard/AgentMyPage.tt
│  └─ Language/de_MyExtension.pm
└─ sql/
   └─ create_tables.sql      # optionnel, pour les migrations de base de données

• Kernel/Config/Files/XML/ : Enregistre les modules, menus ou Dynamic Fields.
• Kernel/System/ : Classe de logique métier.
• Kernel/Modules/ : Contrôleur Frontend.
• Templates & Langue : Fichiers TT + .pm de traduction.

---

3. Construire & installer le paquet

3.1 Générer l’OPM

Utilisez l’outil CLI pour construire un OPM à partir de votre SOPM :

cd /chemin/vers/MyExtension
bin/otobo.Console.pl Dev::Package::Build \
  --sopm-file MyExtension.sopm \
  --output /tmp/MyExtension.opm

3.2 Installation

Admin-UI : Téléchargez le paquet via Admin → Paramètres → Gestionnaire de paquets. Console :

bin/otobo.Console.pl Admin::Package::Install /tmp/MyExtension.opm

Pour désinstaller ou mettre à jour :

bin/otobo.Console.pl Admin::Package::Uninstall /tmp/MyExtension.opm
bin/otobo.Console.pl Admin::Package::Upgrade   /tmp/MyExtension.opm

---

4. Points d’extension

4.1 Dynamic Fields

Dans Kernel/Config/Files/XML/MyExtension.xml, vous enregistrez un nouveau pilote de Dynamic Field :

<Setting Name="DynamicFields::Driver###MyCustomField" Required="0" Valid="1">
  <Navigation>DynamicFields::Driver</Navigation>
  <Value>
    <Array>
      <Item><Hash>
        <Item Key="DriverName">MyCustomField</Item>
        <Item Key="Module">Kernel::System::DynamicField::Driver::MyCustomField</Item>
      </Hash></Item>
    </Array>
  </Value>
</Setting>

Implémentez le pilote dans Kernel/System/DynamicField/Driver/MyCustomField.pm.

4.2 Event-Handler

Enregistrez votre Event-Handler :

<Setting Name="Event::EventHandler###MyHandler" Required="0" Valid="1">
  <Navigation>Event::EventHandler</Navigation>
  <Value>
    <Array>
      <Item><Hash>
        <Item Key="Module">Kernel::System::Event::Handler::MyHandler</Item>
      </Hash></Item>
    </Array>
  </Value>
</Setting>

Implémentez le gestionnaire dans Kernel/System/Event/Handler/MyHandler.pm (méthode Run()).

4.3 Output-Filter

<Setting Name="Output::Filter###MyFilter" Required="0" Valid="1">
  <Navigation>Output::Filter</Navigation>
  <Value>
    <Array>
      <Item><Hash>
        <Item Key="Module">Kernel::System::Output::Filter::MyFilter</Item>
      </Hash></Item>
    </Array>
  </Value>
</Setting>

Filtre dans Kernel/System/Output/Filter/MyFilter.pm.

---

5. Déploiement & OTOpar

• Index du dépôt : Générez Packages.xml pour votre propre dépôt :

  bin/otobo.Console.pl Dev::Package::RepositoryIndex \
    --directory /var/www/otobo-packages

• Ajoutez l’URL de votre dépôt dans SysConfig sous Package::RepositoryList.

• OTOpar : Téléchargez votre OPM sur https://otopar.perl-services.de afin que d’autres puissent l’installer directement.

---

6. Exemple : Paquet MyCalendar

1. Créer le SOPM avec le nom MyCalendar.
2. Script DB sql/create_calendar.sql pour la table calendar_events.
3. XML de configuration définissant un nouveau champ de ticket « Rendez-vous ».
4. Module Core Kernel/System/CalendarEvent.pm avec des méthodes CRUD.
5. Modules Frontend Kernel/Modules/AgentCalendar.pm, template AgentCalendar.tt.
6. Construire le paquet et le télécharger sur OTOpar.

---

7. Conseils & bonnes pratiques

• Adapter le numéro de version dans le sopm (SemVer).
• Versionner proprement les migrations DB dans sql/.
• Créer des tests unitaires pour les classes système et les modules.
• Documentation dans le README plus POD dans les modules Perl.
• Traductions dans Language/de_*.pm et en_*.pm.

Vous disposez désormais d’une base solide pour développer, distribuer et maintenir vos propres plugins OTOBO dans des projets clients. Amusez-vous bien !