history clause

modify [bus OBJECTID| connection ID|connection bus OBJECTID from|to OBJECTID 
relationship NAME] [add|delete] history [ITEM {ITEMS}];

You can add a customized history record through MQL to track certain events, either manually or programmatically. Two parts of the entry are definable: the Tag, and the Comment. The Tag appears at the beginning before the hyphen. Then the user/time/date/current stamp is automatically made, followed by the comment defined by the implementer. The MQL syntax for defining a history entry is:

modify bus OBJECTID add history VALUE [comment VALUE]; 
modify connection ID add history VALUE [comment VALUE];
modify connection bus OBJECTID from|to OBJECTID relationship NAME 
  add history VALUE [comment VALUE]; 

For example, the following command could be added to an MQL/Tcl program which backs up the database:

modify bus $OBJECT add history Backup comment Backup was completed to 
tape #12345;

The history entry for the above would look something like:

(Backup) - user: billy time: Mon Mar 30, 1998 11:28:15 AM Eastern Standard Time 
state: planned comment: Backup was completed to tape #12345.

All custom history event entries are enclosed in parentheses to distinguish them.

Custom history entries do not respond to the history off or set system history off commands.

System Administrators can execute the following command.

history off;

After this command is executed, events that occur on the local machine do not cause a history record to be logged in the database. This command affects only the local machine; concurrent user’s sessions are not affected. In addition, subsequent sessions on the local machine will have history enabled by default.

When history is set to off, modification dates continue to be updated if the business object is modified, including when using the delete history clause for the business object.

To enable history recording for the session again, a System Administrator should use:

history on;

MQL also allows history to be enabled or disabled with the use of a toggle command. Depending on the current setting, history can be enabled/disabled using the same command.

To enable/disable history as a toggle, a System Administrator should use:

history;

When the recording of history is turned off in a program object, it is important that it gets turned back on. While this can be done at the bottom of the program object’s code section, history recording is re-enabled automatically when a top-level program ends its execution even if the code is exited before reaching the command that turns it back on (either successfully or in error).

When used with the Studio Customization Toolkit MQLCommand class, an MQL session lasts for only the duration of one command and not throughout the Studio Customization Toolkit program’s session. This means that the history off command has no effect, since the MQL session ends and so history is turned back on. This is the design intent, to ensure that history is not inadvertently turned off for longer than intended.

If you would like to turn history off throughout the Studio Customization Toolkit program’s session, you can add a flag to the Context.start() method to turn history off for the duration of a transaction rather than only for the duration of one command. When you add this flag, all events that occur within the duration of a transaction will not record history. After the transaction commits, history is turned back on for the next transaction and you will need to explicitly turn history off again with or without the flag.

Since logging history affects performance as well as the size of the database, in some implementations it might be desirable to turn history off permanently.

The system history setting should not be issued within program objects, since it affects all users. In these cases, the temporary MQL history off command should be used instead.

Syntax

In addition, when using the above commands to print all information about a business object, set or connection, history records can be excluded.

You can also use history as select criteria when executing a temporary query. For example, this query selects all the history records for the specified business object:

temp query bus <TYPE> <NAME> <REV> select history ;

You can use the * wildcard with the name and revision. The results show all history records for all matching business objects. You can also select a specific element number in the history, for example:

select history[n];

!History Clause

When all information about a business object or connection is printed with the print commands listed above, everything about the objects or connection, including its history, is listed.

The !history clause allows you to exclude the history of a business object or connection, which can be quite lengthy, when printing all the other information. For example, the following command:

print bus Assembly RB45621 A !history;

Prints out all information about the business object except its history.

Syntax

To select history from a business object use the following syntax:

print bus OBJECT select history.ITEM [history.ITEM];

• OBJECT is the Type, Name, and Revision of the business object or its object ID.
• ITEM can be one of the following:

  between

  EVENT

  time

  user

  state

To select history from a connection, use one of the following:

• ITEM can be:

  EVENT

  time

  user

• ID is the identification of the connection as returned with the select connection ID print command.

The second command listed returns the history of all connections on the specified OBJECT.

History.Between Clause

The History.between clause can be used on a business object. It returns a subset of that business object’s history log when dates are included, or the entire history log when dates are not included.

history.between[FROMDATE|TODATE]

• The dates included must adhere to the date format of the system.
• If both FROMDATE and TODATE are provided, the list includes events that occurred between the 2 dates, inclusive of FROMDATE but exclusive of TODATE.
• If only FROMDATE is included, the list includes events that occurred between the date specified and the present date, inclusive of both FROMDATE and the present date.
• If only TODATE is specified, the list includes events that occurred before the date specified, exclusive of TODATE.

For example, this temp query using the generic date format:

temp query bus <TYPE> <NAME> <REV> select history.between[2017/02/23@22:38:00:GMT|2017/02/23@22:40:00:GMT];

For all matching objects, the history events that occurred within the specified times is displayed. If a matching object does not have any history events within that time period, the results show the business object name, but without any history events. The date format uses the system date format. For more information and help determining the format used on your system, see Installation and Setup: Administrate: 3DEXPERIENCE Platform: 3DSpace Administration: Live Collaboration Server: Configuring Live Collaboration: Configuring Date and Time Formats in the online user assistance.

History.Event Clause

The History.Event clause can also be used on a business object or connection. It returns a list of history records of the EVENT event type. For business objects, EVENT can be one of the following:

For a connection, EVENT can be:

Example 1

For example, if a user enters:

print bus Assembly PR6792 A select history.modify;

the following is output:

modify - user: patrick time: Mon Aug 6, 1998 5:50:11 PM state: Assigned description:  test
modify - user: sam time: Mon Aug 6, 1998 6:50:11 PM state: Assigned description:  test1
modify - user: diane time: Mon Aug 6, 1998 7:50:11 PM state: Assigned description:  test2
modify - user: ted time: Mon Aug 6, 1998 8:50:11 PM state: Assigned description:  test3

Example 2

If you want to find the date when a signature has been satisfied. Use a command similar to the following:

print bus ECR 000122 ""  select history.approve;

This command returns:

business  object  ECR  000122
history.approve = approve - user: Cole  time: Sun Sep 5, 1999  1:24:50 PM 
CDT  state: Approvals  signature: Scrap Approver 1   comment:  

If you have multiple signatures on specific states, you will have to parse the data for a particular date and signature.

Example 3

To return a list of customized history entries created with the add history VALUE [comment VALUE] clause of the modify bus command, use the custom event. For example:

print bus 2340988 select history.custom;

might return:

(Backup) - user: billy time: Mon Mar 30, 1998 11:28:15 AM Eastern Standard Time state: planned comment: Backup was completed to tape #12345.

Freezethaw is one event that can be selected and will return both freeze and thaw entries.

History.Time Clause

The History.Time clause can be used on a business object or connection to return a list of the timestamps of every history record. For example:

print connection 1234568 select history.time;

returns a list of the different times that the connection was updated in the database:

time: Fri, Jan 2, 1998  1;48:41 PM
time: Thurs, Feb 6, 1998 2:20:13 PM
time: Wed, April 8 1998 10:15:12 AM

History.User Clause

The History.User clause can be used on a business object or connection. It essentially gives a list of all users who have operated on the object or connection. For example, the following:

print bus Manual NewBook 1 select history.user;

Might output:

user: sue
user: tim
user: jerry

History.State Clause

The History.State clause can be used only on a business object or set. It returns a list of all states the object was in when operations were performed on it. For example:

print bus 2340988 select history.state;

Gives a list of all states the business object was in after every change to the business object:

state: Proposed
state: Assigned
state: Described

What You Can Delete

History records can be deleted based on:

• The type of event (for example, checkout, checkin);
• The user who performed the event (for example, angie);
• The date the operation took place (for example, on, before, or after a specified date).

In addition, all history records of a business object or connection can be deleted with one command. Users can optionally write the purged entries to a file. The purge history event itself is recorded in history.

While the various forms of the command provide flexibility and control over exactly which history records are purged, very complicated variations are not supported. This is to ensure that accidental deletions of important historical events do not occur. In other words, as the criteria for deletion becomes more complex, more delete history commands will be required.

In the History of an object, other objects are sometimes referred to. This is an issue if “Show” access has been denied for a particular user or object in the database. The performance impact of determining whether the current user has access to see the Type, Name and Revision of such objects would be significant and unavoidable. Individual history records can be deleted using the delete history clause of the modify businessobject or modify connection command. This can be used in action triggers to remove such records.

Delete History Clause

This clause can be used alone, or with other refining ITEM clauses. If there are no ITEMS specified, then all history records associated with the business object or connection are deleted. The syntax is:

modify businessobject OBJECT delete history [ITEM {ITEMS}];

modify connection ID delete history [ITEM {ITEMS}];

• OBJECT is the Type, Name, and Revision of the business object or its object ID.
• ID is the identification of the connection as returned with the select connection ID print command.
• ITEM can be from this list:

  event EVENT

  by USER

  | on | | before | DATE | after |

  | keep | last |

  output FILENAME

The keywords “keep” and “last” are mutually exclusive. Also, only one form of the DATE item is allowed in a single command.

For example:

modify bus Document PO567932 1 delete history;

Deletes all history records and adds a history entry similar to the following:

History Records Purged by ted on 11/9/98 12:02:03 PM.!!!

Event Clause

All history entries that log a specific event can be deleted from a business object or connection using the event EVENT item. EVENT is a database event that is logged in history. For business objects, EVENT can be from the following list:

EVENT for connections can be from the following list:

The purge history event record itself can be deleted; however, doing so will be generate a new purge history record.

A list of events can be specified, separated by a space and a comma. For example:

modify bus Document PO567932 1 delete history event changetype, changename;

Deletes all entries of these types. And:

modify connection 35894008 delete history event freezethaw;

Removes all freeze and thaw history entries on the connection. Freezethaw is one selectable EVENT.

To purge customized history entries created with the add history VALUE [comment VALUE] clause of the modify bus command, use the custom event. For example:

modify bus 2340988 delete history custom;

By User Clause

All history entries that log events performed by a particular user can be deleted from a business object or connection using the by USER item. USER is the person listed in the history entry as the user who performed the operation, and so is, or was, a valid person.

A list of persons can be specified, separated with a space and a comma. Also, the by USER clause can be used with or without the keyword by and with other ITEMS. For example, this command deletes the records of all events performed by either chris or tom from the object’s history:

modify bus Document PO567932 1 delete history by chris, tom;

This example deletes all changetype history events performed by either chris or tom.

modify bus Document PO567932 1 delete history event changetype by chris, tom;

Date Clause

History entries can be deleted from a business object or connection based on when the event occurred using one of the following DATE items.

on DATE

before DATE

after DATE

• DATE is the timestamp in the history entry, and can include the time of day, or just the date of the event. If the time of day is not included, then the input is considered a date. Otherwise the timestamp is taken into account.

For example:

modify bus Document PO567932 1 delete history date 11/04/98;

This example deletes the record of all events that occurred on November 4, 1998. On the other hand:

modify bus Document PO567932 1 delete history before “11/04/98 12:00:00 PM EST”;

This example deletes all entries for events that occurred before November 4, 1998 at 12:00:00 PM EST. The after keyword can be used in the same manner.

Quotes must be used when including the time of day in the DATE.

Dates and times can be entered in the command as specified in the initialization file. For more information about date and time formats, see the Collaboration and Approvals Administration Guide: Properties for Configuring Calendars and Dates.

Date items can be used with or without the other ITEMS listed, but only one date item is allowed in a single command. For example:

mod bus Document PO567932 1 delete history event checkin by sue after 3/17/01;

Only one date ITEM is allowed in a single command.

Keep Item

The keep item clause is used with the other ITEMS and provides a way of reversing what is specified. The ITEMS that follow keep, are not deleted, but all other records are. The one exception is that any purge history records are always kept.

In addition to what is specified with the keep clause of the delete history command, purge history entries are always kept, unless all history is deleted.

Keep can be used with any of the other ITEMS except last , but it must be specified immediately following the delete history clause. For example:

modify bus Document PO567932 1 delete history keep event create;

This example deletes all records except the creation (originated) entry.

modify bus Document PO34675 1 delete history keep event checkin by bill on 
November 5, 1998;

This example deletes all records except those for checkin events performed by bill on the date specified.

When used, keep must be specified immediately following the delete history clause, and cannot be used with last.

Last Item

The last item clause is used with the other ITEMS (except for keep) to purge the most recent history records that meet the criteria. When used, last must be specified immediately following the delete history clause. For example:

modify bus Document PO34675 1 delete history last event checkin by bill;

This example deletes only one entry - for the last checkin event performed by bill.

When used, last must be specified immediately following the delete history clause, and cannot be used with keep.

output FILENAME item

The purged history entries can be written to a text file using the output FILENAME item. In this manner, history can be archived. FILENAME is the name of a file to create with the purged history records. Optionally, a directory path can be included.

For example:

modify bus Document PO34675 delete history event checkin output history.txt;

deletes all “checkin” records and stores them in the file “history.txt.” The file will be saved in ENOVIA_INSTALL unless a path is specified. For example, on a PC, the following could be used:

modify bus Document PO34675 delete history event checkin output “d:\archive\history.txt”;

On UNIX it might be:

modify bus Document PO34675 delete history event checkin output “/home/archive/history.txt”;

• Every time a purge is performed for either business objects or connections, a history record is added that says:

  history = purge - user: USER time: TIMESTAMP 'History Records Purged'

  These purge entries are deleted only when all history is deleted, or when explicitly deleting them, with something like the following:

  modify bus Document PO34675 1 delete history event purge;

  However, if you use the keep clause to save all “modify” records, for example, all “modify” and “purge” records will actually be kept.

• If no items are specified, then all history records associated with a business object or connection are purged, including any purge history entries.
• Once history records are purged, they are completely deleted from the database. So a system administrator should take extra care before purging records. If the output clause is used, the text file could be checked into an object, but entries cannot be imported back into the history log.
• History deletion operations cannot be strung together into one single command. For example, the following command is not supported:

  modify bus TYPE NAME REVISION delete history event lock keep event lock by Jo;

  The delete history clause has been kept as simple as possible, to ensure that unwanted deletions do not occur. To actually do something like the above, (delete only lock records but keep lock records performed by one user), a different selection criteria must be formulated and accomplished using more than one command.