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}	—
Formulário de início	GET /process-definitions/one-by-key/{process-definition-key}/start-form	—
Limpar cache de definições	DELETE /process-definitions/cache	—

Os 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": "abertura-de-conta",
  "name": "Abertura de Conta Digital",
  "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, catálogo de variáveis malformado, etc. — ver Regras de Processo Válido) retorna 400 com code: INVALID_PROCESS_DEFINITION e, em message, a regra violada e o nó.

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=abertura-de-conta

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). Para montar "uma linha por processo" a partir da lista completa, agrupe por key no cliente e fique com a primeira ocorrência de cada uma — por causa da ordenação, ela já é a versão mais alta:

const allVersions = await fetch('/process-definitions').then(r => r.json());
const latestByKey = new Map();
for (const def of allVersions) {
  if (!latestByKey.has(def.key)) latestByKey.set(def.key, def); // 1ª ocorrência = versão mais alta
}

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.

Formulário de início

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

Descreve os campos exigidos para iniciar uma instância da versão mais recente daquela key — um FormDescriptor montado a partir dos inputs do nó de início e do catálogo variableDeclarations (ver Catálogo de Variáveis e Formulários):

{
  "processDefinitionId": "fc451f6f-a944-4dbb-b2ba-b5fb6433f40a",
  "processDefinitionKey": "abertura-de-conta",
  "nodeId": "INICIO",
  "nodeName": null,
  "fields": [
    { "key": "cpf", "label": "CPF", "description": null, "format": "SHORT_TEXT", "required": true,
      "options": [], "currency": null, "validationRegex": "\\d{11}",
      "validationMessage": "Informe o CPF com 11 dígitos, sem pontuação.", "extensionProperties": null,
      "value": null },
    { "key": "rendaDeclarada", "label": "Renda mensal declarada", "description": null, "format": "MONEY",
      "required": true, "options": [], "currency": "BRL", "validationRegex": null, "validationMessage": null,
      "extensionProperties": null, "value": null }
  ]
}

Os campos vêm na ordem dos inputs; value é sempre null (ainda não existe instância). Um processo sem inputs no início devolve fields vazio. 404 (NOT_FOUND) se a key nunca foi implantada. O endpoint não recebe a identidade de quem chama: qualquer chamador que alcance a API consegue ler o formulário.

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. Início, EXTERNAL_TASK e EXECUTABLE_TASK podem trazer variableBindings.
variableDeclarations	array	Catálogo de variáveis do processo — ver Catálogo de Variáveis e Formulários. Vazio quando o processo não declara catálogo.
extensionProperties	object	Mapa string→string livre para metadados da aplicação.