Adding History to Administrative Objects

Administrative objects are objects in the database that represent the definition of application data models (for example, business types, relationship types, attributes, policies, or formats). Object history is a set of records of changes that have been made to an object.

History records can be added to administrative objects automatically or explicitly. This capability enables apps and Administrators to record changes made to administrative objects for purposes of both maintaining an audit trail and identifying the source of a change.

This page discusses:

About History Records

History records are added to administrative objects as a result of any of the following events:

  • Object creation creates a history object marked “create.”
  • Object modification creates a history object marked “modify.”
  • Explicit use of the history keyword in MQL commands for adding or modifying administrative objects creates additional history records marked “custom.” The history keyword allows a free-text string describing the nature of some change to the object.

For each history entry, a persistent record is stored in the database that contains the following information:

  • The label “create,” “modify,” or “custom,” as described above
  • An integer index that specifies the order in which the history record was created
  • The user (current context) who performed the create or modify operation
  • The date and time to the nearest second
  • A descriptive string of up to 2,040 characters

For custom history that is explicitly added with the history keyword in add or modify admintype commands, the descriptive string is the string provided in the command.

For create or modify records that the system generates automatically, the descriptive string consists of the first 2,040 characters of the MQL command that creates the change. If the change is made through the business executable, the MQL command that is recorded as the descriptive string is the same as that generated for business scripting.

The MQL import or export command reads or writes, respectively, history records along with any administrative object.

Command-Line Interface for History Records

The Business graphical user interface does not support the display of history records. These are available only through the command-line interface.

To add a history record with the add command, use the following format:

add <admintype> NAME history STRING;

To add a history record with the modify command, use the following format:

modify <admintype> NAME history STRING;

History records are appended to the end of the output for print commands such as:

print <admintype> NAME;

The output format of print commands for admin objects with history records is as follows:

history index:1 type:custom user:creator date:Day Mmm dd, yyyy hh:mm:ss AM/PM ZONE text:xxx

In the above, <admintype> can be one of only the following types:

  • attribute
  • channel
  • command
  • dimension
  • form
  • format
  • group
  • index
  • inquiry
  • menu
  • page
  • person
  • policy
  • portal
  • program
  • relationship
  • resource
  • role
  • rule
  • site
  • table (system tables only - history does not apply to user tables)
  • type

The history keyword is not available for user-owned workspace objects, such as the following:

  • filter
  • query
  • set
  • table
  • toolset

Printing History for Administrative Objects

The print command for administrative objects supports a history selectable to request the printing of history records only. This command has the following syntax: 

print <admintype> NAME select history;

The format of the output of such a print command is as follows:

history type:custom user:creator date:Day Mmm dd, yyyy hh:mm:ss AM/AM ZONE text:xxx

There are no subselects for the history selectable. In other words, it is not possible to select subsets of history records.

If history records exist, you can print information about the objects without printing their history using either of these methods:

  • Use the print command with a select clause to select specific pieces of information, but do not include the history selectable:

    print <admintype> select ...

  • Use the print command with the history selectable negated to print the non-formatted, complete admintype definition, but with history suppressed:

    print <admintype> !history

Adding Multiple History Records

You can add multiple history records to the same or different objects in a transaction. Date and time are calculated at the time the history addition is requested. If a transaction involving history addition is aborted, the history record is not written.

History with MQL Import/Export Commands

MQL import or export commands read or write, respectively, history records along with any administrative object.

Localization of History Text Strings

The text string input for a history record is treated the same way as any other string attribute, specifically:

  • In a language-specific (in other words, non-UTF8) configuration, it is treated according to the system LANG setting.
  • In a multilingual UTF8 server environment, it is treated as a UTF8 string.

Extended History Records

By default, history records are truncated for description and string attribute changes. You can change this behavior using the following system command:

set system truncatehistory on|off;

When truncatehistory is on, the text is truncated at 254 bytes. This is the default behavior.

By turning the truncatehistory option off, you can store complete history records up to 3MB in the database. History records that exceed a predetermined length are stored in and retrieved from a separate database table. History records are written to either the lxHistory table or the lxDescription table based on length and the truncatehistory setting.

Once a history record has been truncated, turning truncatehistory off will not restore the information. Conversely, turning truncatehistory on will not truncate history records that have already been stored.