TIBCO EBX®
Documentation > Reference Manual > Persistence
Navigation modeDocumentation > 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.

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:

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:

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 but the built-in administrator profile. Access for other users 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.

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

The diagram below shows the resulting relational schema:

scaphas

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:

Combination of operations

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

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:

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

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 TIBCO Software 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 evolutions may also be constrained by the underlying RDBMS, depending on the data already contained in the concerned tables.

Other limitations of historized mode

Documentation > Reference Manual > Persistence