From 8c78c660284d11c202e853158db1c86ee7c02eb6 Mon Sep 17 00:00:00 2001
From: Christoph Strobl <cstrobl@vmware.com>
Date: Wed, 27 Jan 2021 10:16:44 +0100
Subject: [PATCH] Update auditing documentation.

Mention that even when only using the CreatedDate & LastModifiedDate annotations it is mandatory to enable auditing.
Add sample of using auditing metadata within an embedded entity.

Closes #2283
---
 src/main/asciidoc/auditing.adoc | 35 ++++++++++++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/src/main/asciidoc/auditing.adoc b/src/main/asciidoc/auditing.adoc
index ba571e3e86..4fd5dfca88 100644
--- a/src/main/asciidoc/auditing.adoc
+++ b/src/main/asciidoc/auditing.adoc
@@ -4,6 +4,13 @@
 [[auditing.basics]]
 == Basics
 Spring Data provides sophisticated support to transparently keep track of who created or changed an entity and when the change happened. To benefit from that functionality, you have to equip your entity classes with auditing metadata that can be defined either using annotations or by implementing an interface.
+Additionally auditing has to be enabled either via Java or XML configuration which ensures required infrastructure components get registered.
+Please refer to the store specific section for configuration samples.
+
+[NOTE]
+====
+Applications that only track creation and modification dates do not need to specify an <<auditing.auditor-aware>>.
+====
 
 [[auditing.annotations]]
 === Annotation-based Auditing Metadata
@@ -19,7 +26,7 @@ class Customer {
   private User user;
 
   @CreatedDate
-  private DateTime createdDate;
+  private Instant createdDate;
 
   // … further properties omitted
 }
@@ -28,6 +35,32 @@ class Customer {
 
 As you can see, the annotations can be applied selectively, depending on which information you want to capture. The annotations capturing when changes were made can be used on properties of type Joda-Time, `DateTime`, legacy Java `Date` and `Calendar`, JDK8 date and time types, and `long` or `Long`.
 
+Auditing metadata does not necessarily need to live in the root level entity but can be added to an embedded one (depending on the actual store in use), as shown in the snipped below.
+
+.Audit metadata in embedded entity
+====
+[source, java]
+----
+class Customer {
+
+  @Embedded
+  private AuditMetadata auditingMetadata;
+
+  // … further properties omitted
+}
+
+class AuditMetadata {
+
+  @CreatedBy
+  private User user;
+
+  @CreatedDate
+  private Instant createdDate;
+
+}
+----
+====
+
 [[auditing.interfaces]]
 === Interface-based Auditing Metadata
 In case you do not want to use annotations to define auditing metadata, you can let your domain class implement the `Auditable` interface. It exposes setter methods for all of the auditing properties.