Cloud Software Group, Inc. EBX®
Documentation > Reference Manual > Persistence
Navigation mode Documentation > Reference Manual > Persistence

# History

## Overview

History is a feature allowing to track all data modifications on a table (records creation, update and deletion).

It is an improvement over the deprecated XML audit trail.

##### See also

- History
- Replication
- Data model evolutions

## Configuring history

In order to activate historization for a table, a history profile has to be set for the table in the data model. This section describes history profiles and the way they are associated with tables.

### Configuring history in the repository

A history profile specifies when the historization is to be created. In order to edit history profiles, select Administration > History and logs.

A history profile is identified by a name and defines the following information:

- An internationalized label.

- A list of dataspaces (branches) for which history is activated. It is possible to specify whether direct children and/or all descendants should also be concerned.

Some profiles are already created when installing the repository. These profiles can neither be deleted nor modified.

Profile Id | Description
--- | ---
`ebx-referenceBranch` | This profile is activated only on the reference dataspace.
`ebx-allBranches` | This profile is activated on all dataspaces.
`ebx-instanceHeaders` | This profile historizes dataset headers. However, this profile will only be setup in a future version, given that the internal data model only defines dataset nodes.

### Configuring history in the data model

#### Activating table history

History can be activated on a table either through the data model assistant, or by editing the underlying data model.

To activate history by editing the data model, a history profile should be declared on the table using the `historyProfile` element.

    <osd:table>
    	<primaryKeys>/key</primaryKeys>
    	<historyProfile>historyProfileForProducts</historyProfile>
    </osd:table>

The data model assistant allows you to view the historization profiles defined in the repository.

Historization must be activated for each table separately. See model design documentation for more details.

#### Disabling history on a specific field or group

For a historized table, the default behavior is to historize all its supported elements (see Impacts and limitations of historized mode).

It is possible to disable history for a given field or group, either through the data model assistant, or by editing the underlying data model.

To disable the history of a field or group by editing the data model, use the element `osd:history` with the attribute `disable="true"`.

    <xs:element name="longDescription" type="xs:string">
        <xs:annotation>
            <xs:appinfo>
                <osd:history disable="true" />
            </xs:appinfo>
        </xs:annotation>
    </xs:element>

To disable the history of a field or group through the data model assistant, use the `History` property in the `Advanced properties` of the element.

When this property is defined on a group, history is disabled recursively for all its descendants. Once a group disables history, it is not possible to specifically re-enable history on a descendant.

##### Note

If the table containing the field or group is not historized, this property will not have any effect.

It is not possible to disable history for primary key fields.

### Integrity

If problems are detected at data model compilation, warning messages or error messages will be added to the validation report associated with this data model. Furthermore, if any error is detected, each associated instance (dataset) will be inaccessible. The most common error cases are the following:

- A table references a profile that is not defined in the repository.

- A history profile that is referenced in the data model mentions a non-defined or closed dataspace in the current repository.

##### Note

Deploying a data model on a repository that does not have the expected profiles requires the administrator to add them.

## History views and permissions

### Table history view

When the history has been activated on a table in the data model, it is possible to access the history view from various locations in the user interface: record, selection of records, table and dataset.

The next section explains how permissions are resolved.

For more information, see table history view section. To access the table history view from Java, the method `AdaptationTable.getHistory` must be invoked.

### Permissions for table history

Data permissions are also applied to data history. History permissions are resolved automatically as the most restricted permission between data permissions and read-only access right.

This is true for user-defined permission rules and also for programmatic permission rules.

When defining a programmatic rule, it may be required to distinguish between the functional dataset context and the history view context, either because the expected permissions are not the same, or because some fields are not present in the history structure. This is the case for dataset fields, computed values and fields for which history has been disabled. The methods `Adaptation.isHistory` and `AdaptationTable.getHistory` can then be used in the programmatic rule in order to implement specific behavior for history.

##### Note

There is currently a limitation when a table has a scripted permission rule on record specified: for security reason access to the table history is totally disabled for everyone. Access to history will be allowed in a future version.

### Transaction history views

The transaction history view gives access to the executed transactions, independently of a table, a dataset or a data model, directly from the user interface.

To see the 'Transaction history' table, navigate to the Administration area and select 'History and logs' using the down arrow menu in the navigation pane. Transaction history can also be accessed from the Dataspaces area by selecting a historized dataspace and using the Actions menu in the workspace.

For more information, see transaction history view.

### History service on the sidebar

Access a record's history view from the sidebar. This view shows a list of:

- transactions

- modified field values

- the user that modified the record

- timestamp

You can sort transactions by date and time, and filter them by field. History display supports both simple and complex data types, including multi-valued list types.

## SQL access to history

This section describes how to directly access the history data by means of SQL.

### Access restrictions

The database tables must be accessed only in read-only mode. It is up to the database administrator to forbid write access except for the database user used by TIBCO EBX®, as specified in the section Rules for the database access and user privileges.

### Relational schema overview

Here is a description of the history tables in the database.

The database schema contains (see also the diagram in the next section):

Common and generic tables | The main table is `HV_TX`; each record of this table represents a transaction. Only transactions that involve at least one historized table are recorded. These common tables are all prefixed by "HV".
Specific generated tables | For each historized table, a specific history table is generated. This table contains the history of the data modifications on the table. In the EBX® user interface, the name of this table in database can be obtained by clicking on the table documentation pane (advanced mode). All the specific history tables are prefixed with "HG".

### Example of a generated history table

In the following example, we are historizing a table called `product`. Let us assume this table declares three fields in EBX® data model:

Product

- productId: int

- price: int

- beginDate: Date

The diagram below shows the resulting relational schema:

Activating history on this table generates the HG_product table shown in the history schema structure above. Here is the description of its different fields:

- `tx_id`: transaction ID.

- `instance`: instance ID.

- `op`: operation type - C (create), U (update) or D (delete).

- `productId`: `productId` field value.

- `OproductId`: operation field for `productId`, see next section.

- `price`: `price` field value.

- `Oprice`: operation field for `price`, see next section.

- `beginDate`: `date` field value.

- `ObeginDate`: operation field for `beginDate`, see next section.

### Combination of operations

If several operations are combined in the same transaction, the operation field is resolved as follows:

- `C + U -> C`

  `D + U -> D`

  `D + C -> U`

  `C + D -> {} (no entry in history)`

### Values for operation fields

For each functional field, an additional operation field is defined, composed of the field name prefixed by the character `O`. This field specifies whether the functional field has been modified. It is set to one of the following values:

- `null`: if the functional field value has not been modified (and its value is not INHERIT).

- `M`: if the functional field value has been modified (not to INHERIT).

- `D`: if record has been deleted.

If inheritance is enabled, the operation field can have three additional values:

- `T`: if the functional field value has not been modified and its value is INHERIT.

- `I`: if the functional field value has been set to INHERIT.

- `O`: if the record has been set to OCCULTING mode.

## Impacts and limitations of historized mode

The history feature has some impacts and known limitations, which are listed in this section. If using historized mode, it is strongly recommended to read these limitations carefully and to contact Cloud Software Group, Inc. support in case of questions.

### Validation

Some EBX® data model constraints become blocking constraints when table history is activated. For more information, see the section Structural constraints.

### Data model restrictions for historized tables

Some restrictions apply to data models containing historized tables:

- Data model restrictions due to mapped mode

- Limitations exist for two types of aggregated lists: aggregated lists under another aggregated list, and aggregated lists under a terminal group. Data models that contain such aggregated lists can be used, however these lists will be ignored (not historized).

- Computed values are ignored.

- Linked fields are ignored.

- User-defined attributes on historized tables result in data model compilation errors.

Data model evolutions may also be constrained by the underlying RDBMS, depending on the data already contained in the concerned tables.

##### See also

- Data model evolutions

### Other limitations of historized mode

- No data copy is performed when a table with existing data is activated for history.

- Global operations on datasets are not historized (create an instance and remove an instance), even if they declare a historized table.

- Default labels referencing a non-historized field are not supported for historized tables.

  As a consequence, default labels referencing a computed field are not supported for historized tables.

  The workaround is to implement the `UILabelRenderer` interface and adapt the label computation for history.

- D3: the history can be enabled in the delivery dataspace of a primary node, but in the delivery dataspace of the replica nodes, the historization features are always disabled.

- Recorded user in history: for some specific operations, the user who performs the last operation and the one recorded in the corresponding history record may be different.

  This is due to the fact that these operations are actually a report of the data status at a previous state:

  - Archive import: when importing an archive on a dataspace, the time and user of the last operation performed in the child dataspace are preserved, while the user recorded in history is the user who performs the import.

  - Programmatic merge: when performing a programmatic merge on a dataspace, the time and user of the last operation performed in the child dataspace are preserved, while the user recorded in history is the user who performs the merge.

  - D3: for distributed data delivery feature, when a broadcast is performed, the data from the primary node is reported on the replica node and the time and user of the last operation performed in the child dataspace are preserved, while the user recorded in history is 'ebx-systemUser' who performs the report on the replica node upon the broadcast.

Documentation > Reference Manual > Persistence