From 6d36d582353342170501a798f4fe04ecc020dd49 Mon Sep 17 00:00:00 2001
From: Radovan Semancik <radovan.semancik@evolveum.com>
Date: Wed, 17 Apr 2019 10:17:07 +0200
Subject: [PATCH] Adding audit request ID to audit-api (MID-3610)

---
 .../midpoint/audit/api/AuditEventRecord.java  | 49 +++++++++++++++++--
 1 file changed, 46 insertions(+), 3 deletions(-)

diff --git a/repo/audit-api/src/main/java/com/evolveum/midpoint/audit/api/AuditEventRecord.java b/repo/audit-api/src/main/java/com/evolveum/midpoint/audit/api/AuditEventRecord.java
index bd6aaae967c..ac3973014cd 100644
--- a/repo/audit-api/src/main/java/com/evolveum/midpoint/audit/api/AuditEventRecord.java
+++ b/repo/audit-api/src/main/java/com/evolveum/midpoint/audit/api/AuditEventRecord.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010-2017 Evolveum
+ * Copyright (c) 2010-2019 Evolveum
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -53,8 +53,11 @@
  */
 public class AuditEventRecord implements DebugDumpable {
 
-
+	/**
+	 * TODO: what is this?
+	 */
 	private Long repoId;
+	
 	/**
 	 * Timestamp when the event occured.
 	 * Timestamp in millis.
@@ -63,9 +66,28 @@ public class AuditEventRecord implements DebugDumpable {
 
 	/**
 	 * Unique identification of the event.
+	 * Every record should have unique event identifier.
 	 */
 	private String eventIdentifier;
 
+	/**
+	 * <p>
+	 * Identifier of a request (operation). All the records that are result of
+	 * processing of a single request should have the same identifier.
+	 * In usual case there should be be a single request-stage record
+	 * and one or more execution-stage records with the same request
+	 * identifier.
+	 * </p>
+	 * <p>
+	 * Please note that this is quite different than task identifier.
+	 * A single task can make many requests. E.g. a typical reconciliation
+	 * task will make thousands of operations. All of the audit records from
+	 * all of those operations will have the same task identifier. But each
+	 * operation will have a separate request identifier.
+	 * </p>
+	 */
+	private String requestIdentifier;
+	
 	/**
 	 * Identitification of (interactive) session in which the event occured.
 	 */
@@ -73,8 +95,29 @@ public class AuditEventRecord implements DebugDumpable {
 
 	// channel???? (e.g. web gui, web service, ...)
 
-	// task ID (not OID!)
+	/**
+	 * <p>
+	 * Task identifier. Operations are executed in a context of a task.
+	 * This field is an identifier of the task. It is not (necessarily) an
+	 * OID of the task, as an operation may be executed in an non-persistent
+	 * (lightweight) task. This field should be populated for all audit records,
+	 * perhaps except very special system-level records that are executed outside
+	 * of a task.
+	 * </p>
+	 * <p>
+	 * Please note that this is quite different than request identifier.
+	 * A single task can make many requests. E.g. a typical reconciliation
+	 * task will make thousands of operations. All of the audit records from
+	 * all of those operations will have the same task identifier. But each
+	 * operation will have a separate request identifier.
+	 * </p>
+	 */
 	private String taskIdentifier;
+	
+	/**
+	 * Task OID. This field is used for records that are executed in the context
+	 * of a persistent task.
+	 */
 	private String taskOID;
 
 	private String hostIdentifier;		// local node name as obtained from the networking stack