Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improvement in entity audit documentation #24

Merged
merged 2 commits into from
Sep 29, 2023
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 18 additions & 3 deletions developers/backend-api/entity-audit.md
Original file line number Diff line number Diff line change
@@ -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.
RTardelliGarcia marked this conversation as resolved.
Show resolved Hide resolved

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:

Expand All @@ -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:
RTardelliGarcia marked this conversation as resolved.
Show resolved Hide resolved
RTardelliGarcia marked this conversation as resolved.
Show resolved Hide resolved

```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:
Expand Down Expand Up @@ -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.
RTardelliGarcia marked this conversation as resolved.
Show resolved Hide resolved