Tarefas Externas

Opera o ciclo de vida de uma EXTERNAL_TASK (ver Tarefas Externas e Workers para o conceito) de fora do processo Java que hospeda o motor — o caso típico de um worker em outra linguagem, uma tela de tarefas humanas, ou um sistema externo que sinaliza conclusão via webhook.

Operação	Endpoint
Reivindicar (claim)	PUT /external-tasks/{id}/claim/{assignee}
Liberar (unclaim)	PUT /external-tasks/{id}/unclaim
Completar	POST /external-tasks/{id}/complete
Buscar por id	GET /external-tasks/{id}
Listar	GET /external-tasks
Contar	GET /external-tasks/count

Comandos (claim/unclaim/complete) requerem KikwiflowEngine; consultas ({id}/listar/contar) requerem QueryRepository.

Reivindicar

PUT /external-tasks/{id}/claim/{assignee}

Marca assignee como responsável pela tarefa, sinalizando a outros workers/operadores que ela já está sendo tratada. Resposta 204 No Content. claim não é pré-requisito para complete — é só uma convenção para evitar processamento duplicado do mesmo item; nada impede completar uma tarefa nunca reivindicada.

Liberar

PUT /external-tasks/{id}/unclaim

Desfaz o claim atual. Resposta 204 No Content.

Completar

POST /external-tasks/{id}/complete
Content-Type: application/json

{ "variables": { "resultadoAnalise": { "name": "resultadoAnalise", "value": "APROVADO" } } }

Resposta 202 Accepted com a ProcessInstance atualizada — o fluxo avança de forma síncrona dentro desta mesma chamada até o próximo ponto de espera ou o fim do processo (mesmo modelo de completeExternalTask via KikwiflowEngine).

:::info Dois campos do corpo não têm efeito hoje CompleteExternalTaskRequest também aceita tenant e targetFlowNodeId, mas o controller REST não os repassa ao motor — só variables chega em KikwiflowEngine.completeExternalTask. Envie-os se quiser (não geram erro), mas não espere que mudem o comportamento da chamada; se sua integração precisa validar tenant ou redirecionar para um nó específico ao completar, isso ainda não existe nesta camada REST. :::

Buscar por id

GET /external-tasks/{id}

200 OK com a ExternalTask completa, ou 404 (NOT_FOUND).

Listar e contar

GET /external-tasks?process-definition-id=&tenant-id=&assignee=&process-instance-id=&process-instance-id-in=&task-definition-id=&tenant-ids=
GET /external-tasks/count?process-definition-id=&tenant-id=&assignee=&process-instance-id=&process-instance-id-in=&task-definition-id=&tenant-ids=

Os dois endpoints aceitam os mesmos sete parâmetros na assinatura, mas implementam subconjuntos diferentes — um parâmetro fora da lista suportada para aquele endpoint lança NotImplementedException → 501, em vez de ser ignorado:

Parâmetro	GET /external-tasks (listar)	GET /external-tasks/count
process-definition-id	✅ suportado	✅ suportado
tenant-id	✅ suportado	✅ suportado
assignee	✅ suportado	✅ suportado
process-instance-id	✅ suportado	❌ 501
process-instance-id-in	❌ 501	❌ 501
task-definition-id	❌ 501	❌ 501
tenant-ids	❌ 501	❌ 501

Note a assimetria em process-instance-id: funciona em GET /external-tasks?process-instance-id=... mas lança 501 em GET /external-tasks/count?process-instance-id=.... Todos os filtros suportados são combináveis entre si (AND); nenhum é obrigatório — sem nenhum parâmetro, ambos os endpoints operam sobre todas as tarefas externas.

Respostas: 200 OK com ExternalTask[] (não paginado) para listar; 200 OK com { "total": N } para contar.