Definições de Processo

Uma ProcessDefinition é o JSON versionado que descreve um processo (ver Anatomia de um Processo). Estes endpoints implantam e consultam essas definições — não confundir com Instâncias de Processo, que são execuções concretas de uma definição.

Operação	Endpoint	Autenticação/condição
Implantar uma definição	POST /process-definitions	requer kikwiflow.security.deploy-enabled: true
Listar definições	GET /process-definitions	—
Buscar a versão mais recente por key	GET /process-definitions/one-by-key/{process-definition-key}	—
Buscar uma versão exata por id	GET /process-definitions/{id}	—
Limpar cache de definições	DELETE /process-definitions/cache	—

Os quatro GET/DELETE requerem um QueryRepository no contexto (ver Visão Geral); em POST /process-definitions basta o KikwiflowEngine.

Implantar uma definição

POST /process-definitions
Content-Type: application/json

Corpo — o mesmo JSON de processo descrito em Anatomia de um Processo, sem os campos que só existem depois de implantado (id, version, checksum):

{
  "key": "onboarding-cliente",
  "name": "Onboarding de Cliente",
  "description": "",
  "sla": "",
  "defaultStartPoint": "INICIO",
  "flowNodes": {
    "INICIO": { "id": "INICIO", "type": "DEFAULT_START_EVENT", "outgoing": [{ "targetNodeId": "FIM" }] },
    "FIM": { "id": "FIM", "type": "DEFAULT_END_EVENT", "outgoing": [] }
  },
  "extensionProperties": {}
}

Resposta 201 Created — a ProcessDefinition persistida, com id, version e checksum preenchidos. Reimplantar o mesmo key cria uma nova versão; instâncias já em execução continuam na versão com a qual começaram (ver a mesma referência acima).

:::warning Desabilitado por padrão kikwiflow.security.deploy-enabled é false por padrão — chamar este endpoint sem habilitá-lo lança SecurityException, que não tem handler dedicado e portanto retorna 500 (não 403) com o corpo de erro padrão do servlet container, não o envelope {code, message} dos demais erros. Ver Convenções, Autenticação e Erros e Segurança e Multi-tenancy para o quadro completo, inclusive como restringir por role em vez de ligar/desligar globalmente.

Uma definição inválida (gateway sem providerType, referência a AnswerProvider/bean inexistente, etc. — ver Regras de Processo Válido) também cai fora do envelope de erro padrão: InvalidProcessDefinitionException não tem handler dedicado e vira 500. :::

Muitas aplicações preferem nunca ligar deploy-enabled e implantar exclusivamente via auto-deploy do classpath num pipeline de CI/CD — este endpoint existe para os casos que precisam de deploy dinâmico em runtime (multi-tenant com processos por cliente, ferramentas de autoria).

Listar definições

GET /process-definitions
GET /process-definitions?key=onboarding-cliente

Sem key: devolve todas as versões de todas as definições, ordenadas por version decrescente — não é deduplicado por processo. Com key: mesma ordenação, filtrado às versões daquela key (também não deduplica — se você quer só a versão mais recente de uma key específica, use o próximo endpoint). Ver Guia de Integração do Monitor §1 para a técnica de deduplicar no cliente quando precisar de "um card por processo".

Resposta 200 OK — ProcessDefinition[], possivelmente vazio.

Buscar a versão mais recente por key

GET /process-definitions/one-by-key/{process-definition-key}

Sempre a versão de maior version para aquela key — uma chamada por chave, sem precisar deduplicar nada no cliente. 404 (NOT_FOUND) se a key nunca foi implantada.

Buscar uma versão exata por id

GET /process-definitions/{id}

id aqui é o identificador de uma versão específica, não da key — duas versões da mesma definição têm ids diferentes. 404 (NOT_FOUND) se não existir.

Limpar cache de definições

DELETE /process-definitions/cache

Resposta 204 No Content. Força a próxima resolução de definição (por key, no início de uma nova instância) a ir ao repositório em vez do cache em memória do parser. Use depois de editar uma definição diretamente no banco (fora do fluxo normal de deploy) ou ao depurar uma versão que parece "não atualizar".

Modelo de resposta (ProcessDefinition)

Campo	Tipo	Observação
id	string	Identificador da versão (não da key).
key	string	Identificador estável do processo entre versões.
version	int	Incrementa a cada POST /process-definitions com o mesmo key.
name, description, sla	string	Metadados livres.
checksum	string	Hash do conteúdo — usado internamente para detectar definições idênticas re-enviadas.
defaultStartPoint	string	id do nó de entrada.
flowNodes	object	Mapa nodeId → definição do nó — ver Anatomia de um Processo.
extensionProperties	object	Mapa string→string livre para metadados da aplicação.