OTOBO

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 plugins personalizados como pacotes OPM para o OTOBO.

1. Estrutura de uma .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>MinhaExtensao</Name>
  <Version>1.0.0</Version>
  <Framework>10.0.x</Framework>   <!-- Versão mínima do OTOBO -->
  <Vendor>NomeDaSuaEmpresa Ltda</Vendor>
  <URL>https://github.com/seu-usuario/otobo-meu-pacote</URL>
  <License>GPL-3.0</License>
  <Description Lang="pt">Extensão para funções personalizadas</Description>
  <ChangeLog Version="1.0.0" Date="13.06.2025 12:00:00">Lançamento inicial</ChangeLog>
  <Filelist>
    <File Location="Kernel/Config/Files/XML/MinhaExtensao.xml" Permission="644"></File>
    <File Location="Kernel/System/MinhaExtensao.pm"            Permission="644"></File>
    <File Location="Kernel/Modules/AgentMinhaPagina.pm"           Permission="644"></File>
    <File Location="Kernel/Output/HTML/Standard/AgentMinhaPagina.tt" Permission="644"></File>
    <File Location="Kernel/Language/pt_MinhaExtensao.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 ​

Coloque seu pacote em um diretório próprio, por exemplo, MinhaExtensao/:

MinhaExtensao/
├─ MinhaExtensao.sopm
├─ Kernel/
│  ├─ Config/Files/XML/MinhaExtensao.xml
│  ├─ System/MinhaExtensao.pm
│  ├─ Modules/AgentMinhaPagina.pm
│  ├─ Output/HTML/Standard/AgentMinhaPagina.tt
│  └─ Language/pt_MinhaExtensao.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 & Idioma: Arquivos TT + arquivos de tradução .pm.

3. Construir e Instalar o Pacote ​

3.1 Criar OPM ​

Use a ferramenta CLI para criar um OPM a partir da sua SOPM:

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

3.2 Instalação ​

Interface de Admin: Faça o upload do pacote em Admin → Configurações → Gerenciamento de Pacotes. Console:

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

Para desinstalar ou atualizar:

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

4. Pontos de Extensão ​

4.1 Campos Dinâmicos ​

No Kernel/Config/Files/XML/MinhaExtensao.xml, registre um novo driver de campo dinâmico:

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

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

4.2 Manipulador de Eventos ​

Registre seu manipulador de eventos:

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

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

4.3 Filtro de Saída ​

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

Implemente o filtro em Kernel/System/Output/Filter/MeuFiltro.pm.

5. Implantação e OTOpar ​

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

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

  • Adicione a URL do repositório em Package::RepositoryList no SysConfig.

  • 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. SOPM crie com o nome MyCalendar.
  2. Script de banco de dados sql/create_calendar.sql para a tabela calendar_events.
  3. XML de configuração define um novo campo de ticket "Data".
  4. Módulo principal Kernel/System/CalendarEvent.pm com métodos CRUD.
  5. Módulos de frontend Kernel/Modules/AgentCalendar.pm, template AgentCalendar.tt.
  6. Construa o pacote e faça o upload para o OTOpar.

7. Dicas e Práticas Recomendadas ​

  • Número de versão no sopm atualizado (SemVer).
  • Migrações de banco de dados em sql/ versionadas corretamente.
  • 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 manter plugins personalizados do OTOBO em projetos de clientes. Divirta-se!