Getting started

What is the Atoti Audit Service

This service can be used in a Spring Boot application to track changes made to data in your applications. It provides REST services to view audit entries, and an API and default implementations to create audit entries. The audit entries include the following pieces of information:

• the type of object that was changed
• the id of the audit entry
• the id of the object that was changed
• the field of the object that was changed
• the old value of the field
• the new value of the field
• the time when the change was made
• optional extra information about the changes

The audit entry is intended to be a generic technical object - rather than a business-oriented or user-oriented object - so that it can be easily manipulated - for example filtered and sorted - for regulatory purposes.

Why use the Atoti Audit Service

The primary goals of the Atoti Audit Service are:

• to provide a way to view the changes made to data in your applications
• to provide a way to track changes made to data in your applications
• to provide a way to filter, sort and export the changes made to data in your applications for regulatory purposes

For clarity, the service is NOT intended to:

• provide a business specific view of the changes made to your data
• provide an out-of-the-box timeline view of the changes made to your data

Setting up the service

Prerequisites

Before you begin, ensure you have the following installed:

• Java 21+
• Maven 3.8+

Overview

There are two ways to use the service:

1. Using a Spring Boot Starter: this is the quickest way to get started
2. Using a custom implementation: this is the most flexible way to use the service

1. Using a Spring Boot Starter

This is the easiest way to get started with the service. When using this method of the service, you can import a Spring Boot starter and automatically inherit the default implementation of the service. This allows you to start using the service immediately.

These starters also allow you to configure the service to suit your needs. Each xyz-spring-boot-starter has a corresponding xyz module that contains the code that is imported into the starter. You can follow Spring best practices to modify the imported code or to extend its behavior and build your own starter.

The following section lists the starters we provide.

The Workflow Core Spring Boot Starter

This starter utilizes the com.activeviam.workflow.core.workflow.history.IAuditLogService that is provided by ActiveViam’s Business Solutions team’s workflow-core library. You can use this starter if the following dependency is present in your application:

<dependency>
    <groupId>com.activeviam.solutions.services</groupId>
    <artifactId>workflow-core</artifactId>
    <version>${workflow-core.version}</version>
</dependency>

The workflow-core.version version must be at least 2.5.0.

Installation

To install the starter, add the following dependency to your pom.xml file:

<dependency>
    <groupId>com.activeviam.solutions.services</groupId>
    <artifactId>audit-service-workflow-core-spring-boot-starter</artifactId>
</dependency>

If you want to implement your own starter, you can use the following dependency instead:

<dependency>
    <groupId>com.activeviam.solutions.services</groupId>
    <artifactId>audit-service-workflow-core</artifactId>
</dependency>

Configuration

Once you have added the starter to your project, you can start using the service. The service will automatically be configured with the default REST service to fetch audit entries and it will use your existing workflow-core library to create audit entries.

2. Using a custom implementation

This approach is more flexible than using a Spring Boot starter. It allows you to implement your own version of the service and to configure it to suit your needs.

Installation

To install the required dependencies, add the following to your pom.xml file:

<dependency>
    <groupId>com.activeviam.solutions.services</groupId>
    <artifactId>audit-service-rest</artifactId>
</dependency>

Configuration

To configure the service, you will need to create an implementation of the service and import the implementation and the REST service.

The implementation must extend the following com.activeviam.solutions.services.api.IAuditEntryRetrievalService interface methods:

/**
 * <b>IAuditEntryRetrievalService</b>
 *
 * <p>Service used to retrieve {@link AuditEntry}s.
 *
 * @author ActiveViam
 */
@PreAuthorize("@auditRoleValidationService.hasRequiredRole()")
public interface IAuditEntryRetrievalService {

  /**
   * @return the list of {@code types} of audit entries
   */
  List<String> getTypes();

  /**
   * @return the list of all audit entries
   */
  List<AuditEntry> getAuditEntries(List<FilterConditionDTO> filters);

  /**
   * @param type the type of audit entries to retrieve
   * @return the list of audit entries of the given {@code type}
   */
  List<AuditEntry> getAuditEntries(String type, List<FilterConditionDTO> filters);

  /**
   * @param type the type of audit entries to retrieve
   * @param objectId the ID of the entity to retrieve audit entries for
   * @return the list of audit entries of the given {@code type} and {@code objectId}
   */
  List<AuditEntry> getAuditEntries(String type, String objectId, List<FilterConditionDTO> filters);
}

This service is used to return audit entries. It is up to you to determine how these audit entries should be created and stored. The audit entry has the following java type:

/**
 * <b>AuditEntry</b>
 *
 * <p>A class representing an audit entry. An audit entry is a record of a change made to an object
 * and can be used for audit purposes.
 *
 * @author ActiveViam
 */
@Data
@SuperBuilder(toBuilder = true)
@NoArgsConstructor
public class AuditEntry {

  /** The type of the object that was changed. */
  protected String type;

  /** The unique id of the audit entry. Determined at runtime and used only by the UI currently. */
  @EqualsAndHashCode.Exclude protected Long id;

  /** The id of the object that was changed. */
  protected String objectId;

  /** The field that was changed. */
  protected String field;

  /** The old value of the field. */
  protected Object oldValue;

  /** The new value of the field. */
  protected Object newValue;

  /** The user who made the change. */
  protected String user;

  /** The timestamp of the change. */
  protected LocalDateTime timestamp;

  /** Fields containing additional logic, usually implementation specific, of the audit entry. */
  protected Map<String, Object> extraFields;
}

Then, import the implementation and the REST service into your project using:

@Import({
        YourAuditEntryRetrievalService.class,
        AuditServiceRestController.class
})
@Configuration
public class YourConfiguration {
    ...
}

Role-based access

You can configure a user role to access the audit service by specifying a value for the activeviam.apps.audit-service.required-role property. If this property is not set, the audit service will be accessible to all users. To enforce role-based access, you must enable method-level security by adding @EnableMethodSecurity to your application.