Operando via API REST

Este capítulo é para quando você precisa operar instâncias de código ou em automação — um sistema parceiro que completa uma tarefa por webhook, um job que dispara instâncias em lote, um pipeline que implanta uma definição. Há dois caminhos: chamar o KikwiflowEngine de dentro da própria aplicação, ou a API REST de gestão, para quem opera de fora.

Via KikwiflowEngine (dentro da própria aplicação)

Quando quem opera a instância é a própria aplicação — um listener de evento assíncrono, um @Scheduled, um controller REST seu — injete KikwiflowEngine e chame direto, sem passar por HTTP:

// iniciar
kikwiflowEngine.startProcess()
        .byKey("abertura-de-conta")
        .withBusinessKey(cpf)
        .withVariables(Map.of(
                "cpf", new ProcessVariable("cpf", cpf),
                "rendaDeclarada", new ProcessVariable("rendaDeclarada", renda)))
        .execute();

// completar uma tarefa externa a partir de um callback de outro sistema
kikwiflowEngine.completeExternalTask(externalTaskId,
        Map.of("decisao", new ProcessVariable("decisao", "APROVADA")),
        IdentityContext.system());

// retentar um incidente aberto
kikwiflowEngine.retryIncident(incidentId, IdentityContext.system());

IdentityContext.system() é um atalho para chamadas internas sem um usuário/tenant real por trás (equivalente a rodar com papel SYSTEM_ADMIN, tenant GLOBAL). Em um endpoint autenticado por usuário, use o IdentityContext real resolvido para aquela requisição. completeExternalTask mescla as variáveis fornecidas e continua a execução de forma síncrona dentro da mesma chamada, até o próximo ponto de commitBefore ou o fim do processo.

Os demais métodos seguem o mesmo padrão: claim/unclaim de tarefas externas, setVariables/ unsetVariables de uma instância, deleteInstance e correlateMessage (entrega de um evento por chave de correlação — ver Event Catcher e Event Thrower).

Via API REST (de fora da aplicação)

Com kikwi-management-rest-spring-boot-starter no classpath, a mesma superfície fica exposta via HTTP, sob kikwiflow.rest.base-path (padrão /kikwiflow/api/v1):

Recurso	O que dá para fazer	Referência
Definições de processo	implantar, buscar por id/key, listar, limpar cache	Definições de Processo
Instâncias	iniciar, consultar, snapshot, variáveis, encerrar	Instâncias de Processo
Busca de instâncias	filtros por definição, chave de negócio, tenant, status, variáveis, datas	Busca Avançada
Tarefas externas	claim, unclaim, complete, consultar	Tarefas Externas
Incidentes	consultar, retentar	Incidentes
Correlação de eventos	entregar um evento por chave (webhooks)	Correlação de Eventos
Histórico e estatísticas	timeline de uma instância; snapshot agregado e stream SSE por definição	Histórico, Estatísticas (Pulse)

Antes de expor a API, leia Convenções, Autenticação e Erros — ela cobre como a API resolve identidade e tenant e os casos de erro que ainda não seguem o envelope padrão.

Incidentes

Um incidente é aberto quando uma tarefa esgota suas tentativas de retry, ou quando um erro de negócio não tem BOUNDARY_ERROR_HANDLER correspondente (ver Tratando Erros de Negócio). Retentar reativa a tarefa associada e marca o incidente como resolvido de forma atômica — só incidentes com status OPEN podem ser retentados. Não há operação de retry em lote: para retentar todos os incidentes de uma definição, liste-os e retente um a um.

Próximo passo

A maior parte do comportamento operacional acima é regida por propriedades kikwiflow.* — veja Configuração Essencial para as que você provavelmente vai querer ajustar.