Gatilhos — /triggers

Uma Coleta com Parâmetros de Entrada e uma Entrega com contrato de entrada (Payload de Entrada, ou tags de escrita em OPC UA, Modbus, Sparkplug e PI) são orientadas a evento: só executam quando alguém chama a API dinâmica do CMS com os valores. Nem sempre existe esse alguém — o sistema que deveria chamar não foi construído, ou a consulta é a mesma todo dia.

O Gatilho resolve isso por dentro do CMS. Ele guarda os valores fixos que um produtor externo mandaria e um agendamento próprio, e no horário marcado executa a Definição pelo mesmo caminho da API dinâmica. Nada muda no agendador das Interfaces: o Gatilho é um chamador interno com agenda, não um segundo motor de execução.

O que aparece na lista

• Coletas: só as que precisam de parâmetros — elegíveis à API dinâmica (HTTP, SQL Server, Oracle, SQLite, PostgreSQL, InfluxDB, MongoDB, SAP RFC, PI Web API) e com ao menos um Parâmetro de Entrada declarado. Uma Coleta pull comum não aparece: ela já roda sozinha no agendador da Interface, e um Gatilho a faria rodar duas vezes.
• Entregas: todas, menos as das ferramentas de Help Desk — chamado se abre por alerta ou pelo botão do cabeçalho, não por agenda. Uma Entrega só acontece quando alguém entrega uma mensagem, então um Gatilho de Entrega é “criar esta mensagem neste horário”. A que declara contrato de entrada (Payload de Entrada, tags de escrita OPC UA ou Modbus, métricas de comando Sparkplug, tags de escrita PI) abre nos Campos, um por alias; a que não declara abre direto no Corpo, onde você escreve a mensagem.

Se a Coleta que você procura não aparece, é porque o cadastro dela ainda não declara Parâmetros de Entrada — declare lá primeiro.

Criando um Gatilho

1. Nome livre, único. É o nome que aparece em Agendadores.
2. Alvo: escolha Coleta ou Entrega e a Definição. Os combos de Aplicação e Interface são só um funil para achar a Definição; quem escolhe a Definição direto na busca vê os dois preenchidos.
3. Parâmetros: um campo por alias do contrato. Obrigatório sem valor padrão precisa vir preenchido; vazio usa o valor padrão do cadastro, quando houver. Para alvos de equipamento (OPC UA, Modbus, Sparkplug, PI) a tela mostra o destino de cada valor e avisa que os valores serão gravados no equipamento no horário marcado.
   • Na Coleta, um botão alterna entre Campos e JSON: é o mesmo objeto de aliases, só que editado como texto — útil para colar o corpo que já existe numa ferramenta externa. Voltar para Campos exige um JSON plano válido.
   • Na Entrega, o botão alterna entre Campos e Corpo. No Corpo você escreve a mensagem inteira, no Content-Type que escolher (JSON, XML ou texto), e ela entra pelo mesmo caminho de um POST externo: validação de Content-Type, Transformer e Erros de Negócio da Entrega. Ao trocar para Corpo, o texto começa com o JSON dos campos preenchidos; ao voltar, um JSON plano vira campos de novo, e XML ou JSON aninhado começa com os campos vazios. Se o corpo é JSON e a Entrega declara contrato, os obrigatórios ainda são conferidos no salvar; XML e texto ficam por conta da própria Entrega, como para qualquer produtor.
4. Agendamento, em cinco modos: a cada N segundos/minutos/horas; diário (com opção de só dias úteis); semanal (dias marcados e horário); mensal (dia 1 a 28 ou último dia do mês); ou uma expressão cron. A tela mostra a frase legível e as próximas três execuções, no fuso do servidor.

Ativar, pausar, executar agora

Todo Gatilho nasce desativado. Criar não executa nada.

• Ativar só acontece nesta tela, depois de uma pergunta que mostra o alvo, os parâmetros, a frequência e a próxima execução. A regra é do servidor: tentar ligar um Gatilho pela tela de Agendadores é recusado, e a tela leva você para cá.
• Pausar é imediato, daqui ou de Agendadores.
• Executar agora dispara uma execução fora da agenda. Num Gatilho mensal de “último dia”, o disparo manual ignora a regra do dia — é exatamente para testar.

O que acontece na execução

• Coleta: a busca roda na origem com os parâmetros fixos, e as mensagens seguem o encaminhamento configurado na Coleta. Se a Aplicação de origem estiver offline, os parâmetros ficam guardados e a Interface reexecuta a busca quando ela voltar.
• Entrega: nasce uma mensagem na Interface — com o corpo {alias: valor} no modo Campos, ou com o texto cru e o Content-Type escolhido no modo Corpo — e ela segue o fluxo normal — Transformer, Erro de Negócio, retentativas. A mensagem não é marcada como teste.
• Alvo desativado, contrato que mudou e deixou um obrigatório sem valor, falha na origem: tudo vira erro no histórico do agendador e na coluna “Última execução”. O Gatilho não se desliga sozinho — quem decide pausar é você, olhando o erro.
• Nas telas de Mensagens, a mensagem gerada por um Gatilho leva um raio discreto ao lado do status, com o nome do Gatilho no título; o popup e a página de detalhe mostram o raio com o nome. É só uma marca de origem, sem atalho: diferente da mensagem de teste, ela é tráfego real e conta em painéis e relatórios.

Em Agendadores

Cada Gatilho é um agendador trigger-<id>, listado no grupo Gatilhos de Agendadores, com o nome que você deu. Lá dá para pausar, executar agora e ver o histórico de execuções; editar o agendamento e ativar são feitos aqui.

Histórico

Dois históricos, por botões distintos na linha:

• Execuções — cada disparo, com duração, resultado e mensagem (o mesmo histórico do agendador).
• Alterações — quem criou, quem alterou o quê (antes e depois), quem ativou, desativou, executou manualmente ou excluiu. Sai do log de auditoria.

Import/Export, Packs e MCP

Gatilhos viajam no Import/Export como o domínio Gatilhos, referenciando a Definição alvo pela sigla. Um Pack pode declarar Gatilhos para as próprias Coletas e Entregas. Pelo Servidor MCP, cms_list_triggers lista e cms_create_trigger cria. Em todos os casos o Gatilho chega desativado.

Permissão

A Ferramenta é /triggers, no grupo Config. de Integração, logo após Entregas. O recorte é o mesmo das demais telas de cadastro: você vê os Gatilhos cujas Definições alvo estão nas suas Interfaces.