Skip to main content

Building the command

The jeap-audit-command-builder module provides the fluent CreateAuditRecordCommandBuilder and the Spring-managed CreateAuditRecordCommandBuilderFactory.

CreateAuditRecordCommandBuilder​

Use the builder directly when you construct the command yourself (and send it however you like). Create it with the auditing service's name, its system name and a timestamp; an optional processId can be passed as a fourth argument.

CreateAuditRecordCommand command = CreateAuditRecordCommandBuilder
        .createCommandBuilder(serviceName, systemName, Instant.now())
        .setEventType(AuditEventType.CREATED)
        .addEventData("key1", "value1")
        .addEventData("key2", "value2")
        .setTriggerUser(userId, identityProvider)
        .build();

Builder methods​

MethodPurpose
setEventType(AuditEventType)Event type; defaults to AuditEventType.UNKNOWN if not set
setContext(useCase) / setContext(useCase, processId)Sets the audit context; the two-arg form must agree with any processId already on the command
addEventData(key, value)Adds a free-form key/value element to the audit event (key and value both required, repeatable)
setTriggerUser(userId, identityProvider)Sets a user trigger (clears any system trigger)
setTriggerSystem(department, system, component)Sets a system trigger (clears any user trigger)
setAuditObject(type, id) / setAuditObject(type, id, version)Sets the audited object
addAuditObjectDataValue([role,] name, value)Adds a plain string value entry to the audited object
addAuditObjectDataJSON([role,] name, jsonAsUTF8)Adds a JSON entry (accepts a String or ByteBuffer)
addAuditObjectDataS3([role,] name, objectReference)Adds an S3 object-reference entry
idempotenceId(id)Overrides the generated idempotence id (inherited from AvroCommandBuilder)
build()Validates and returns the CreateAuditRecordCommand

The role argument on the addAuditObjectData* methods is an optional AuditObjectDataRole (NEW or OLD), used to distinguish before/after values; overloads without it pass null.

Event data (addEventData)​

Event data is a list of free-form AuditEventDataElement key/value pairs attached to the audit event — supplementary context about the action, as opposed to the state of the audited object. Use it for facts that are not a field of the audited business object, for example the reason for a change, a correlation/request id, the channel or client IP the action came through, or any use-case-specific tag.

CreateAuditRecordCommand command = CreateAuditRecordCommandBuilder
        .createCommandBuilder(serviceName, systemName, Instant.now())
        .setEventType(AuditEventType.MODIFIED)
        .addEventData("reason", "customer request")
        .addEventData("correlationId", correlationId)
        .setTriggerUser(userId, identityProvider)
        .build();
  • Both key and value are required (non-null Strings).
  • addEventData is repeatable and preserves insertion order.
  • Event data is optional as a whole: if you add none, the event simply carries no event data.

Contrast with addAuditObjectData*: use addEventData for event-level context; use the addAuditObjectData* methods to capture the audited object's data/state (which additionally support an optional NEW/OLD role for before/after comparison).

Rules enforced by build()​

  • Exactly one trigger must be set (setTriggerUser or setTriggerSystem), otherwise build() throws IllegalStateException.
  • If no idempotenceId was set, one is generated from systemName, serviceName, the event type, the trigger (user id or system component) and the timestamp.
  • setContext(useCase, processId) throws IllegalArgumentException if its processId differs from a processId already supplied to createCommandBuilder.

CreateAuditRecordCommandBuilderFactory​

The factory is auto-configured as a Spring bean. It pre-fills the trigger so callers do not have to extract it themselves. serviceName/systemName default to the values from the jEAP messaging Kafka properties; overloads let you pass them explicitly.

// User trigger taken from the current jEAP security token (token subject + issuer):
CreateAuditRecordCommandBuilder builder = factory.createWithUserTrigger(Instant.now());

// System trigger taken from a consumed message (its publisher system & service):
CreateAuditRecordCommandBuilder builder =
        factory.createWithSystemTriggerFromMessage(triggeringDepartment, Instant.now(), message);

CreateAuditRecordCommand command = builder.build();

createWithUserTrigger requires jEAP security on the classpath; without it the factory throws an AuditException ("You cannot use user convenience method without jEAP security"). When jEAP security is present but the current security context does not hold a recognized JeapAuthenticationToken (e.g. the call is made outside a request scope or before authentication), the factory throws AuditException ("Could not determine user data from the security context. Unsupported user Authentication: <auth>"). The user id is the token subject (the PAMS ID in the ePortal context) and the identity provider is the token issuer. createWithSystemTriggerFromMessage derives the idempotence id from the source message (audit-<message idempotence id>).