OTOBO / Znuny Guide

Português

English
Deutsch
Français
Español
Italiano
Polski
Nederlands

Português

English
Deutsch
Français
Español
Italiano
Polski
Nederlands

Desenvolvimento de Plugins com Pacotes OPM ​

Nesta seção, você aprenderá como criar, instalar e distribuir seus próprios plugins como pacotes OPM para OTOBO.

1. Estrutura de um .sopm ​

O arquivo SOPM (*.sopm) contém todos os metadados do seu pacote:

xml
<?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>   <!-- Versão mínima do OTOBO -->
  <Vendor>SuaEmpresa Ltda</Vendor>
  <URL>https://github.com/seu-usuario/otobo-meupacote</URL>
  <License>GPL-3.0</License>
  <Description Lang="pt">Extensão para funcionalidades especiais</Description>
  <ChangeLog Version="1.0.0" Date="13.06.2025 12:00:00">Primeira publicação</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/pt_MyExtension.pm"       Permission="644"></File>
  </Filelist>
</otobo_package>
  • Name/Version/Framework: Identificação única do pacote e versão compatível do OTOBO.
  • Filelist: Todos os arquivos que serão copiados durante a instalação.

2. Arquivos e Estrutura de Diretórios ​

Crie seu pacote em um diretório próprio, por exemplo, MyExtension/:

MyExtension/
├─ MyExtension.sopm
├─ Kernel/
│  ├─ Config/Files/XML/MyExtension.xml
│  ├─ System/MyExtension.pm
│  ├─ Modules/AgentMyPage.pm
│  ├─ Output/HTML/Standard/AgentMyPage.tt
│  └─ Language/pt_MyExtension.pm
└─ sql/
   └─ create_tables.sql      # opcional, para migrações de banco de dados
  • Kernel/Config/Files/XML/: Registra módulos, menus ou campos dinâmicos.
  • Kernel/System/: Classe de lógica de negócios.
  • Kernel/Modules/: Controlador de frontend.
  • Templates e Idioma: Arquivos TT + arquivo .pm de tradução.

3. Construir e Instalar o Pacote ​

3.1 Gerar OPM ​

Use a ferramenta CLI para construir um OPM a partir do seu SOPM:

bash
cd /caminho/para/MyExtension
bin/otobo.Console.pl Dev::Package::Build \
  --sopm-file MyExtension.sopm \
  --output /tmp/MyExtension.opm

3.2 Instalação ​

Interface de Administração: Carregue o pacote em Admin → Configurações → Gerenciamento de Pacotes. Console:

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

Para desinstalar ou atualizar:

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

4. Pontos de Extensão ​

4.1 Campos Dinâmicos ​

Em Kernel/Config/Files/XML/MyExtension.xml, registre um novo Driver de Campo Dinâmico:

xml
<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>

Implemente o driver em Kernel/System/DynamicField/Driver/MyCustomField.pm.

4.2 Manipuladores de Eventos ​

Registre seu manipulador de eventos:

xml
<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>

Implemente o manipulador em Kernel/System/Event/Handler/MyHandler.pm (método Run()).

4.3 Filtros de Saída ​

xml
<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 em Kernel/System/Output/Filter/MyFilter.pm.

5. Implantação e OTOpar ​

  • Índice de Repositório: Crie Packages.xml para seu próprio repositório:

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

  • Em SysConfig, adicione a URL do seu repositório em Package::RepositoryList.

  • OTOpar: Faça o upload do seu OPM em https://otopar.perl-services.de para que outros possam instalá-lo diretamente.

6. Exemplo: Pacote MyCalendar ​

  1. Crie o SOPM com o nome MyCalendar.
  2. Script de DB sql/create_calendar.sql para a tabela calendar_events.
  3. XML de Configuração define um novo campo de ticket "Agendamento".
  4. Módulo Core Kernel/System/CalendarEvent.pm com métodos CRUD.
  5. Módulos Frontend Kernel/Modules/AgentCalendar.pm, template AgentCalendar.tt.
  6. Construa o pacote e faça o upload para o OTOpar.

7. Dicas e Melhores Práticas ​

  • Ajuste o número da versão no sopm (SemVer).
  • Versionamento limpo de migrações de DB em sql/.
  • Crie testes unitários para classes de sistema e módulos.
  • Documentação no README e POD nos módulos Perl.
  • Traduções em Language/pt_*.pm e en_*.pm.

Com isso, você terá uma base sólida para desenvolver, distribuir e implantar seus próprios plugins OTOBO de forma sustentável em projetos de clientes. Divirta-se!