Histórico de Eventos

Timeline de eventos críticos de uma instância — a base para telas de troubleshooting/auditoria (o "Cockpit" do Kikwiflow). Este documento cobre só o contrato REST; para o catálogo completo dos 13 tipos de evento, o padrão outbox, garantias transacionais e a distinção com eventos leves, veja Eventos e Observabilidade — leitura obrigatória antes de construir qualquer coisa sobre este endpoint.

GET /process-instances/{id}/events

Requer QueryRepository. Registro do endpoint é condicional a duas flags independentes:

Flag	Controla
kikwiflow.outbox.events-enabled (default false)	Se o dado existe — eventos só são gravados no outbox com essa flag ligada.
kikwiflow.history.enabled (default true)	Se o endpoint é registrado. Desligar remove o endpoint inteiro, mesmo com o outbox habilitado.

Resposta

200 OK — HistoryEventSummary[], ordenado por timestamp ascendente (a ordem em que a instância passou pelos nós):

[
  {
    "id": "6f2e...",
    "eventType": "FLOW_NODE_FINISHED",
    "processInstanceId": "ae8fd836-...",
    "processDefinitionId": "fc451f6f-...",
    "tenantId": "empresa-abc-123",
    "actorId": null,
    "timestamp": "2026-07-24T17:10:32.100Z",
    "payload": { "flowNodeDefinitionId": "ENRICH_CUSTOMER_PROFILE", "nodeExecutionStatus": "SUCCESS", "...": "..." }
  }
]

payload é polimórfico — sua forma depende de eventType (ver a tabela completa de payloads em Eventos e Observabilidade §Tipos de evento crítico emitidos hoje). actorId é null para os tipos que não carregam identidade de ator (FLOW_NODE_FINISHED, GATEWAY_ANSWER_RESOLVED, PROCESS_INSTANCE_FINISHED, ORPHANED_CHILD_COMPLETION) ou o sentinel "__KIKWIFLOW_SYSTEM__" para ações que o motor dispara sozinho (IncidentCreated, RetryScheduled, TimerFired).

eventType (CriticalEventType), catálogo completo:

FLOW_NODE_FINISHED · GATEWAY_ANSWER_RESOLVED · PROCESS_INSTANCE_STARTED · PROCESS_INSTANCE_FINISHED · INCIDENT_CREATED · INCIDENT_RESOLVED · EXTERNAL_TASK_CLAIMED · EXTERNAL_TASK_UNCLAIMED · EXTERNAL_TASK_COMPLETED · RETRY_SCHEDULED · PROCESS_VARIABLE_CHANGED · TIMER_FIRED · ORPHANED_CHILD_COMPLETION

404 (NOT_FOUND) se a instância não existir. Lista vazia (não erro) se o outbox nunca foi habilitado para essa instância, ou se ela simplesmente ainda não gerou eventos.

Mascaramento em PROCESS_VARIABLE_CHANGED

Diferente da escrita no outbox (que grava o valor bruto — masking não é decisão do ponto de gravação), a leitura via este endpoint aplica VariableSecurityPolicyManager.applyReadPoliciesAndMasking antes de devolver a resposta: se a policy nega leitura daquela variável para o IdentityContext da chamada, value vem null em vez do dado real. Como a implementação padrão (DefaultVariableSecurityPolicyManager) é um no-op que permite tudo (ver Convenções, Autenticação e Erros), esse mascaramento só existe de fato se sua aplicação fornecer sua própria implementação.

:::danger Sem enforcement de tenant — de propósito Este endpoint não valida tenantId do chamador contra o tenantId da instância. É intencional: é um endpoint de backoffice/suporte, não uma API de uso geral para aplicação cliente — presume-se que quem acessa já tem permissão independente de tenant (ver Eventos e Observabilidade). Se você expuser este dado para usuários finais (não só para operação interna), implemente enforcement de tenant na sua própria camada — o Kikwiflow não faz isso aqui. :::

Apagar a instância não apaga o histórico

PUT /process-instances/{id} (ver Instâncias de Processo) remove a instância e suas tarefas, mas não apaga as entradas de outbox_events associadas — o histórico continua consultável por este endpoint mesmo depois da instância sumir, como rastro de auditoria.