Variáveis de Processo

Variáveis são o estado de uma instância de processo — os dados que TaskHandlers, AnswerProviders e DueDateProviders leem e escrevem ao longo da execução.

Pense em uma pasta que viaja de mesa em mesa

Como um processo administrativo físico, em que uma pasta viaja de mesa em mesa e cada pessoa lê o que já foi preenchido e acrescenta uma folha nova. Na abertura de conta, a pasta chega com cpf e rendaDeclarada; Calcular Score lê as duas folhas e acrescenta score; Aprovar Abertura lê score e acrescenta decisao. Cada etapa lê o que precisa e não sabe nada sobre como aquilo chegou ali.

O tipo ProcessVariable

public record ProcessVariable(String name, Set<String> readRoles, Set<String> writeRoles,
                               boolean isTransient, Object value) {
    public ProcessVariable(String name, Object value) {
        this(name, Set.of(), Set.of(), false, value);
    }
}

Na prática, o construtor de dois argumentos é o que você vai usar quase sempre:

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

readRoles/writeRoles existem para restringir leitura/escrita por papel (RBAC em nível de variável), mas hoje só têm efeito se a sua aplicação plugar uma implementação real de VariableSecurityPolicyManager — a implementação padrão do motor é um no-op que não aplica restrição nenhuma. isTransient: true marca uma variável que não deve ser persistida entre etapas (útil para um valor calculado que só o handler atual precisa).

Lendo e escrevendo em um TaskHandler

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

    boolean jaTemScore = execution.hasVariable("score");

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

getVariable retorna o ProcessVariable inteiro (não só o valor) — acesse .value() para o dado em si.

Passando variáveis iniciais ao iniciar um processo

O abertura-de-conta já nasce com dados: a solicitação chega do site com cpf e rendaDeclarada, e é com esse payload que a instância é iniciada. No Monitor, é o formulário do botão de play; em código, é withVariables:

kikwiflowEngine.startProcess()
        .byKey("abertura-de-conta")
        .withBusinessKey("111.111.111-11")
        .withVariables(Map.of(
                "cpf", new ProcessVariable("cpf", "111.111.111-11"),
                "rendaDeclarada", new ProcessVariable("rendaDeclarada", 8000)
        ))
        .execute();

Atualizando variáveis de fora de um TaskHandler

Duas formas, dependendo de quem está atualizando:

• Ao completar uma tarefa externa — variáveis entregues junto da conclusão são mescladas na instância antes do fluxo continuar (ver Tarefas Externas e Workers). É assim que decisao entra na instância quando o analista completa Aprovar Abertura pelo Monitor.

• A qualquer momento, via API REST de gestão — PUT /process-instances/{id}/variables. É o mecanismo por trás do editor de variáveis do Monitor quando alguém corrige um dado manualmente antes de retentar um incidente. Detalhes do endpoint em Operando via API REST.

Operar no Monitor

No detalhe de qualquer instância, o painel Variáveis mostra o contexto atual e permite editá-lo: adicionar, alterar ou marcar uma variável para exclusão, com tipo (String, Number, Boolean ou Object/JSON). É a mesma superfície usada ao iniciar uma instância e ao completar uma tarefa.

Quando usar / quando não usar

Use uma variável de processo para todo dado que uma etapa posterior do fluxo precisa ler — é o único canal de estado entre nós.

Não use a instância como banco de dados: guarde na variável o mínimo que o fluxo precisa para decidir (o score, a decisao), não o registro completo do cliente. O dado de domínio pesado vive no seu banco; a variável carrega a chave e o resultado.

Próximo passo

Com os conceitos de modelagem cobertos, o próximo passo natural é garantir que os handlers que você escreveu se comportam como esperado — veja Testando Seus Handlers.