Pular para o conteúdo principal

Instâncias de Processo

Uma ProcessInstance é uma execução concreta de uma Definição de Processo. Este documento cobre o ciclo de vida básico (iniciar, consultar, alterar variáveis, encerrar). Para busca com filtros ricos, veja Busca Avançada de Instâncias.

OperaçãoEndpoint
Iniciar uma instânciaPOST /process-instances
Buscar uma instância por idGET /process-instances/{id}
Listar instâncias (por ids, ou por definição+tenant)GET /process-instances
Contar instâncias de uma definiçãoGET /process-instances/count?process-definition-id=
Atualizar (mesclar) variáveisPUT /process-instances/{id}/variables
Remover variáveisPUT /process-instances/{id}/variables/unset
Encerrar/remover uma instânciaPUT /process-instances/{id}
Incidentes de uma instânciaGET /process-instances/{id}/incidents
Snapshot completo de uma instânciaGET /process-instances/{id}/snapshot
Listar com paginação (deprecated)GET /process-instances/summary — use POST /search

Todos requerem QueryRepository no contexto exceto POST /process-instances, PUT .../variables, PUT .../variables/unset e PUT /process-instances/{id}, que requerem KikwiflowEngine.

Iniciar uma instância​

POST /process-instances
Content-Type: application/json
{
  "processDefinitionKey": "abertura-de-conta",
  "tenant": "empresa-abc-123",
  "businessKey": "solicitacao-42",
  "businessValue": 15000.00,
  "origin": "portal-vendas",
  "variables": {
    "cpf": { "name": "cpf", "value": "11122233344" }
  }
}
CampoObrigatórioPapel
processDefinitionKeysimResolve sempre para a versão mais recente implantada daquela key.
targetFlowNodeIdnãoInicia a instância diretamente num nó específico em vez de defaultStartPoint — uso avançado (retomar/simular a partir de um ponto do fluxo).
tenantnãoGrava em ProcessInstance.tenantId. Ver Segurança e Multi-tenancy — não há validação de que o IdentityContext da requisição tenha direito a esse tenant.
businessKeynãoIdentificador de negócio livre (ex.: número de pedido), não único imposto pelo motor.
businessValuenãoBigDecimal livre para a aplicação anexar um valor monetário/numérico à instância (ex.: para dashboards).
originnãoString livre para rastrear de onde veio o start (nome do sistema chamador).
variablesnãoVer formato de variáveis.

Resposta 201 Created — a ProcessInstance recém-criada, já avançada de forma síncrona até o primeiro ponto de espera (EXTERNAL_TASK, boundary timer, etc.) ou até concluir, caso o processo não tenha nenhum nó assíncrono (ver Execução Síncrona/Assíncrona).

Se o nó de início declara inputs no contrato de dados, as variables enviadas são validadas antes de qualquer execução: faltando um campo obrigatório ou com valor fora do formato, a resposta é 422 (VARIABLE_VALIDATION_FAILED, com um erro por campo — ver Convenções, Autenticação e Erros) e nenhuma instância é criada. Para descobrir quais campos enviar, use o formulário de início.

Buscar uma instância por id​

GET /process-instances/{id}

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

Listar instâncias​

GET /process-instances?ids=id-1&ids=id-2
GET /process-instances?process-definition-id={id}&tenant-id={tenant}

Este endpoint só aceita duas combinações de filtro — qualquer outra combinação (inclusive nenhum parâmetro) lança NotImplementedException → 501:

  1. ids (uma ou mais ocorrências) — busca exatamente aquelas instâncias, ignorando os demais parâmetros.
  2. process-definition-id e tenant-id juntos — não funciona informar só um dos dois.

Para qualquer outro filtro (status, chave de negócio, intervalo de datas, variáveis...), use POST /process-instances/search — muito mais completo e o caminho recomendado; este GET existe para os dois casos de acesso direto acima.

Resposta 200 OK — ProcessInstance[], não paginado.

Contar instâncias​

GET /process-instances/count?process-definition-id={id}

Único filtro suportado hoje — omitir process-definition-id lança NotImplementedException → 501, não devolve uma contagem total. Conta todas as instâncias daquela definição (ACTIVE, COMPLETED e CANCELLED — não só as ativas; para "quantas estão rodando agora" use /pulse/process-definition/{id}/snapshot).

Resposta 200 OK:

{ "total": 1284 }

Atualizar variáveis​

PUT /process-instances/{id}/variables
Content-Type: application/json

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

Mescla (upsert por nome) sobre as variáveis existentes — não substitui o mapa inteiro; variáveis não citadas permanecem intocadas. Resposta 200 OK com a ProcessInstance atualizada.

Remover variáveis​

PUT /process-instances/{id}/variables/unset
Content-Type: application/json

{ "variableNames": ["statusCredito", "scoreTemporario"] }

Remove as variáveis citadas por nome. Resposta 200 OK com a ProcessInstance atualizada.

Encerrar/remover uma instância​

PUT /process-instances/{id}

Sem corpo. Resposta 204 No Content.

:::warning Nome de operação enganoso e delete físico Apesar do verbo PUT e de não haver corpo, esta operação apaga a instância (e suas ExternalTask/ ExecutableTask associadas) — não é um "encerrar suavemente" nem um soft-delete reversível. Trate como destrutivo: não há confirmação, e não há checagem de tenant/identidade antes de apagar (o IdentityContext recebido não é usado para autorização nesta operação hoje). Eventos de histórico já emitidos para a instância (GET /process-instances/{id}/events) não são apagados — permanecem como rastro de auditoria mesmo depois da instância sumir; incidentes associados também não são removidos, e passam a apontar para um processInstanceId inexistente. :::

Incidentes de uma instância​

GET /process-instances/{id}/incidents

200 OK — Incident[] não paginado (tipicamente poucos por instância). Ver Incidentes para o modelo completo e como retentar.

Snapshot completo​

GET /process-instances/{id}/snapshot

Agrega, numa única chamada concorrente (ExecutorService de threads virtuais), tudo que uma tela de detalhe de instância normalmente precisaria buscar separadamente:

{
  "instance": { "...": "ProcessInstance completa" },
  "executableTasks": [ "..." ],
  "externalTasks": [ "..." ],
  "incidents": [ "..." ],
  "eventCatcherWaitStatus": [ "..." ]
}

404 (NOT_FOUND) se a instância não existir — as demais listas do snapshot vêm vazias em vez de erro se não houver dados (não é tratado como "instância inexistente", já que tarefas/incidentes zerados são um estado normal).

Progresso de um EVENT_CATCHER: eventCatcherWaitStatus​

eventCatcherWaitStatus é computado (não persistido) a cada chamada, a partir das externalTasks do próprio snapshot — um item por EVENT_CATCHER ativo na instância (GROUP ou STANDALONE):

CampoSignificado
taskDefinitionIdid do nó EVENT_CATCHER na definição
externalTaskIdid da tarefa coordenadora (GROUP) ou da própria tarefa (STANDALONE)
matchPolicyALL (só conclui com todas as chaves), ANY (primeira chave vence), ou null para STANDALONE
totalCorrelationKeysquantas chaves esse nó espera ao todo
receivedCountquantas já chegaram
pendingCorrelationKeysquais ainda faltam — útil para depurar "por que essa instância não anda?"

Com isso dá para mostrar "3 de 5 eventos recebidos" e listar as chaves pendentes. Um EVENT_CATCHER STANDALONE sempre aparece com totalCorrelationKeys: 1 e receivedCount: 0 — ele só existe na lista enquanto está esperando; quando a chave chega, a tarefa é removida.

Em matchPolicy: ANY, receivedCount não sobe gradualmente: a primeira chave recebida já conclui o nó inteiro, então ele sai de 0 direto para o nó desaparecer de activeNodes (a instância avançou).

GET /process-instances/summary (deprecated)​

Paginado, com três filtros fixos (processDefinitionId, activeNodeId, tenantId) e sem os demais filtros de /search. Mantido só por compatibilidade com integrações antigas — não use em código novo; veja Busca Avançada de Instâncias para o substituto completo.