Improvement in entity audit documentation

developers/backend-api/entity-audit.md

@@ -1,14 +1,14 @@
 # Entity Audit
 
-An **Entity Audit** represents a write operation on a **Live** entity, that was captured by a Hibernate Listener, and transformed into a new entity called `EntityAudit`. This new entity stores details of the operation and the new state of the entity in the system.
+An **Entity Audit** represents a write operation on a **Live** entity, that was listened by a Hibernate Listener, and transformed into a new entity called `EntityAudit`. This new entity stores details of the operation and the new state of the entity in the system.
 
 Live supports storing an `EntityAudit` in two forms: a _database record_ and/or an _event_ depending on the configuration set in the general system settings.
 
 ![configuration image](<../../.gitbook/assets/entity_audit_config.png>)
 
 {% hint style="info" %} This feature is disabled by default. {% endhint %}
 
-## Auditable entities
+## Live auditable entities
 
 There are some rules to an entity to be available for auditing. The `EntityAuditListener` is the base class of the listeners and apply some filters before auditing a entity:
 
@@ -18,6 +18,19 @@ There are some rules to an entity to be available for auditing. The `EntityAudit
 
 {% hint style="warning" %} **Delete operations do not store the complete content** of the entity due to a technical reason. In delete operations the Hibernate Listener can no longer have access to a relationship of the target entity. Another point is that this operation do not change the last version of the content being deleted and therefore would be a resource waste. {% endhint %}
 
+## Plugin auditable entities
+
+Starting in version 3.36, **Live** provides new API entry that permits plugins to register their own __Hibernate Session Factory__ into Live to expand the auditing features to the plugin's entities. Live will use the plugin's __Hibernate Session Factory__ to register a `EntityAuditDBListener` with all necessary `TypeAdapters` and used it to search for `EntityAudits` entities in the auditing endpoint (/rest/entity-audit). It is also possible to extend the listener in order to customize the common rules and add more skip conditions to avoid auditing a write operation. With that in hand the plugin can register the listener by itself in its _Hibernate Session Factory_ as this snippet bellow:
+
+```java
+EntityAuditDBListener myListener = ...
+
+EventListenerRegistry registry = ((SessionFactoryImpl) sessionFactory).getServiceRegistry().getService(EventListenerRegistry.class);
+registry.getEventListenerGroup(EventType.POST_INSERT).appendListener(myListener);
+registry.getEventListenerGroup(EventType.POST_UPDATE).appendListener(myListener);
+registry.getEventListenerGroup(EventType.POST_DELETE).appendListener(myListener);
+```
+
 ## Using audit as versioning
 
 As said before, if the feature is enabled in the system configurations, the write operations of entities will be stored containing the current version of the entity in json format, e.g. the `Plugin` entity:
@@ -97,4 +110,6 @@ This endpoint retrieves the entity content from an `EntityAudit`. It is used to
 
 If needed, the user can use the result of this method to roll back parts or all of the current version of an entity by calling the save method on the related resource class.
 
-{% hint style="warning" %} Getting an EntityAudit that represents a delete operation will return a BAD_REQUEST. As explained before, EntityAudits of delete operations do not hold an entity content {% endhint %}
+{% hint style="warning" %} Getting an EntityAudit that represents a delete operation will return a BAD_REQUEST. As explained before, EntityAudits of delete operations do not hold an entity content {% endhint %}
+
+{% hint style="info" %} A change was made in the EntityAudits returned by the listing endpoints (List by type and List by type and id). That change replaces the `author` field from a structure like `{"id":1, "name":"someone"}` to a simple integer representing the id. This was necessary to keep the model of EntityAudit from Live and the plugins the same as the plugins do not store users information to fill in the value.