OTOBO Znuny ACLs

Listas de Controle de Acesso (ACLs) em OTOBO são a base de uma gestão robusta de permissões. Neste subtópico, você aprenderá:

Conceitos e Valor de Negócio: Por que os ACLs são indispensáveis.
Visão Geral da Arquitetura: Como o subsistema de ACL é estruturado internamente.
Match vs. Action: Estrutura básica de um ACL.
Configurações do Sistema: Configurações importantes do SysConfig relacionadas a ACLs.

1. Conceitos e Valor de Negócio

ACLs definem quais ações agentes e clientes podem executar no sistema de tickets – de forma automatizada e sensível ao contexto.

Segurança: Proteja funções sensíveis (por exemplo, fechar ticket) contra uso não autorizado.
Usabilidade: Oculte dinamicamente botões ou menus irrelevantes para não sobrecarregar o usuário.
Automação: Controle fluxos de tickets (priorização, escalonamento, atribuição) diretamente através de regras de ACL, sem código adicional.
Manutenibilidade: Exporte, importe e versiona ACLs centralmente – ideal para ambientes multi-instância.

1.1 ACLs Baseados em Papéis e Critérios

Baseado em Papéis: Atribuição com base em papéis ou grupos de agentes (por exemplo, Admin vs. Agente de Suporte).
Baseado em Critérios: Controle por atributos de ticket (Fila, Status, Prioridade, Campos Dinâmicos, ID do Cliente).

A combinação de ambas as abordagens permite regras precisas, por exemplo: "Apenas agentes seniores movem tickets com prioridade > 3 para a fila de desenvolvimento."

2. Visão Geral da Arquitetura

O subsistema ACL do OTOBO está distribuído em vários componentes principais:

Componente	Tarefa
Kernel::System::ACL::DB::ACL	Backend Perl: Persiste e carrega ACLs do banco de dados
Kernel::System::YAML	Serializa `config_match` e `config_change` como texto YAML
Kernel::System::Cache	Armazena em cache consultas de ACL com TTL (SysConfig: `ACL::CacheTTL`)
Tabela acl_sync	Registra quais ACLs são novas ou foram alteradas (sync_state), para acionar implantações
ZZZACL.pm	Arquivo Perl gerado que, ao ser implantado, disponibiliza todos os ACLs validados nos módulos de ticket

perl

# Exemplo: Serialização YAML antes do INSERT no DB
my $YAML = $Kernel::OM->Get('Kernel::System::YAML');
my $ConfigMatchYAML  = $YAML->Dump(Data => $Param{ConfigMatch});
my $ConfigChangeYAML = $YAML->Dump(Data => $Param{ConfigChange});
$DBObject->Do(
    SQL  => 'INSERT INTO acl (..., config_match, config_change, ...) VALUES (?, ?, ?, ...)',
    Bind => [\$ConfigMatchYAML, \$ConfigChangeYAML, ...],
);

Observação: O superusuário (UserID 1) ignora automaticamente todos os ACLs – para não se bloquear.

3. Estrutura Básica de um ACL: Match vs. Action

Seção	Tarefa
Match	Define condições: verifica atributos de ticket (Properties) ou valores do DB (PropertiesDatabase).
Action	Especifica quais elementos da UI (botões, campos) são exibidos ou ocultos (Possible, PossibleAdd, PossibleNot) ou quais ações são executadas (mudança de status/fila).

Exemplo de Opções de Match:

Queue, Status, Priority
DynamicField_<Name>, CustomerUser, Owner
Frontend::Module (AgentTicketZoom, CustomerTicketCreate)

Exemplo de Opções de Action:

Possible: Lista branca, permitindo apenas certas filas ou status.
PossibleAdd: Adiciona valores extras em uma seleção limitada.
PossibleNot: Remove certos botões (por exemplo, AgentTicketClose) da UI.

4. Configurações Importantes do SysConfig

Os elementos principais mencionados acima são configurados via SysConfig:

Chave	Descrição	Valor de Exemplo
`ACL::CacheTTL`	Tempo de vida do cache em segundos (Backend)	`3600`
`ACLKeysLevel1MatchTicket`	Primeira camada permitida para Match (Properties, PropertiesDatabase)	`Properties, PropertiesDatabase`
`ACLKeysLevel1ChangeTicket`	Primeira camada permitida para Change (Possible, PossibleAdd, PossibleNot)	`Possible, PossibleAdd, PossibleNot`
`ACLKeysLevel2::PropertiesTicket`	Chaves de Match permitidas (Queue, State, DynamicField, etc.)	`Queue, State, CustomerUser, ...`
`ACLKeysLevel2::PossibleTicket`	Chaves de Change permitidas (Form, FormStd, Action, Process, Ticket)	`Form, FormStd, Action, ...`
`ACLKeysLevel3::Actions###DefaultTicket`	Lista de todas as ações possíveis na UI (AgentTicketClose, AgentTicketEmail, ...)	(ver lista)

Dica: Ajuste ACLKeysLevel* para popular a UI de ACL apenas com entradas relevantes.

Avaliação, Stop-on-Match e Performance

A avaliação das ACLs (Access Control Lists) determina quais regras são aplicadas quando um ticket é carregado ou uma ação é executada no sistema de tickets. Uma configuração eficiente desses fluxos, bem como otimizações de performance direcionadas, são cruciais para garantir uma interface de agente fluida e escalável.

Ciclo de Avaliação

Cada vez que um agente abre um ticket ou executa uma ação (por exemplo, clique em um botão), o OTOBO percorre a lista de todas as ACLs ativas, ordenadas por sua chave de ordenação (Nome ou ID). O seguinte fluxo mostra o processo de verificação e execução:

Match (ConfigMatch): Critérios como Fila, Status, Prioridade ou Campos Dinâmicos são verificados aqui.
Change (ConfigChange): Define quais elementos da UI são removidos ou adicionados (Possible, PossibleAdd, PossibleNot) ou quais ações automáticas ocorrem (mudança de Fila/Status).
StopAfterMatch: Se definido como 1, o processamento é interrompido após a primeira ACL correspondente.

Lembrete: Um StopAfterMatch corretamente definido evita que ACLs subsequentes acionem alterações indesejadas.

Estratégias de Stop-on-Match

Opção	Efeito
StopAfterMatch=1	Assim que uma ACL corresponde, nenhuma outra é verificada – ideal para regras exclusivas.
StopAfterMatch=0	Todas as ACLs são verificadas – necessário quando várias ACLs devem intervir independentemente.

Dica: Prefixos numéricos (por exemplo, 100-, 200-) no nome da ACL controlam a ordenação natural e, portanto, a prioridade de regras críticas.

Otimização de Performance

Um grande conjunto de ACLs pode aumentar os tempos de carregamento dos formulários de ticket. Estas medidas ajudam a aumentar a performance:

Ajustar CacheTTL: Em SysConfig, em ACL::CacheTTL (por exemplo, 3600 s), você define por quanto tempo as definições de ACL carregadas permanecem no cache.
Ativar Cache de Pré-seleção: O módulo TicketACL::ACLPreselection preenche opções pré-selecionadas antecipadamente e economiza verificações repetidas.
Redução de Regras: Remova ACLs obsoletas ou duplicadas e agrupe regras semelhantes.
Otimizar Sequência: Coloque ACLs frequentemente correspondentes no início da lista.
Campos Indexados: Utilize índices de DB para Campos Dinâmicos e outras propriedades frequentemente consultadas.

xml


<Setting ID="ACL::CacheTTL">
    <Group>Core::Ticket::ACL</Group>
    <Value>3600</Value>
    <Description>Tempo de vida do cache para backends de DB-ACL em segundos.</Description>
</Setting>

Manutenção e Melhores Práticas

Prática	Benefício
Exportação YAML	Versiona ACLs no Git para rastrear alterações.
Documentação	Crie um log de alterações com carimbos de data/hora, autor e objetivo do ACL.
Revisão de Regras	Revisões regulares em equipe evitam sobreposições.
Ambiente de Teste	Valide novos ACLs com tickets de teste controlados.
Depuração de Logs	Ative logs de depuração (`TicketACL::Debug::Enabled`) para insights detalhados.

Configurar Depuração

xml


<Setting ID="TicketACL::Debug::Enabled">
    <Group>Core::Ticket::ACL</Group>
    <Value>1</Value>
    <Description>Ativar depuração de ACL</Description>
</Setting>
<Setting ID="TicketACL::Debug::Filter###00-DefaultTicket.xml">
<Group>Core::Ticket::ACL</Group>
<Value>&lt;OTOBO_TICKET_TicketID&gt;</Value>
<Description>Filtro para saídas de depuração por ID de ticket.</Description>
</Setting>

Através dessas estratégias direcionadas, você garante que sua infraestrutura de ACL no OTOBO permaneça tanto performática quanto manutenível – mesmo em ambientes grandes e distribuídos.

Exemplos Práticos, Governança e Referência

Nesta seção final do artigo, demonstramos como os ACLs podem ser usados na prática no OTOBO com cenários concretos. Em seguida, abordamos métodos de governança comprovados e fornecemos referências para leituras adicionais.

Exemplos Práticos

1. Priorização Automática para a Fila "Alarme"

Objetivo: Mover imediatamente tickets com prioridade 5 (muito alta) para a fila Alarme e notificar o responsável.

yaml

- Name: "100-Auto-Alarm"
  StopAfterMatch: 1
  ValidID: 1
  ConfigMatch:
    Properties:
      Priority:
        ID: [ 5 ]
  ConfigChange:
    PossibleNot:
      Form:
        - ticketCreateQuickClose
    PossibleAdd:
      Form:
        - ticketCreateNotifyOwner
    Action:
      Queue: "Alarm"

Configurações Básicas Dados básicos do ACL e configuração de Match

Configurações de Ação Change do ACL: Mudança de Fila e Adição de Botão

2. Proteção contra Escalonamento para Tickets com Prioridade "Muito Alta"

Objetivo: Impedir que tickets com prioridade de banco de dados 5 sejam fechados.

yaml

- Name: "101-No-Close-High"
  StopAfterMatch: 1
  ValidID: 1
  ConfigMatch:
    PropertiesDatabase:
      Priority:
        Name: [ "5" ]
  ConfigChange:
    PossibleNot:
      Action:
        - AgentTicketClose

Proteção contra Escalonamento Change do ACL: Ocultar botão de Fechar

3. Restrição de UI por Fila

Objetivo: Na fila Suporte, a opção de status resolvido não deve estar disponível.

yaml

- Name: "102-Hide-Resolved-Support"
  ValidID: 1
  ConfigMatch:
    Properties:
      Queue:
        Name: [ "Support" ]
  ConfigChange:
    PossibleNot:
      FormStd:
        - State::resolved

Remover Status Change do ACL: Remover opção de status

4. Restrição de Processo do Cliente

Objetivo: Clientes não podem mover seus próprios tickets para outras filas.

yaml

- Name: "103-Cust-No-Reassign"
  ValidID: 1
  ConfigMatch:
    Properties:
      Frontend:
        Action:
          - CustomerTicketZoomReply
  ConfigChange:
    PossibleNot:
      Action:
        - AgentTicketMove

Restringir Processo do Cliente Change do ACL: Ocultar botão de Mover para clientes

5. Escalonamento Baseado em Tempo após 48 Horas

Objetivo: Tickets abertos há mais de 48 horas são automaticamente atribuídos a Agentes Seniores.

yaml

- Name: "104-Escalate-48h"
  ValidID: 1
  ConfigMatch:
    Properties:
      Ticket:
        CreateTimeOlderThan: 48h
  ConfigChange:
    Action:
      Owner: "Senior-Agenten"

Observação: Este cenário pode exigir uma extensão para critérios de match baseados em tempo.

Governança e Documentação

Medida	Descrição
Convenção de Nomes	Prefixos numéricos (por exemplo, `100-`, `200-`) para ordenação e clareza.
Changelog	Registre `Name`, `Comment`, `ChangeTime` e `ChangeBy` para cada alteração de ACL.
Processo de Revisão	Realize revisões regulares para evitar sobreposições e conflitos.
Versionamento	Exporte ACLs como YAML e versiona no Git ou em uma ferramenta de documentação.
Testes	Valide ACLs em um ambiente de teste com tickets de teste específicos.

Referências Adicionais

Referência de ACL (YAML): Kernel/Config/Files/ZZZACL.pm (gerado)
Chaves SysConfig ACL: Termos de Nível 1-3 para controle fino (Core::Ticket::ACL)
Documentação de Campos Dinâmicos: Integração de campos dinâmicos em ACLs

Com estes exemplos práticos e recomendações de governança, você agora possui as ferramentas para operar ACLs no OTOBO de forma segura, eficiente e rastreável.

OTOBO Znuny ACLs ​

1. Conceitos e Valor de Negócio ​

1.1 ACLs Baseados em Papéis e Critérios ​

2. Visão Geral da Arquitetura ​

3. Estrutura Básica de um ACL: Match vs. Action ​

4. Configurações Importantes do SysConfig ​

Avaliação, Stop-on-Match e Performance ​

Ciclo de Avaliação ​

Estratégias de Stop-on-Match ​

Otimização de Performance ​

Manutenção e Melhores Práticas ​

Configurar Depuração ​

Exemplos Práticos, Governança e Referência ​

Exemplos Práticos ​

1. Priorização Automática para a Fila "Alarme" ​

2. Proteção contra Escalonamento para Tickets com Prioridade "Muito Alta" ​

3. Restrição de UI por Fila ​

4. Restrição de Processo do Cliente ​

5. Escalonamento Baseado em Tempo após 48 Horas ​

Governança e Documentação ​

Referências Adicionais ​

OTOBO Znuny ACLs

1. Conceitos e Valor de Negócio

1.1 ACLs Baseados em Papéis e Critérios

2. Visão Geral da Arquitetura

3. Estrutura Básica de um ACL: Match vs. Action

4. Configurações Importantes do SysConfig

Avaliação, Stop-on-Match e Performance

Ciclo de Avaliação

Estratégias de Stop-on-Match

Otimização de Performance

Manutenção e Melhores Práticas

Configurar Depuração

Exemplos Práticos, Governança e Referência

Exemplos Práticos

1. Priorização Automática para a Fila "Alarme"

2. Proteção contra Escalonamento para Tickets com Prioridade "Muito Alta"

3. Restrição de UI por Fila

4. Restrição de Processo do Cliente

5. Escalonamento Baseado em Tempo após 48 Horas

Governança e Documentação

Referências Adicionais