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. Numa abertura de conta, a pasta chega com cpf e rendaDeclarada; a etapa de score lê as duas folhas e acrescenta score; a aprovação lê score e acrescenta decisao. Cada etapa lê o que precisa e não sabe nada sobre como aquilo chegou ali. A analogia para de funcionar na cópia: uma folha de papel só está em uma mesa por vez, mas ramos paralelos de um processo leem as mesmas variáveis ao mesmo tempo.

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 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

Um processo costuma nascer com dados — uma solicitação de abertura de conta chega com cpf e rendaDeclarada, e é com esse payload que a instância é iniciada. Em código, é withVariables:

kikwiflowEngine.startProcess()
        .byKey("abertura-de-conta")
        .withBusinessKey("11111111111")
        .withVariables(Map.of(
                "cpf", new ProcessVariable("cpf", "11111111111"),
                "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). É assim que a decisao de um analista entra na instância.

• A qualquer momento — KikwiflowEngine.setVariables/unsetVariables, ou via API REST com PUT /process-instances/{id}/variables. É o caminho para corrigir um dado manualmente antes de retentar um incidente. Detalhes em Operando via API REST e na referência de instâncias.

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.

Exigindo e validando variáveis

Por padrão, nada obriga uma variável a existir nem a ter um formato. Quando os dados vêm de pessoas ou de sistemas que você não controla, declare um catálogo de variáveis no .kikwi e diga, em cada etapa, quais são obrigatórias: o motor passa a recusar o início ou a conclusão com dado faltando ou malformado, e a API descreve os campos de cada etapa para o seu frontend montar o formulário. Veja Catálogo de Variáveis e Formulários.

Próximo passo

Para garantir que os handlers que leem e escrevem essas variáveis se comportam como esperado, veja Testando Seus Handlers.