Olá, como podemos ajudar você?

  1. Página inicial
  2. Voltar para a pesquisa
  3. Módulo Administrativo
  4. Fluxo de Trabalho
Evento de tarefa: regras automáticas nas tarefas do fluxo de trabalho
15 min
Criado por Raphael Borba em 23/10/2026 16:38
Atualizado por Mauricio Rodrigues de Macedo Junior em 28/10/2026 16:15
Tags: ParametrizaçãoKanban

Evento de tarefa: regras automáticas nas tarefas do fluxo de trabalho


Nesse artigo você vai aprender

O que é um evento de tarefa, como cadastrar um, como ligá-lo a uma tarefa do fluxo de trabalho, em quais momentos ele roda, quais verificações prontas existem e como escrever o script. No final há um exemplo completo: impedir que uma tarefa seja concluída sem anexo.



Descrição

Um evento de tarefa é uma regra escrita em script (JavaScript) que o Pontta executa automaticamente em momentos da vida de uma tarefa de fluxo de trabalho: quando ela é agendada, concluída ou cancelada.


O evento é cadastrado uma vez e pode ser usado em quantas tarefas e fluxos você quiser. Com ele é possível, por exemplo:

  • Impedir uma ação: barrar a conclusão, o agendamento ou o cancelamento quando uma regra da empresa não for cumprida.
  • Avisar pessoas: notificar ou enviar e-mail para alguém quando a tarefa for concluída.
  • Atualizar informações: atualizar dados do registro ligado à tarefa.


Além dos scripts, a mesma tela de regras da tarefa do fluxo oferece verificações prontas, sem programação, como Tarefa anterior está concluída (seção 5).


Nota: eventos de tarefa só valem para tarefas criadas por um fluxo de trabalho. Tarefas avulsas não executam eventos.



Sumário

Utilize os links abaixo para ir diretamente à seção desejada:



⚓ 

1. Onde fica

Os eventos de tarefa ficam na Administração:

    1 - Abra Fluxo de trabalho.

    2 - Clique em Evento de tarefa.



⚓ 

2. Cadastrar um evento de tarefa

A tela Evento de tarefa lista os eventos já cadastrados:

    1 - Clique no + para cadastrar um novo evento.

    2 - Os três pontos de cada linha trazem as opções do evento já cadastrado.


Na tela Novo evento de tarefa:

    1 - Executar um script: é o único tipo de evento cadastrável nesta tela 

    2 - Nome: obrigatório. Use um nome que diga o que a regra faz. Ele aparece na hora de escolher o evento e também nas mensagens de erro do script.

    3 - Script: o código JavaScript que será executado (seção 7). Também é obrigatório.

    4 - Clique em CRIAR.


Nota: cadastrar o evento não faz ele rodar. Ele só passa a ser executado depois de ligado a uma tarefa do fluxo de trabalho (seção 3).



⚓ 

3. Ligar o evento a uma tarefa do fluxo

Acesse Administração > Fluxo de trabalho > Fluxos de trabalho e abra o fluxo desejado. No final da tela:

    1 - Clique nos três pontos da tarefa que vai receber o evento.

    2 - Clique em Alterar as regras.


Role a tela de regras até os momentos de verificação:

    1 - Verificar eventos usando operadores (avançado): liga o modo com E, OU e NÃO (seção 6). Deixe desmarcado para o uso comum.

    2 - Clique no + do momento em que o evento deve rodar. No exemplo, Antes do agendamento.

    3 - Tipo de evento: escolha o que será verificado (seção 5).

    4 - O − remove a linha.

    5 - Clique em ATUALIZAR para salvar as regras.


Para usar um evento cadastrado na seção 2:

    1 - Em Tipo de evento, escolha Executar um script.

    2 - No campo Evento, escolha o evento cadastrado.

    3 - Clique em ATUALIZAR.


Nota: as regras valem para a posição daquela tarefa naquele fluxo. Se a mesma tarefa de fluxo é usada em outro fluxo, configure as regras lá também.



⚓ 

4. Momentos: quando cada evento roda

Cada momento é ligado a uma ação sobre a tarefa:

  • Antes do agendamento / Após o agendamento: quando a tarefa é agendada para um colaborador.
  • Antes de completar / Após completar: quando o estágio da tarefa muda para Concluída, seja nos detalhes da tarefa, em Minhas tarefas ou no kanban.
  • Antes de cancelar / Após cancelar: quando a tarefa é cancelada.


A diferença entre antes e após:

  • Antes: rodam antes da ação. Se um deles falhar, a ação não acontece e o usuário vê a mensagem. É o lugar para validações.
  • Após: rodam logo depois da ação, ainda na mesma operação. O script já enxerga a tarefa agendada, concluída ou cancelada. É o lugar para avisos e atualizações.


Quando um momento tem mais de um evento, eles rodam na ordem da lista e todos precisam passar. O primeiro que falhar interrompe a ação.


Nota: em Antes de completar, os eventos rodam antes das outras regras de conclusão da tarefa (checklist, formulário, tarefas anteriores). Um aviso em Antes de completar pode ser enviado mesmo que a conclusão seja barrada logo depois por outra regra. Para avisos, prefira Após completar.



⚓ 

5. Tipos de evento

    1 - Verificações prontas: conferem a situação da própria tarefa ou das tarefas anteriores do fluxo, sem script.

    2 - Executar um script: roda um evento cadastrado em Evento de tarefa.


O que cada verificação pronta exige e a mensagem que aparece quando ela não é cumprida:

  • Tarefa anterior está agendada: todas as tarefas anteriores do fluxo têm agendamento. Mensagem: A tarefa [nome] não está agendada.
  • Tarefa anterior está concluída: todas as tarefas anteriores estão concluídas. Mensagem: A tarefa [nome] não está concluída.
  • Tarefa anterior está cancelada: todas as tarefas anteriores estão canceladas. Mensagem: A tarefa [nome] não está cancelada.
  • Tarefa está agendada: a própria tarefa tem agendamento.
  • Tarefa está concluída: a própria tarefa está concluída.
  • Tarefa está cancelada: a própria tarefa está cancelada.


Exemplo de uso sem script: em uma tarefa de instalação, coloque Tarefa anterior está concluída em Antes do agendamento. Assim ninguém agenda a instalação antes de concluir a tarefa anterior, como a medição.


Nota: as verificações da própria tarefa fazem mais sentido nos momentos Após ou em outra ação. Tarefa está concluída em Antes de completar, por exemplo, sempre falha, porque a tarefa ainda não foi concluída nesse momento.



⚓ 

6. Verificar eventos usando operadores

Com Verificar eventos usando operadores (avançado) marcado, cada evento recebe um operador:

  • E: o evento é obrigatório.
  • NÃO: o contrário do evento é obrigatório. Por exemplo, NÃO Tarefa anterior está cancelada exige que nenhuma tarefa anterior esteja cancelada.
  • OU: entre os eventos OU, basta um ser cumprido. Vale quando o momento só tem eventos OU.


Nota: não misture eventos OU com eventos E ou NÃO no mesmo momento. Com um único OU, ele é ignorado e só os eventos E e NÃO são verificados. Com dois ou mais OU, o Pontta não verifica nenhum evento daquele momento.



⚓ 

7. Escrevendo o script

O script é JavaScript e roda no servidor do Pontta. Ele recebe prontas as informações da tarefa:

  • taskId: identificador da tarefa.
  • referenceKey: tipo do registro de onde a tarefa veio (por exemplo SALES_ORDER para pedido de venda).
  • referenceId: identificador desse registro.
  • cooperatorId: identificador do colaborador que fez a ação.


  • notification: envia notificações dentro do Pontta.
  • mail: envia e-mails.


Para impedir a ação, use throw com a mensagem para o usuário. O Pontta mostra a mensagem com o nome do evento na frente, no formato Em "Nome do evento": mensagem.


Nota: o script roda dentro da ação do usuário. Um script lento (por exemplo, chamando um serviço externo que demora) deixa a conclusão, o agendamento ou o cancelamento lento para todo mundo. Um erro de programação no script também barra a ação. Teste sempre no ambiente de teste antes de ligar o evento em produção.



⚓ 

8. Exemplo: exigir anexo para concluir a tarefa

Objetivo: em uma tarefa de conferência, o colaborador só pode concluir depois de anexar pelo menos um arquivo (uma foto, um documento assinado).


Passo 1: cadastrar o evento

Em Administração > Fluxo de trabalho > Evento de tarefa, clique no + e preencha:

  • Nome: Exigir anexo para concluir
  • Script: o código abaixo
// Evento: Exigir anexo para concluir
// Usar em: Antes de completar, verificar se > Executar um script

var anexo = db.find(
  "SELECT 1 AS existe FROM file_storage WHERE reference ->> 'TASK' = :taskId LIMIT 1",
  { taskId: String(taskId) }
);

if (anexo == null) {
  throw 'Anexe pelo menos um arquivo na tarefa antes de concluí-la.';
}

O que o script faz: procura um arquivo anexado à tarefa. Se não encontrar, interrompe a conclusão com a mensagem.


Passo 2: ligar o evento à tarefa

    1 - Abra o fluxo de trabalho e, na tarefa de conferência, clique nos três pontos > Alterar as regras.

    2 - Em Antes de completar, verificar se, clique no +.

    3 - Em Tipo de evento, escolha Executar um script e, em Evento, escolha Exigir anexo para concluir.

    4 - Clique em ATUALIZAR.


Resultado

Ao tentar mudar a tarefa para Concluída sem anexo, o Pontta não conclui e mostra: Em "Exigir anexo para concluir": Anexe pelo menos um arquivo na tarefa antes de concluí-la. Depois de anexar um arquivo nos detalhes da tarefa, a conclusão funciona normalmente.


Outro exemplo: avisar o gerente quando a tarefa for concluída

Ligue este evento em Após completar, verificar se. Troque o e-mail pelo de um colaborador cadastrado no Pontta: a notificação só chega a quem é colaborador.

// Evento: Avisar gerente ao concluir
// Usar em: Após completar, verificar se > Executar um script

var Set = Java.type('java.util.Set');

var tarefa = db.get(
  'SELECT title, reference_name FROM task WHERE id = :taskId',
  { taskId: taskId }
);

notification.notify(
  'Tarefa concluída',
  'A tarefa ' + tarefa.title + ' (' + tarefa.reference_name + ') foi concluída.',
  Set.of('gerente@suaempresa.com.br')
);



⚓ 

Dúvidas frequentes

Cadastrei o evento, mas ele não roda.

O evento precisa estar ligado a uma tarefa do fluxo (seção 3). Confira também se a tarefa foi criada por esse fluxo e se a ação feita corresponde ao momento escolhido.


Aparece Em "nome do evento": e uma mensagem que eu não escrevi.

O script deu erro durante a execução. Corrija o script em Evento de tarefa. Enquanto isso, a ação fica bloqueada para todos.


Preciso desligar o evento com urgência.

Abra o fluxo, clique em Alterar as regras na tarefa, remova a linha do evento com o − e clique em ATUALIZAR.


Aparece A tarefa [nome] não está concluída ao agendar.

A tarefa tem a verificação Tarefa anterior está concluída em Antes do agendamento. Conclua as tarefas anteriores do fluxo ou revise a regra.


O evento funciona para tarefas criadas à mão?

Não. Só tarefas criadas por um fluxo de trabalho executam eventos.


Alterei o script. Preciso ligar o evento de novo?

Não. As tarefas do fluxo usam sempre a versão atual do evento.

Este artigo foi útil para você?
Últimos artigos visitados