Process History

The Process History Service, implemented through the Data-Audit subsystem, provides a comprehensive temporal view of process execution throughout the lifecycle of process instances. This component is a crucial part of the Adaptive Process Architecture, maintaining an immutable record of every significant event for compliance, analysis, and process improvement.

Overview

The Data-Audit subsystem enables the storage of events issued by various process components and persists them in a structured format. It captures the complete evolution of process instances, from creation to completion, including all intermediate state changes. The Data-Audit system consists of several modules:

Data-Audit Common: Provides the common framework to create implementations
Data-Audit «Quarkus»: Provides the wiring to use Data-Audit with Quarkus as a colocated service
Data-Audit JPA Common: Provides the common extension that doesn’t depend on the runtime
Data-Audit JPA «Quarkus»: Provides the wiring between the specific implementation and Quarkus System

Key Features

Comprehensive Event Recording

The Data-Audit subsystem records events from multiple sources:

Workflow Engine Events: Process instance creation, state transitions, completion
User Task Events: Task creation, assignment, completion
Temporal Events: Timer creation, execution, cancellation
Variable Events: Data modifications throughout the process lifecycle

Immutable Audit Trail

The Process History Service maintains an immutable record of all events, ensuring compliance with regulatory requirements and providing a trusted audit trail for:

Compliance verification
Process forensics
Legal documentation
Historical analysis

Temporal Querying

Through its GraphQL interface, the Data-Audit service supports sophisticated temporal queries that can:

Identify historical patterns
Compare process performance over time
Reconstruct the state of a process at any point in time
Analyze decision paths and outcomes

Extensibility

The Data-Audit subsystem provides several extension points:

Storage customization
Query customization
Event filtering
Security integration

Querying the Process History Service

The Data-Audit service exposes a GraphQL endpoint for querying historical process data:

${HOST}/data-audit/q

Example Queries

Retrieve Process Instance States

This example shows how to retrieve all process instance states:

curl -H "Content-Type: application/json" -H "Accept: application/json" -s -X POST http://${HOST}/data-audit/q/ -d '
{
    "query": "{GetAllProcessInstancesState {eventId, processInstanceId, eventType, eventDate}}"
}'|jq

Register a Custom Query

You can register custom queries to extract specific information:

curl -H "Content-Type: application/json" -H "Accept: application/json" -s -X POST http://${HOST}/data-audit/r/ -d '
{
    "identifier" : "tests",
    "graphQLDefinition" : "type EventTest { jobId : String, processInstanceId: String} type Query { tests (pagination: Pagination) : [ EventTest ] } ",
    "query" : "SELECT o.job_id, o.process_instance_id FROM job_execution_log o"
}'

Once registered, you can execute the custom query:

curl -H "Content-Type: application/json" -H "Accept: application/json" -s -X POST http://${HOST}/data-audit/q/ -d '
{
    "query": "{tests {jobId, processInstanceId}}"
}'|jq

Schema Discovery

To retrieve the GraphQL schema definition including a list of all registered queries, run a GET command to:

${HOST}/data-audit/r

This endpoint can also be used to register new queries.

Adding Data-Audit to Your Project

To enable the Process History Service in your project, add the following dependencies:

<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kogito-addons-quarkus-data-audit</artifactId>
</dependency>

<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kogito-addons-quarkus-data-audit-jpa</artifactId>
</dependency>

The first dependency specifies how you want to deploy the service (as a colocated/embedded service), and the second dependency specifies the implementation you want to use.

Java Persistence API (JPA) Implementation

The JPA implementation allows you to store the events in a relational database. This implementation uses the same database connection as your application, simplifying configuration and deployment. Depending on your database, you may need additional dependencies:

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>

Extension Points

The Data-Audit system provides several extension points for customization:

Context Factory

org.kogito.kie.app.audit.spi.DataAuditContextFactory depends on the runtime and enables the creation of the context needed by a particular implementation.

Runtime-Independent Extensions

These extension points do not depend on the runtime:

org.kie.kogito.app.audit.spi.DataAuditStore: Stores the data in a particular way
org.kie.kogito.app.audit.spi.GraphQLSchemaQuery<T>: Enables execution of a GraphQL query
org.kie.kogito.app.audit.spi.GraphQLSchemaQueryProvider: Enables the subsystem to identify additional queries provided by the end user

Configuration

The Data-Audit service is automatically configured to use the same data source as your main application. The most relevant configuration properties are:

# Enable or disable the Data-Audit service
kogito.data-audit.enabled=true

# Configure the audit retention period (in days)
kogito.data-audit.retention-period=365

Best Practices

Data Volume Management

Implement appropriate retention policies for audit data
Consider archiving older audit data to cold storage
Monitor the growth of audit tables

Query Performance

Create custom queries for frequently used reports
Use pagination for large result sets
Index database fields used in filtering

Compliance Requirements

Document the audit trail capabilities for regulatory reviews
Ensure audit data is properly secured
Implement backup strategies appropriate for compliance requirements

Home

Get started

AI Assistant

Core Concepts

Decision Control

Decision Control Tower

Drools

Guides

Platform

Deployment

Reference

FAQ

Process History

Overview

Key Features

Comprehensive Event Recording

Immutable Audit Trail

Temporal Querying

Extensibility

Querying the Process History Service

Example Queries

Retrieve Process Instance States

Register a Custom Query

Schema Discovery

Adding Data-Audit to Your Project

Java Persistence API (JPA) Implementation

Extension Points

Context Factory

Runtime-Independent Extensions

Configuration

Best Practices

Data Volume Management

Query Performance

Compliance Requirements

See Also

​Overview

​Key Features

​Comprehensive Event Recording

​Immutable Audit Trail

​Temporal Querying

​Extensibility

​Querying the Process History Service

​Example Queries

​Retrieve Process Instance States

​Register a Custom Query

​Schema Discovery

​Adding Data-Audit to Your Project

​Java Persistence API (JPA) Implementation

​Extension Points

​Context Factory

​Runtime-Independent Extensions

​Configuration

​Best Practices

​Data Volume Management

​Query Performance

​Compliance Requirements

​See Also

Overview

Key Features

Comprehensive Event Recording

Immutable Audit Trail

Temporal Querying

Extensibility

Querying the Process History Service

Example Queries

Retrieve Process Instance States

Register a Custom Query

Schema Discovery

Adding Data-Audit to Your Project

Java Persistence API (JPA) Implementation

Extension Points

Context Factory

Runtime-Independent Extensions

Configuration

Best Practices

Data Volume Management

Query Performance

Compliance Requirements

See Also