Tarefas Externas e Workers

Uma EXTERNAL_TASK modela um passo cuja conclusão não está sob controle direto do motor — uma aprovação humana em uma tela, um callback assíncrono de um sistema externo, um evento que chega horas ou dias depois. Diferente de uma EXECUTABLE_TASK, não há TaskHandler associado: o nó simplesmente fica pendente até que algo, de fora, sinalize que ele terminou.

Pense em uma ficha de matrícula escolar

Você entrega a ficha, a escola confere os documentos — e então a ficha fica em uma pilha aguardando a assinatura da diretora. O processo não terminou. Não foi cancelado. Está parado em um ponto específico, aguardando uma ação externa. Quando a diretora assina, o processo avança para o próximo passo.

Uma tarefa externa no Kikwiflow funciona assim: a instância está ativa, persiste seu estado, e aguarda uma chamada externa (via API REST, o Monitor, ou um evento) que a sinalize para avançar. Nenhum recurso de CPU é consumido enquanto espera — não há uma thread bloqueada, parada, contando os segundos.

No processo de abertura de conta, Aprovar Abertura é exatamente isso: depois que Calcular Score grava o score, o processo para ali, e não avança sozinho — nem em um segundo, nem em uma hora — até que o analista de crédito revise o resultado e registre a decisao.

Modelar no Craft

No canvas, Aprovar Abertura é um External Task. O campo Ator/Executor identifica quem é responsável pela tarefa (usado pelo Monitor para filtrar filas), e vai para extensionProperties:

{
  "id": "EXTERNAL_E5F3809A",
  "name": "Aprovar Abertura",
  "type": "EXTERNAL_TASK",
  "extensionProperties": { "actor": "analista_credito" },
  "outgoing": [ { "targetNodeId": "DEFAULT_84F32C05" } ]
}

Não há campo executor — não há bean Spring a resolver. O nó apenas cria um registro de tarefa pendente e aguarda.

Ciclo de vida

1. Criada — quando o fluxo alcança o nó, uma ExternalTask pendente é registrada.
2. claim (opcional) — um worker ou operador reivindica a tarefa para si, evitando que outra pessoa processe o mesmo item ao mesmo tempo. No Monitor, é o botão Assumir Tarefa.
3. complete — alguém (um operador via Monitor, um endpoint da sua aplicação, um job) sinaliza que a tarefa terminou, opcionalmente entregando variáveis de processo. O motor então continua o fluxo a partir dali, mesclando essas variáveis na instância — de forma síncrona, até o próximo ponto de commitBefore ou o fim do processo.

Completar a tarefa fora do Monitor — via API REST de gestão ou programaticamente com KikwiflowEngine, para quando a conclusão vem de um sistema, não de uma pessoa — está em Operando via API REST.

Operar no Monitor

Com uma instância parada em Aprovar Abertura, abra-a no Monitor e clique no card da tarefa. O modal mostra o contexto da instância (incluindo o score que Calcular Score gravou) e um editor de variáveis. No mundo real, é aqui que o analista de crédito decide: adicione a variável decisao (APROVADA ou RECUSADA) e clique em Completar e Avançar. O fluxo retoma na hora e a instância chega em Conta Aberta.

📸 [ASSET NECESSÁRIO] Print do modal de tarefa externa "Aprovar Abertura" no Monitor: o contexto da instância com score visível, o editor de variáveis com decisao sendo preenchida, e os botões Assumir/Completar. Incluir no documento de assets: monitor-aprovar-abertura-modal.png

Quando usar / quando não usar

Use EXTERNAL_TASK quando o próximo passo depende de um evento que chega em um momento indeterminado — minutos, horas ou dias depois — e não faz sentido bloquear uma thread esperando por ele: uma aprovação humana como Aprovar Abertura, um webhook de um parceiro, o upload de um documento. Combine com um timer de borda quando essa espera precisa de um prazo (ex.: recusar automaticamente se o analista não decidir em 48h).

Não use para lógica síncrona que roda inteiramente dentro da sua aplicação e retorna na hora — isso é EXECUTABLE_TASK.

Próximo passo

Uma espera indefinida raramente é aceitável em produção — o capítulo Timers e Prazos mostra como dar um prazo a Aprovar Abertura. Antes disso, veja como rotear o fluxo com base em uma decisão de negócio em Decisões e Gateways.