From 18e20619c3893d3cd2fb68788f48149237a5030e Mon Sep 17 00:00:00 2001 From: Rodrigo Tardelli Date: Thu, 28 Sep 2023 13:21:55 -0300 Subject: [PATCH 1/2] Improvement in entity audit documentation --- developers/backend-api/entity-audit.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/developers/backend-api/entity-audit.md b/developers/backend-api/entity-audit.md index e3bb9b3..2bba67a 100644 --- a/developers/backend-api/entity-audit.md +++ b/developers/backend-api/entity-audit.md @@ -1,6 +1,6 @@ # 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. @@ -8,7 +8,7 @@ Live supports storing an `EntityAudit` in two forms: a _database record_ and/or {% 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 %} \ No newline at end of file +{% 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. From 4963e7e14f199a8a69731962e5c339bd37b15355 Mon Sep 17 00:00:00 2001 From: Rodrigo Tardelli Date: Fri, 29 Sep 2023 14:22:24 -0300 Subject: [PATCH 2/2] Apply changes from review --- developers/backend-api/entity-audit.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/developers/backend-api/entity-audit.md b/developers/backend-api/entity-audit.md index 2bba67a..8e6aaed 100644 --- a/developers/backend-api/entity-audit.md +++ b/developers/backend-api/entity-audit.md @@ -1,6 +1,6 @@ # Entity Audit -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. +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. 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. @@ -20,7 +20,19 @@ There are some rules to an entity to be available for auditing. The `EntityAudit ## 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: +Starting in version 3.36.0, **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). + +```java +/* This TypeAdapter is including an instance of EntityContext to provide a way to recovery the user by its ID */ +EntityContext entityContext = live.data().getContext(); +AssetTypeAdapter assetTypeAdapter = new AssetTypeAdapter(entityContext); +TypeAdapterDescriptor typeAdapterDescriptor = new TypeAdapterDescriptor<>("asset", Asset.class, assetTypeAdapter, AssetDTO::new); + +EntityAuditOptions options = new EntityAuditOptions(Collections.singletonList(typeAdapterDescriptor)); +live.data().auditHibernateSessions(sessionFactory, options); +``` + +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 = ... @@ -112,4 +124,4 @@ If needed, the user can use the result of this method to roll back parts or all {% 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. +{% hint style="info" %} A change in version 3.36.0 was made in the list of EntityAudit 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.