Pular para o conteúdo principal

Início Rápido

Em menos de 15 minutos você vai modelar um processo no Craft, gerar o projeto Spring Boot, implementar um handler e ver a primeira instância rodar no Monitor. O problema que ele resolve:

Uma fintech abre contas digitais. Hoje a análise de cada solicitação é manual e sem visibilidade: um formulário chega pelo site, alguém calcula um score de risco numa planilha, um analista de crédito olha o resultado e decide aprovar ou não — e não existe um lugar único onde se veja em que etapa cada solicitação está. Solicitações somem no meio do caminho. Ninguém sabe quantas. Ninguém sabe onde.

Você constrói primeiro a versão mínima, que já tira a análise da planilha. A partir daí, cada capítulo do Guia do Desenvolvedor pega este mesmo processo e adiciona uma peça — score baixo, analista que demora, cadastro inválido — até virar um sistema de abertura de conta observável de ponta a ponta.

Se ainda não sabe o que é o Kikwiflow nem por que usá-lo, comece por Kikwiflow. Termos em inglês (workflow, bean, worker, handler) são glosados na primeira aparição e estão reunidos no Glossário.

Pré-requisitos​

O Initializr do Craft gera um projeto Spring Boot completo, com docker-compose.yml. Há dois caminhos para rodá-lo — escolha um:

  • Docker + IDE (recomendado) — Docker e Docker Compose instalados, e uma IDE. É o caminho mais objetivo e rápido: você não instala Java, Maven nem MongoDB na máquina. Recomendamos o VS Code, por causa da extensão Kikwiflow Craft para VS Code, que abre o .kikwi como diagrama (não como JSON cru) dentro do editor e tem o botão "Ir para o bean".
  • JDK + Maven + MongoDB — JDK 21+, Maven 3.9+, e um MongoDB acessível (o docker-compose do projeto usa mongo:7). Use este caminho se preferir não depender do Docker para rodar a aplicação.

O tutorial mostra os comandos nos dois caminhos onde eles diferem.

1. Modelar no Craft​

Acesse o Kikwiflow Craft e crie um novo rascunho. Arraste da paleta, nessa ordem: um Start Event, uma Executable Task, uma External Task, e um End Event — conectando cada um ao seguinte (veja Construindo o fluxo no canvas se for a primeira vez que você abre o editor).

Configure os dois nós do meio:

  • Calcular Score (Executable Task) → campo Executor: calcularScoreTaskHandler.
  • Aprovar Abertura (External Task).
craft.kikwiflow.io
Processo abertura-de-conta no canvas do Craft: Início → Calcular Score (calcularScoreTaskHandler) → Aprovar Abertura → Fim.
O fluxo no canvas do Craft: início, a tarefa executável Calcular Score, a tarefa externa Aprovar Abertura e o fim.

Abra Configurações do Processo e defina a Chave do Processo (ID) como abertura-de-conta — é esse identificador, não o nome do arquivo, que o seu código vai usar para iniciar instâncias.

craft.kikwiflow.io
Painel Configurações do Processo no Craft, com a Chave do Processo (ID) definida como abertura-de-conta.
Em Configurações do Processo, a Chave do Processo (ID) é o identificador que o seu código usa para iniciar instâncias.

Entendendo o processo​

  • Calcular Score é uma tarefa executável (EXECUTABLE_TASK), ou seja, é uma tarefa que vai ser executada pela aplicação, pode ser um algoritimo que por exemplo lê cpf e rendaDeclarada e grava um score, sem intervenção humana.

  • Aprovar Abertura é uma tarefa externa (EXTERNAL_TASK), ou seja, o processo pausa até que o analista de crédito revise o score e registre a decisao.

Este diagrama ao ser exportado vai gerar um arquivo '.kikwi', que nada mais é do que um grafo em JSON que vai servir de mapa para que o motor de execução entenda o que deve fazer e quando deve fazer.

Ver o .kikwi exportado (JSON)
{
  "key": "novo-processo",
  "name": "Novo Processo",
  "version": 1,
  "description": "",
  "extensionProperties": {},
  "flowNodes": {
    "e34061ff-fac4-46c2-ba55-96d1d86d8689": {
      "id": "e34061ff-fac4-46c2-ba55-96d1d86d8689",
      "name": "Início",
      "type": "DEFAULT_START_EVENT",
      "commitBefore": false,
      "commitAfter": false,
      "outgoing": [
        {
          "id": "flow-207bf0b9-e03c-4ffe-a1de-ed629b6883fe",
          "name": "",
          "targetNodeId": "EXECUTABLE_4F492EA7",
          "extensionProperties": {}
        }
      ],
      "layout": {
        "x": 448,
        "y": 360
      },
      "extensionProperties": {}
    },
    "EXECUTABLE_4F492EA7": {
      "id": "EXECUTABLE_4F492EA7",
      "name": "Calcular Score",
      "type": "EXECUTABLE_TASK",
      "executor": "calcularScoreTaskHandler",
      "commitBefore": false,
      "commitAfter": false,
      "outgoing": [
        {
          "id": "flow-4fa741f3-c956-4178-a72f-83ac0c0a4d0e",
          "name": "",
          "targetNodeId": "EXTERNAL_F6659E57",
          "extensionProperties": {}
        }
      ],
      "layout": {
        "x": 512,
        "y": 346
      },
      "extensionProperties": {}
    },
    "EXTERNAL_F6659E57": {
      "id": "EXTERNAL_F6659E57",
      "name": "Aprovar Abertura",
      "type": "EXTERNAL_TASK",
      "commitBefore": false,
      "commitAfter": false,
      "outgoing": [
        {
          "id": "flow-9b5662ae-61c2-4005-a94d-03813f18fe88",
          "name": "",
          "targetNodeId": "DEFAULT_555BEF2F",
          "extensionProperties": {}
        }
      ],
      "layout": {
        "x": 834,
        "y": 346
      },
      "extensionProperties": {}
    },
    "DEFAULT_555BEF2F": {
      "id": "DEFAULT_555BEF2F",
      "name": "Fim",
      "type": "DEFAULT_END_EVENT",
      "commitBefore": false,
      "commitAfter": false,
      "outgoing": [],
      "layout": {
        "x": 1164,
        "y": 360
      },
      "extensionProperties": {}
    }
  },
  "defaultStartPoint": "e34061ff-fac4-46c2-ba55-96d1d86d8689"
}

Você não precisa ler isso como JSON. A extensão Kikwiflow Craft para VS Code abre qualquer .kikwi como o mesmo diagrama que você desenhou no Craft — e daí você pula do nó direto para o bean que o implementa.

IDs gerados pelo Craft

O Craft identifica nós por UUID internamente (43ee89f9-...), não por nomes legíveis. Mas você pode editar o identificador destes nós para uma melhor legibilidade humana em logs e ferramentas de observabilidade.

2. Gerar o projeto com o Initializr​

Com o fluxo pronto, abra o Hub de Exportação (botão Export na barra do canvas) e escolha o modo Initializr. Preencha o modal:

CampoValor
groupIdcom.empresa
artifactIdconta-service
nameconta-service
packageNamecom.empresa.processo
Java21
Versão do Kikwideixe o padrão

Clique em gerar. Toda a geração acontece no navegador — baixa um conta-service.zip. Descompacte em algum lugar do seu workspace.

craft.kikwiflow.io
Modal do Initializr no Hub de Exportação do Craft, com groupId, artifactId, packageName, versão do Java e versão do Kikwi preenchidos.
O modal do Initializr no Hub de Exportação, com os campos do projeto conta-service preenchidos.

Alternativa sem gerar o projeto inteiro: exporte só o .kikwi (modo JSON do Hub) para src/main/resources/processes/ de um projeto que você já tem; os stubs de bean você cria a partir do próprio nó, pelo botão "Ir para o bean" da extensão do VS Code.

3. O projeto gerado​

Descompactado, o conta-service tem esta forma:

conta-service/
  pom.xml                 # Java 21, os starters do Kikwiflow (motor, MongoDB, query, REST, Monitor)
  Dockerfile              # build multi-stage (Maven → JRE 21), expõe 8081
  docker-compose.yml      # a aplicação (porta 8081) + um MongoDB (mongo:7)
  .dockerignore
  README.md               # abra este primeiro — cobre os caminhos Docker e Maven
  src/main/resources/
    application.yml        # config do projeto (abaixo)
    processes/
      abertura-de-conta.kikwi   # ← o processo que você desenhou, já embutido
  src/main/java/com/empresa/processo/
    ContaServiceApplication.java
    executors/
      CalcularScoreTaskHandler.java   # ← stub gerado a partir do executor; corpo // TODO

O .kikwi do passo 1 já vem em src/main/resources/processes/, e cada executor referenciado no processo já tem uma classe stub em executors/ — anotada com @Component("<nome>"), implementando a interface certa, com o corpo do método marcado como // TODO.

O que o Initializr adiciona ao pom.xml
DependênciaPapelDocumentação
spring-boot-starter / spring-boot-starter-webContexto Spring + o Tomcat que serve a API REST e os assets estáticos do Monitor.docs do Spring Boot
kikwi-spring-boot-starterO motor em si + a auto-configuração Spring Boot (execução, navegação, retry, timers). Traz kikwi-core, kikwi-model e o parser Jackson transitivamente — você não os declara.Motor de Execução
kikwi-runtime-persistence-mongodb-spring-boot-starterPersistência do estado de cada instância em MongoDB, com commitWork transacional. Alternativa para começar sem infra: kikwi-in-memory-spring-boot-starter (nada sobrevive a um restart) — ver Instalação e Setup.Persistência e Consistência
kikwi-runtime-query-spring-boot-starterO lado de leitura: busca de instâncias e histórico de eventos que a API de gestão consulta.Busca Avançada de Instâncias
kikwi-management-rest-spring-boot-starterA API REST + SSE de gestão: definições, instâncias, completar tarefas externas, retry de incidentes, correlação de eventos.Referência da API REST
kikwi-monitor-spring-boot-starterEmbute a interface do Kikwiflow Monitor no próprio processo da aplicação, em /monitor-ui/. Depende do starter de management REST.Kikwiflow Monitor

O application.yml que vem no projeto:

server:
  port: ${SERVER_PORT:8081}
spring:
  application:
    name: conta-service
  threads:
    virtual:
      enabled: true
  data:
    mongodb:
      uri: ${MONGODB_URI:mongodb://localhost:27017}
      database: conta_service_db
      auto-index-creation: true
kikwiflow:
  process-definition:
    auto-deploy:
      enabled: true                         # registra todo .kikwi em resources/processes/ na subida
      path: "classpath*:processes/**/*.kikwi"
  security:
    deploy-enabled: true                    # sem isto, nenhum processo é implantado
  execution:
    task-acquisition-interval-millis: 1000  # … demais chaves de tuning: ver Configuração Essencial
  retry:
    default-retry-interval: PT1M
  pulse:
    sse-endpoints:
      enabled: true

4. Implementar o TaskHandler​

O executor: "calcularScoreTaskHandler" declarado em Calcular Score precisa de um bean Spring com esse nome — o Initializr já gerou a classe vazia. Abra src/main/java/com/empresa/processo/executors/CalcularScoreTaskHandler.java e preencha o corpo:

package com.empresa.processo.executors;

import io.kikwiflow.execution.api.context.ExecutionContext;
import io.kikwiflow.execution.api.handler.TaskHandler;
import io.kikwiflow.model.execution.ProcessVariable;
import org.springframework.stereotype.Component;

import java.math.BigDecimal;

@Component("calcularScoreTaskHandler")
public class CalcularScoreTaskHandler implements TaskHandler {

    @Override
    public void handle(ExecutionContext execution) {
        String cpf = execution.getVariable("cpf").value().toString();
        BigDecimal rendaDeclarada = new BigDecimal(
                execution.getVariable("rendaDeclarada").value().toString());

        int score = calcular(cpf, rendaDeclarada);

        execution.setVariable("score", new ProcessVariable("score", score));
    }

    private int calcular(String cpf, BigDecimal rendaDeclarada) {
        // Regra de exemplo, determinística: quanto maior a renda, maior o score (teto 1000).
        int base = rendaDeclarada.divide(BigDecimal.TEN).intValue();
        return Math.min(base, 1000);
    }
}

O nome passado a @Component("...") precisa bater exatamente com executor no JSON — é assim que o motor resolve qual bean invocar quando o fluxo alcança aquele nó (detalhes em Tarefas Executáveis).

5. Subir e executar​

Da raiz do conta-service:

docker compose up --build

Sobe o MongoDB (mongo:7) e a aplicação num passo só — não precisa de Java, Maven ou Mongo instalados localmente.

Nos dois casos, no log de inicialização você vê o processo ser implantado:

 ✓ Processo implantado: abertura-de-conta (v1)

A aplicação responde em http://localhost:8081, e o Monitor embarcado em http://localhost:8081/monitor-ui/.

6. Operar no Monitor​

Acesse http://localhost:8081/monitor-ui/. O processo abertura-de-conta aparece na lista, ainda sem nenhuma execução.

Iniciar uma instância — abra o processo e clique no botão de play na barra flutuante superior. No formulário, deixe a chave de negócio (business key) em branco — o Monitor gera uma — e informe o conjunto inicial de variáveis (o payload): os dados que a solicitação "traz do site":

VariávelTipoValor
cpfString111.111.111-11
rendaDeclaradaNumber8000

Ao confirmar, a instância nasce, Calcular Score roda na hora (é síncrona), grava score = 800, e o processo para em Aprovar Abertura — uma EXTERNAL_TASK não avança sozinha, ela espera. É exatamente esse estado de espera, visível e nomeado, que substitui o "ninguém sabe onde cada solicitação está" do problema original.

localhost:8081/monitor-ui/
Monitor mostrando uma instância de abertura-de-conta parada em Aprovar Abertura, com a variável score já preenchida no painel de contexto.
A instância parada em Aprovar Abertura no Monitor — o estado de espera visível e nomeado que substitui o “ninguém sabe onde cada solicitação está”.

Completar a tarefa humana — clique no card de Aprovar Abertura. No mundo real, é aqui que o analista de crédito olha o score e decide. No editor de variáveis do modal, adicione:

VariávelTipoValor
decisaoStringAPROVADA

Clique em Completar e Avançar. O Monitor mostra o fluxo avançando em tempo real: a instância chega ao Fim e conclui — visível, do início ao fim, sem grep em log nenhum.

Para onde ir depois​

Esse processo é deliberadamente pequeno — uma execução, uma espera, sem decisões, sem prazos, sem tratamento de erro. O Guia do Desenvolvedor pega este mesmo processo e faz ele crescer, capítulo a capítulo. Comece por Anatomia de um Processo para entender a forma de um .kikwi, ou pule direto para a pergunta que te trouxe aqui:

PerguntaVeja
"E se o score for baixo — quero mandar para uma mesa de análise?"Decisões e Gateways
"E se o analista não decidir em 48h?"Timers e Prazos
"E se o CPF vier com formato inválido?"Tratando Erros de Negócio
"E se a consulta ao bureau falhar?"Tarefas Executáveis
"Como testo tudo isso sem subir infraestrutura?"Testando Seus Handlers
"Consulta ao bureau e coleta de documentos são independentes — posso rodar em paralelo?"Processamento Paralelo

Para montar o pom.xml à mão ou entender a escolha de persistência, veja Instalação e Setup.