Audit

Introduction

The Audit module collects business-relevant changes performed through the platform — one entry per Flow run, Schedule execution, API call, or manual action — and persists them as a chain with its operations, identity-oriented change packages, and individual field-level changes. Unless configured headless, it also serves a dedicated audit UI and a read-only REST API over the same data.

See Data model for the chain, operation, package and change structure, Using the audit UI for the built-in UI, and API reference for the REST API.

Configuration

Note

Module name: Audit

Properties

Name	Description	Default	Mandatory
read_only	Serve queries without consuming events, writing records or running writer migrations. Use an existing audit database.	false
context_path	Path below the HTTP context for UI and API routes.	/
server_id	Server identifier stored on each chain this writer records; at most 255 characters.
requires_any_role	Allow a session with any listed role. Use a non-empty array or comma-separated string.	Unconfigured
requires_all_roles	Allow a session with every listed role. When both role settings are present, either requirement is sufficient.	Unconfigured
headless	If true, no UI route is set up; the node still collects events and serves the REST API.	false
http_context	HTTP context mount. API routes are published under {http_context}{context_path}/api, with slash normalization.	/audit
webroot_dir	Directory the built UI is unpacked to. Ignored when headless is true.	web/audit
public	Whether the UI's static assets are served without authentication.	true
type	Storage backend for the write path: jdbc or file. The REST API always reads through jdbc, regardless of this setting.	jdbc
path	File path for JSON Lines output. Required when type is file. Write-path only.
jdbc	JDBC connection used by both the write path and the REST API's read path. See below.	{}
object_types	Shared object-type definitions. Each type can configure ldap enrichment and jdbc table/reference mappings. See the object-type guidance below.	{}
enrichment	LDAP target-object enrichment configuration. See below.	{}

Example

{
  "name": "Audit",
  "config": {
    "jdbc": {
      "schema": "AUDIT"
    },
    "enrichment": {
      "ldap": {
        "object_types": {
          "user": {
            "display_name_attributes": ["displayName", "cn", "uid"]
          },
          "group": {
            "display_name_attributes": ["displayName", "cn"],
            "reference_attributes": {
              "member": {
                "value_object_type": "user",
                "identity_bearing": true
              }
            }
          }
        }
      }
    }
  }
}

The REST API is always available, whether or not headless is set — the UI is the optional part, not the API.

jdbc properties

Name	Description	Default	Mandatory
jdbc.destination	JdbcClient instance name used by both the write path and the REST API's read path.	default
jdbc.schema	Schema the audit tables live in — the single source for both write and read.	audit
jdbc.identity_bearing_attributes	Attribute names that override the default identity/object routing rule, independent of enrichment configuration. Write-path only.	[]

By default, events are written through jdbc to the configured database, in its own schema (audit by default), and the REST API reads through the same jdbc connection. For test or throwaway setups, events can instead be appended to a JSON Lines file by setting type to file — the REST API still reads through jdbc regardless.

Database setup

On writing servers, configure the selected JdbcClient's migrations.locations as ["classpath:db/migration/audit"] and its migrations.schemas to match jdbc.schema here. The first schema in that list is Flyway's default schema. Audit does not select those JdbcClient migrations automatically. Omit the JdbcClient migrations object on a read-only server; it reads the database migrated by a writer.

Shared object types

Configure new type mappings under object_types.<type>. The ldap subobject accepts the display-name and reference-attribute properties below and optional object_classes for resolving a type from a directory entry. Without explicit classes, user recognizes user and inetOrgPerson, while group recognizes group, groupOfNames and groupOfUniqueNames. An explicit empty class list disables this resolution for that type.

For JDBC, object_types.<type>.jdbc.tables lists tables holding that type. jdbc.reference_columns.<column> accepts value_object_type and identity_bearing (default false) to describe references to another configured type. Table and column matching is case-insensitive. A table cannot map to two types. JDBC identities are qualified with their type, for example user:42, to distinguish equal row IDs in different types.

The legacy enrichment.ldap.object_types location remains supported. Do not configure LDAP types there and under object_types.<type>.ldap at the same time: initialization rejects the combination. The example above uses the legacy location; its display-name and reference properties also apply at the new location.

Enriching LDAP changes

Raw change events reference LDAP entries by DN and attribute name. To show human-readable names, and to correctly attribute a change to the right identity — for example, a change to a group's member attribute should be attributed to the person added, not to the group — configure enrichment.ldap.object_types.

enrichment.ldap object type properties

Configured per object type under enrichment.ldap.object_types.<name>, for example enrichment.ldap.object_types.user.

Name	Description	Default	Mandatory
display_name_attributes	Ordered list of attributes to use as this object type's display name. The first attribute with a value on a given entry is used.
reference_attributes	Attributes on this object type that reference another object type. See below.	{}

enrichment.ldap reference attribute properties

Configured per attribute under enrichment.ldap.object_types.<name>.reference_attributes.<attribute>, for example enrichment.ldap.object_types.group.reference_attributes.member.

Name	Description	Default	Mandatory
value_object_type	The object type referenced by this attribute's values. Must also be defined under object_types.
identity_bearing	If true, a change to this attribute is attributed to the referenced value instead of the entry the write targeted.	false

Enrichment performs a live directory lookup per changed entry, using the same destination that made the original write. If a lookup fails — the entry was deleted, or the directory is unreachable — the raw change is still recorded; only the enriched values are missing.

Authentication

The audit UI's static assets are public by default (public: true). API authentication is supplied by the hosting product's authentication handler; the standalone module has none by default. Protect a standalone deployment through an authenticated gateway or restricted network.

Both UI and API routes enforce requires_any_role and requires_all_roles against the session's roles. With both configured, satisfying either requirement grants access. Missing roles fail a configured requirement with HTTP 403. Empty or malformed configured role lists fail startup; omission leaves that role requirement unconfigured. public controls static-asset authentication and does not bypass role checks.

Read-only deployments

Set read_only: true to serve an existing database without consuming or persisting events or running writer migrations. Point jdbc.destination and jdbc.schema at the writer's database. The module logs missing or older schema information at startup; the read-only startup check does not itself fail startup. Configure server_id on writing servers when several servers share a database.

In this section

• Data model
• Using the audit UI
• API reference