Registry technical audit columns documentation

chapter_3/create_registry/index.rst

@@ -295,3 +295,70 @@ pay attention to the JNDI name (in case you created the table within Knowage met
 - ``MODEL_NAME``: name of the business model
 - ``ATTRIBUTES_OLD``: previous attributes state in case of an UPDATE or DELETION
 - ``ATTRIBUTES_NEW``: new attributes state in case of an INSERTION or UPDATE
+
+
+Auditing with table's technical columns
+-------------------
+
+Another simple audit mechanism is available, that enables also final users to:
+- discover the user who inserted a record and when;
+- discover the last user who modified a record and when;
+- discover the user who logically deleted (*) a record and when;
+- logically delete a record.
+
+(*) Logical deletion means that the records is flagged as "deleted", but it is still physically stored within the database table.
+
+These information (except the logically deletion column) are set automatically by KNOWAGE when user interacts with the registry document, and then saved inside the same table the registry document is built upon. A suitable table has to contain some technical columns to be used specifically for auditing purposes: for example, consider the following table:
+
+.. code-block:: sql
+   :linenos:
+
+   CREATE TABLE store_with_audit (
+     store_id int NOT NULL,
+     store_name varchar(30) DEFAULT NULL,
+     ... other stores related columns ...
+     user_in varchar(45) DEFAULT NULL,
+     user_up varchar(45) DEFAULT NULL,
+     user_de varchar(45) DEFAULT NULL,
+     time_in datetime DEFAULT NULL,
+     time_up datetime DEFAULT NULL,
+     time_de datetime DEFAULT NULL,
+     deleted tinyint(1) DEFAULT NULL
+   )
+
+The meaning of the last columns is:
+- user_in: the user who inserted the record;
+- time_in: insertion timestamp;
+- user_up: the last user who modified the record;
+- time_up: last modification timestamp;
+- user_de: the user who logically deleted the record;
+- time_de: logical deletion timestamp;
+- deleted: boolean flag to represent if the record is logically deleted or not.
+
+Of course this is a simple audit management system, it cannot track all the records history: for example, only the last modification information is kept.
+
+A valid template for this registry looks like:
+
+.. code-block:: xml
+    :linenos:
+    :caption: Example (b) of template code for Registry.
+
+    <COLUMN field="user_in" visible="true" editable="false" title="User insert" audit="USER_INSERT"	/>
+    <COLUMN field="user_up" visible="true" editable="false" title="User update" audit="USER_UPDATE"	/>
+    <COLUMN field="user_de" visible="true" editable="false" title="User delete" audit="USER_DELETE"	/>
+    <COLUMN field="time_in" visible="true" editable="false" title="Time insert" audit="TIME_INSERT"	/>
+    <COLUMN field="time_up" visible="true" editable="false" title="Time update" audit="TIME_UPDATE"	/>
+    <COLUMN field="time_de" visible="true" editable="false" title="Time delete" audit="TIME_DELETE"	/>
+    <COLUMN field="deleted" visible="true" editable="true"  title="Is deleted?" audit="IS_DELETED"	/>
+
+As you can see, the audit columns must have the "audit" attribute with one of the following admissible values (no other values are permitted):
+USER_INSERT, USER_UPDATE, USER_DELETE, TIME_INSERT, TIME_UPDATE, TIME_DELETE, IS_DELETED
+
+Some notes:
+- the audit columns are not mandatory: you can have a subset of those (for example you can have only insertion columns, or only deletion columns) or even none;
+- a record can be logically deleted but also reactivated: when a record is being reactivated, deletion user and time are reset to null;
+- all audit columns (except the "deleted" column) must be readonly; setting them as visible and editable is not permitted, since they are managed by KNOWAGE;
+- all audit columns can be set to be not visible; of course, setting the "deleted" column to be invisible does not make much sense, since it means that nobody will be able to exploit it and to logically delete records;
+- when cloning a record, audit columns are NOT cloned;
+- physical deletion is permitted, you can enable it in case you need.
+