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

O processo de abertura de conta do tutorial, como o Craft o exporta, ilustra os campos de topo:

{
  "key": "abertura-de-conta",
  "name": "Abertura de Conta Digital",
  "description": "",
  "extensionProperties": {},
  "flowNodes": { "...": "..." },
  "defaultStartPoint": "43ee89f9-17c8-4d93-84dc-bae52ed7054d"
}

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 operação/observabilidade — é o que aparece no Craft e no Monitor.
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.

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.

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 — como o processo de abertura de conta do tutorial, que só cruza uma fronteira assíncrona ao esperar a EXTERNAL_TASK (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

Com a forma do processo entendida, o próximo passo é a etapa que faz o trabalho de verdade quando o fluxo não está esperando ninguém: Tarefas Executáveis.