Important

You are browsing the documentation for version 4.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Data Audit

Introduction

The OroDataAuditBundle leverages the Loggable Doctrine extension (StofDoctrineExtension) to provide changelogs for your entities.

Entity Configuration

DataAudit can only be enabled for Configurable entities. To add a property of an entity to the changelog, you simply have to enable the audit for the entity itself and specify some fields you want to be logged. To achieve this, you should use the Oro\Bundle\EntityConfigBundle\Metadata\Annotation\Config and Oro\Bundle\EntityConfigBundle\Metadata\Annotation\ConfigField annotations for the entity.

Caution

Note that this annotation will be read-only on installation. On platform updates, this annotation will be read and only saved in the configuration for new entities, or for entities which were not Configurable before or have not be changed via the configuration UI.

Note

Audit can be enabled/disabled per an entire entity or for separate fields in the UI under System / Entities / EntityManagement (attribute Auditable).

Example of annotation configuration:

 1// src/Acme/DemoBundle/Entity/Product.php
 2namespace Acme\DemoBundle\Entity;
 3
 4use Doctrine\ORM\Mapping as ORM;
 5
 6use Oro\Bundle\EntityConfigBundle\Metadata\Annotation\Config;
 7use Oro\Bundle\EntityConfigBundle\Metadata\Annotation\ConfigField;
 8
 9/**
10 * @ORM\Entity
11 * @Config( # entity default configuration
12 *      routeName="acme_product_index", # optional, used to represent entity instances count as link
13 *                                      # in EntityManagement UI
14 *      routeView="acme_product_view",  # optional
15 *      defaultValues={
16 *          "entity"={ # entity configuration scope 'entity'
17 *              "icon"="icon-product" # default icon class which will be used
18 *                                    # can be changed via UI
19 *          },
20 *          "dataaudit"={ # entity configuration scope 'dataaudit'
21 *              "auditable"=true # will enable dataaudit for this entity
22 *                               # if not specified will be false
23 *                               # but you will be able to enable audit via UI
24 *          },
25 *          # ...
26 *          # any other entity scope default configuration
27 *          # ...
28 *      }
29 * )
30 */
31class Product
32{
33    /**
34     * @ORM\Column(type="string")
35     */
36    private $title;
37
38    /**
39     * @ORM\Column(type="string")
40     * @ConfigField( # field default configuration
41     *      defaultValues={
42     *          "dataaudit"={
43     *              "auditable"=true
44     *          },
45     *          # ...
46     *          # any other entity scope default configuration
47     *          # ...
48     *      }
49     * )
50     */
51    private $price;
52}

Now, every time a product’s price is modified, the changes are logged in the database. The logging manager not only stores the data being modified but also logs a set of related information:

  • The action corresponding to the operation performed by the Doctrine ORM (one of create, update and delete);

  • The modified entity’s class name

  • The current date and time

  • The user performing the change

  • A string representation of the modified entity. If the entity class implements a __toString() method, the return value of this method is used. Otherwise, the class name is used.

Each entity object gets its own history. Therefore, changesets get version numbers starting with 1. Each time a new changeset is created, a new version number is created by incrementing the highest existing version number for a particular entity by one.

Browsing the Change History

The DataAuditBundle ships with a controller that gives you access to the history of particular entities through your web browser. By default, the route path of the controller is /audit/history/{entity}/{id}/{_format}. For example, if you want to view the history the product with id 5, you’ll use the route path /audit/history/product/5. If you don’t specify a format, the bundle will try HTML by default. You can override the path by providing your own definition for a route with id oro_dataaudit_history.

API

Along with browsing the audit history with your web browser, you can also access the data being stored via an API which provides methods to receive your stored results via REST API.

Both variants provide methods to retrieve:

  • A list of all audit log entries

  • A single audit log entry

To retrieve a single entry, you need its id which must be extracted from the list of log entries.

Note

The audit log entry id isn’t related to any of the entities being watched.

REST API

The two REST API endpoints are controlled by the oro_api_get_audit and oro_api_get_audits routes:

Route

Path

Use case

oro_api_get_audits

/api/rest/{version}/audits.{_format}

Retrieve all audit log entries

oro_api_get_audit

/api/rest/{version}/audits/{id}.{_format}

Retrieve an audit log entry

Currently, JSON is the only format being supported which will also be chosen by the API controller if you omit it. Use the special latest value to access the most recent version of the API. At the moment, this is equivalent to v1 which is the only available version.