Referência de Configuração

Todas as propriedades abaixo são lidas de application.yml/application.properties via classes @ConfigurationProperties do Spring Boot. Esta página é a fonte única de verdade sobre nomes, defaults e efeitos — construída lendo diretamente as classes de propriedades (KikwiflowProperties, KikwiflowRestProperties, KikwiflowPulseProperties, KikwiflowHistoryProperties, KikwiflowOutboxProperties, MonitorUiProperties), não a documentação de exemplos.

Cada bloco de propriedades só existe se o módulo correspondente estiver no classpath: kikwiflow.* (motor) com kikwi-spring-boot-starter; kikwiflow.rest.* / kikwiflow.pulse.* / kikwiflow.history.* com kikwi-management-rest-spring-boot-starter; kikwiflow.outbox.ttl com kikwi-runtime-persistence-mongodb-spring-boot-starter; kikwiflow.monitor-ui.* com kikwi-monitor-spring-boot-starter.

kikwiflow.* (motor — KikwiflowProperties, módulo kikwi-spring-boot-autoconfigure)

Propriedade	Tipo	Default	Efeito
kikwiflow.stats.enabled	boolean	false	Habilita a coleta em memória de eventos críticos (FLOW_NODE_FINISHED, GATEWAY_ANSWER_RESOLVED) para consumo local. Ver Eventos e Observabilidade.
kikwiflow.outbox.events-enabled	boolean	false	Habilita a persistência de eventos críticos na coleção outbox_events (implementação MongoDB) e a emissão de PROCESS_INSTANCE_FINISHED. Não inclui nenhum consumidor/relay — ver Eventos e Observabilidade.
kikwiflow.outbox.ttl	String (ISO-8601)	não declarado (retenção indefinida)	(binding próprio de kikwi-runtime-persistence-mongodb-spring-boot-autoconfigure, mesma chave kikwiflow.outbox) Cria um índice TTL nativo do MongoDB sobre outbox_events.timestamp (ex.: P30D).
kikwiflow.process-definition.auto-deploy.enabled	boolean	true	Liga o KikwiflowAutoDeployer (ApplicationRunner que varre o classpath no boot). Habilitado por padrão — a v1 community assume que a maioria dos times quer autodeploy pronto para uso; desligue explicitamente se preferir controlar o deploy só via API/pipeline.
kikwiflow.process-definition.auto-deploy.path	String	classpath*:processes/**/*.kikwi	Padrão de localização (Spring ResourcePatternResolver) dos arquivos .kikwi a implantar automaticamente.
kikwiflow.security.deploy-enabled	boolean	false	Interruptor global de deploy — ver aviso abaixo.
kikwiflow.execution.task-acquisition-interval-millis	long	5000	Intervalo entre ciclos de polling do TaskAcquirer.
kikwiflow.execution.task-acquisition-max-tasks	int	10	Máximo de tarefas buscadas por ciclo de polling (também limitado pelos permits disponíveis de max-concurrent-tasks).
kikwiflow.execution.max-concurrent-tasks	int	200	Tamanho do Semaphore que limita tarefas em execução simultânea por instância.
kikwiflow.execution.shutdown-grace-period-seconds	int	20	Tempo de espera por tarefas em voo durante stop() antes de shutdownNow().
kikwiflow.execution.lock-timeout-millis	long	5000	TTL do lock otimista sobre uma ExecutableTask adquirida. Ver nota abaixo.
kikwiflow.retry.default-retry-interval	String (ISO-8601)	PT3M (default do KikwiflowConfig; só é aplicado se a propriedade não for enviada)	Intervalo fixo de retry para nós sem retryPolicy declarada.
kikwiflow.retry.fatal-exceptions	List<String> (FQCN)	[]	Exceções que pulam retry e abrem incidente imediatamente. Ver Retry e Resiliência.

:::tip Resolvido: auto-deploy.path era configuração morta KikwiflowProperties costumava expor autoDeploy solto na raiz (kikwiflow.auto-deploy.*), um prefixo diferente do que KikwiflowAutoConfiguration já checava via @ConditionalOnProperty para ligar/desligar o bean KikwiflowAutoDeployer (kikwiflow.process-definition.auto-deploy.enabled). Na prática, auto-deploy.enabled "funcionava" por coincidência — o @ConditionalOnProperty lê a chave certa direto do Environment, independente do binding do objeto — mas auto-deploy.path não tinha como ser configurado: o valor customizado nunca chegava a KikwiflowAutoDeployer, que sempre recebia o default de fábrica. Agora AutoDeploy vive dentro de uma classe ProcessDefinition, sob o mesmo prefixo kikwiflow.process-definition.auto-deploy.* que o @ConditionalOnProperty sempre usou — as duas tabelas de linhas acima já refletem o caminho correto e funcional. :::

:::danger kikwiflow.security.deploy-enabled é false por padrão — de propósito Diferente do que o campo isProcessDefinitionDeployEnabled em KikwiflowConfig sugere isoladamente (seu valor de fábrica ali é true), KikwiflowAutoConfiguration.kikwiflowConfig() sempre sobrescreve esse valor com properties.getSecurity().isDeployEnabled() — e esse campo em KikwiflowProperties.Security é um boolean primitivo sem valor inicial explícito, ou seja, false por padrão do Spring Boot. Se você não declarar kikwiflow.security.deploy-enabled: true explicitamente no seu application.yml, todo deploy de processo (inclusive via autodeploy, que passa pelo mesmo DeploymentSecurityManager) será rejeitado com SecurityException. O sample-onboarding-process só funciona porque declara esse valor explicitamente. Note que a chave é deploy-enabled (um único campo booleano), não deploy.enabled — não existe nenhum objeto aninhado deploy em KikwiflowProperties.Security, então uma variação com ponto não se liga a nada e falha silenciosamente (o processo continua deployável ou não conforme o default, sem nenhum aviso de propriedade desconhecida). :::

:::tip Resolvido: lock-timeout-millis já teve default de fábrica de 12 milissegundos Até uma versão anterior, o default de KikwiflowProperties.Execution.lockTimeoutMillis era 12 — quase certamente 12 pensado como segundos e nunca corrigido para 12000. Um lock que expira em 12ms é efetivamente inútil como proteção contra dois workers processando a mesma tarefa (qualquer TaskHandler real leva mais que isso para rodar), e divergia do default que o próprio kikwi-core já usa quando este módulo Spring Boot não está no caminho (KikwiflowConfig.lockTimeoutMillis = 5000L). O default de fábrica agora é 5000 (5 segundos) nos dois lugares. Ainda vale declarar kikwiflow.execution.lock-timeout-millis explicitamente em produção — um valor na casa de alguns segundos a poucos minutos, dependendo da duração típica dos seus TaskHandlers — em vez de confiar no default, mas ele deixou de ser uma armadilha silenciosa. :::

spring.application.name também afeta o motor

KikwiflowProperties.instanceName é resolvido via @Value("${spring.application.name:kikwiflow-engine}") — não é uma propriedade kikwiflow.* própria. Esse valor vira o prefixo do workerId usado pelo TaskAcquirer para locking distribuído (<instanceName>-<uuid-curto>) e aparece em logs de diagnóstico. Em ambientes com múltiplas instâncias do mesmo serviço, isso não precisa ser único por instância — a parte do UUID já garante unicidade — mas ajuda a identificar de qual serviço um worker pertence em um ambiente com vários serviços Kikwiflow diferentes.

kikwiflow.rest.* (API de gestão — KikwiflowRestProperties, módulo kikwi-management-rest-spring-boot-autoconfigure)

Propriedade	Tipo	Default	Efeito
kikwiflow.rest.base-path	String	/kikwiflow/api/v1	Prefixo base de todos os endpoints REST de gestão.
kikwiflow.rest.cors.allowed-origins	String[]	[] (nenhuma origem liberada)	Origens permitidas para CORS nos endpoints de gestão.

:::info kikwiflow.rest.process-definition.deploy.enabled não existe como binding real Esse caminho de propriedade aparecia no application.yml do sample-onboarding-process (já removido de lá), mas não corresponde a nenhum campo em KikwiflowRestProperties (que só expõe base-path e cors.allowed-origins) nem é lido em nenhum controller do kikwi-management-rest — ProcessDefinitionCommandController.deploy delega direto para processDefinitionService.deploy(...), cujo único controle de acesso é kikwiflow.security.deploy-enabled (descrito acima). Trate essa chave como configuração morta/sem efeito até que um binding real seja adicionado — o controle de fato do endpoint de deploy é feito por kikwiflow.security.deploy-enabled. :::

kikwiflow.pulse.sse-endpoints.* (KikwiflowPulseProperties)

Propriedade	Tipo	Default	Efeito
kikwiflow.pulse.sse-endpoints.enabled	boolean	true	Habilita os endpoints de Server-Sent Events para acompanhamento em tempo real (ex.: contadores/estatísticas expostos por kikwi-management-rest).
kikwiflow.pulse.sse-endpoints.interval	long (ms)	5000	Intervalo entre emissões de cada conexão SSE aberta.

kikwiflow.history.* (KikwiflowHistoryProperties, módulo kikwi-management-rest-spring-boot-autoconfigure)

Propriedade	Tipo	Default	Efeito
kikwiflow.history.enabled	boolean	true	Registra (ou não) GET /process-instances/{id}/events. Independente de kikwiflow.outbox.events-enabled — essa flag controla se o endpoint existe, não se há dado para servir. Ver Eventos e Observabilidade.

kikwiflow.monitor-ui.* (UI de monitoramento embarcada — MonitorUiProperties, módulo kikwi-monitor-spring-boot-autoconfigure)

Presentes apenas quando kikwi-monitor-spring-boot-starter está no classpath. Esse módulo só serve a SPA estática do Kikwiflow Monitor (sob o path fixo /monitor-ui/) mais um endpoint GET /monitor-ui/config.json que reflete estas propriedades em camelCase — ele não fala com o motor, não é proxy e não valida token. O browser lê apiUrl desse config.json e chama kikwi-management-rest diretamente. Requer uma aplicação web servlet. Ver kikwi-monitor: Lib Spring que Embarca o Monitor para o detalhamento completo.

Propriedade	Tipo	Default	Efeito
kikwiflow.monitor-ui.enabled	boolean	true	Liga/desliga a auto-configuration inteira do módulo. Com false, nenhum recurso de /monitor-ui/** é registrado.
kikwiflow.monitor-ui.api-url	String	http://localhost:8081	Host onde kikwi-management-rest está rodando (mesmo processo, outro processo ou outro host — indiferente para esta lib). Vai no config.json como apiUrl e é a base de todas as chamadas REST/SSE que o browser faz.
kikwiflow.monitor-ui.require-auth	boolean	true	Se false, o frontend não exige token (nem OIDC nem manual) — use só em ambiente fechado/local.
kikwiflow.monitor-ui.read-only	boolean	false	Esconde na UI os comandos de escrita (iniciar instância, retry, complete, claim/unclaim). Não substitui autorização no servidor — é só cosmético no frontend.
kikwiflow.monitor-ui.oidc-authority	String	""	Repassado ao config.json (oidcAuthority). Vazio desliga o fluxo OIDC no frontend.
kikwiflow.monitor-ui.oidc-client-id	String	""	client_id OIDC repassado ao frontend.
kikwiflow.monitor-ui.oidc-redirect-uri	String	""	Redirect URI OIDC repassado ao frontend.

:::info CORS e path continuam fora deste módulo Como o browser fala direto com kikwi-management-rest, se a UI for servida de um host/porta diferente do da API REST (ex.: api-url apontando para outro serviço), essa origem precisa estar em kikwiflow.rest.cors.allowed-origins no host do motor (ver seção acima); no mesmo processo, não. O prefixo /monitor-ui é uma constante Java fixada em build time nos artefatos do frontend — não existe propriedade para mudá-lo. :::

spring.data.mongodb.* (persistência — Spring Data MongoDB padrão)

Não são propriedades do Kikwiflow, mas são obrigatórias quando kikwi-runtime-persistence-mongodb-spring-boot-starter está no classpath:

Propriedade	Efeito
spring.data.mongodb.uri	Connection string. Deve apontar para um replica set (ver Persistência e Consistência Transacional) — transações multi-documento exigem isso. Nunca declare credenciais em texto plano no application.yml versionado; use variável de ambiente.
spring.data.mongodb.database	Nome do banco de dados.
spring.data.mongodb.auto-index-creation	Recomendado true — combinado com KikwiEngineRepository.ensureIndexes(), chamado no boot.

Exemplo consolidado de application.yml recomendado

spring:
  threads:
    virtual:
      enabled: true
  data:
    mongodb:
      uri: ${MONGODB_URI}
      database: ${MONGODB_DATABASE}
      auto-index-creation: true

kikwiflow:
  process-definition:
    auto-deploy:
      enabled: true
      path: "classpath*:processes/**/*.kikwi"
  security:
    deploy-enabled: true    # obrigatório declarar — default é false
  execution:
    task-acquisition-interval-millis: 1000
    task-acquisition-max-tasks: 20
    max-concurrent-tasks: 200
    shutdown-grace-period-seconds: 30
    lock-timeout-millis: 30000   # recomendado declarar explicitamente em produção — default de fábrica é 5000 (5s)
  retry:
    default-retry-interval: PT1M
    fatal-exceptions:
      - java.lang.NullPointerException
      - java.lang.IllegalArgumentException
  stats:
    enabled: true
  outbox:
    events-enabled: true                 # habilita persistência em outbox_events (sem relay embutido)
    ttl: P30D                            # opcional — retenção indefinida se omitido
  rest:
    base-path: /kikwiflow/api/v1
    cors:
      allowed-origins: "https://app.suaempresa.com"
  pulse:
    sse-endpoints:
      enabled: true
      interval: 5000
  history:
    enabled: true                        # registra GET /process-instances/{id}/events
  monitor-ui:                            # só se kikwi-monitor-spring-boot-starter estiver no classpath
    enabled: true
    api-url: "https://app.suaempresa.com"  # host onde kikwi-management-rest responde
    require-auth: true                     # false só em ambiente fechado/local
    read-only: false

:::tip Ambiente local / demo Para rodar o monitor embarcado localmente sem configurar OIDC, o mínimo é kikwiflow.monitor-ui: { enabled: true, api-url: "http://localhost:8081", require-auth: false } (ajuste a porta para a da sua aplicação). Depois é só abrir http://localhost:8081/monitor-ui/. Como UI e API REST estão no mesmo processo, não é preciso configurar CORS — só quando api-url aponta para outro host. :::