Anatomia de um Processo

Um processo Kikwiflow é um único arquivo JSON. Este documento descreve seus campos de topo, o catálogo de tipos de nó disponíveis, e os campos de uma conexão (sequence flow) entre nós.

Pense na planta baixa de uma casa

A definição JSON de um processo é a planta baixa: ela descreve os cômodos (nós) e as portas que os conectam (sequence flows), mas não decide sozinha o que acontece dentro de cada cômodo. O que acontece dentro é papel do TaskHandler que ocupa aquele nó — a planta só garante que, saindo de um cômodo, você sabe exatamente para qual porta ir em seguida. A analogia para de funcionar quando o cômodo decide sozinho para onde a próxima porta leva — é exatamente isso que um gateway faz, e nenhuma planta baixa real toma essa decisão em tempo real.

Campos de topo

Um processo de abertura de conta, como o Craft o exporta, ilustra os campos de topo:

{
  "key": "abertura-de-conta",
  "name": "Abertura de Conta Digital",
  "description": "",
  "extensionProperties": {},
  "flowNodes": { "...": "..." },
  "defaultStartPoint": "INICIO"
}

Campo	Papel
key	Identificador estável do processo, usado por KikwiflowEngine.startProcess().byKey(...). Reimplantar o mesmo key atualiza a definição para novas instâncias; instâncias já em execução continuam na versão com a qual começaram.
name	Nome legível, para exibição em ferramentas de modelagem e operação.
flowNodes	Mapa de id do nó → definição do nó. Cada nó é indexado pelo próprio id — não por posição em uma lista.
defaultStartPoint	O id do nó por onde toda nova instância começa. Obrigatório — a inicialização falha se apontar para um nó inexistente.
extensionProperties	Mapa livre de string→string, para metadados que sua aplicação queira anexar ao processo (ex.: limiares de SLA) sem que o motor precise entender o significado.
variableDeclarations	Opcional. Catálogo das variáveis do processo, com formato e validação — ver Catálogo de Variáveis e Formulários.

Catálogo de tipos de nó

type	Papel
DEFAULT_START_EVENT	Ponto de entrada de uma instância. Toda definição precisa de pelo menos um, referenciado por defaultStartPoint.
DEFAULT_END_EVENT	Fim de um ramo de execução. outgoing vazio.
EXECUTABLE_TASK	Executa lógica de negócio síncrona, via TaskHandler. Ver Tarefas Executáveis.
EXTERNAL_TASK	Espera a conclusão de algo fora do controle direto do motor (humano, sistema externo). Ver Tarefas Externas e Workers.
EXCLUSIVE_GATEWAY	Roteia para exatamente um dos ramos de saída, com base em uma decisão. Ver Decisões e Gateways.
PARALLEL_GATEWAY / JOIN_GATEWAY	Fan-out (segue todos os ramos de saída simultaneamente) e fan-in (espera todos os ramos pendentes antes de prosseguir). Ver Processamento Paralelo.
BOUNDARY_INTERRUPTIVE_TIMER / BOUNDARY_NON_INTERRUPTIVE_TIMER	Timers de borda anexados a uma tarefa. Ver Timers e Prazos.
BOUNDARY_ERROR_HANDLER	Captura um erro de negócio lançado pelo nó ao qual está anexado. Ver Tratando Erros de Negócio.
EVENT_CATCHER / EVENT_THROWER	Espera por um ou mais eventos identificados por chave de correlação / dispara um evento para quem estiver esperando. Ver Event Catcher e Event Thrower.
BOUNDARY_INTERRUPTIVE_CATCH_EVENT	Evento de borda que cancela a espera do nó pai quando uma chave de correlação chega. Ver Boundary Catch Event.
TIMER_TASK	Pausa o caminho principal até um prazo. Ver Timer Task.
CALL_ACTIVITY_COORDINATOR	Inicia um ou mais subprocessos e espera por eles. Ver Subprocessos (Call Activity).

Os campos de cada tipo e onde cada evento de borda pode ser anexado estão em Referência de Nós e Linter.

Conexões (sequence flows)

Cada nó declara sua lista outgoing de conexões para os próximos nós:

{
  "id": "flow-1",
  "name": "",
  "targetNodeId": "PROXIMO_NO",
  "transitionType": "automated",
  "isDefault": false,
  "extensionProperties": {}
}

Campo	Papel
targetNodeId	O id do próximo nó — precisa existir em flowNodes.
isDefault	Só é relevante em gateways de decisão: marca a aresta a seguir quando nenhuma outra condição casar. No máximo uma aresta isDefault: true por gateway.
expectedAnswer	Só é relevante em EXCLUSIVE_GATEWAY: a aresta é seguida quando a decisão resolvida for igual a este valor (comparação exata de string).
handlesNull	Só é relevante em EXCLUSIVE_GATEWAY: a aresta é seguida quando a decisão resolvida for null.

Detalhes de roteamento e do casamento de expectedAnswer/isDefault/handlesNull estão em Decisões e Gateways.

commitBefore e commitAfter: o que significam para você

Todo nó pode declarar commitBefore/commitAfter (booleanos, default false). Na prática, para quem desenha o processo, isso responde a uma pergunta simples: este nó precisa sobreviver a uma reinicialização da aplicação antes ou depois de executar?

• commitBefore: true — o motor persiste o estado da instância antes de executar aquele nó, e a execução daquele ponto em diante passa a ser assíncrona (processada por um worker interno em segundo plano, não na mesma chamada que iniciou o processo). Use isso em nós que podem demorar, falhar e precisar de retry, ou que começam um ramo paralelo.
• Sem commitBefore em nenhum nó do caminho, o processo inteiro roda de forma síncrona, dentro da mesma chamada Java que o iniciou — até chegar a uma espera. Uma EXTERNAL_TASK sempre interrompe a execução: uma espera nunca é síncrona, por definição (ninguém bloqueia uma thread esperando um analista de crédito bater o martelo).

Isso é o suficiente para decidir quando usar commitBefore ao modelar um processo. O mecanismo interno completo (filas de trabalho, UnitOfWork, quando o motor decide cruzar essa fronteira sozinho — como em PARALLEL_GATEWAY, que sempre é assíncrono) está documentado em Execução Síncrona e Assíncrona, para quem quiser entender o motor por dentro.

Próximo passo

A etapa que faz o trabalho de verdade quando o fluxo não está esperando ninguém é a tarefa executável — o ponto onde o seu código Java entra no processo.