Merge remote-tracking branch 'refs/remotes/origin/master'

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,18 +66,58 @@ 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.
 	 */
 	private String sessionIdentifier;
 
 	// 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