INTRO
-----
This document contains the proposed plan for implementing the possibility to track changes made to objects, requested in bug 965 [1]. The initial bug report (by fcoulmier) has the following description:

"It would be awesome to have a change tracking system on the objects so that we can know what have been changed on them and by whom at what time.
I think it could be a new tab on each object, like you already did for IP addresses.
What I would like to know, for example is when we upgrade the amount of RAM of a server. Or When we switched it off. Or when we upgraded the operating system. Even, when we unpugged it from one switch and replugged it on another switch. Or when we changed its location from one rack to another.
Everything should be tracked so we have a better control on what has been done in our datacenter. Also, it would prevent us to restore DB each time we made an error in changing something on the object and don't remembering what it was.

Thank you"

At the time of writing, this bug refers to 2 additional bugs, namely 566 [2] and 891 [3]. These bugs respectively request the possibility to see old values when they are changed, and the possibility to see history logging when a VM has been moved to a different container.

This document contains a list of requirements in order to implement this feature, and a proposal for doing so.

[1] http://bugs.racktables.org/view.php?id=965
[2] http://bugs.racktables.org/view.php?id=566
[3] http://bugs.racktables.org/view.php?id=891


REQUIREMENTS
------------
1. Possibility to get a history log of changes made to an object
2. Be able to see when a change to an object was made
3. Be able to see who made a change
4. Be able to see what the old and new 'value' of a change are/were
5. Changes of values should remain making sence, even when referred objects/racks/etc. are removed from Racktables
6. The history tracking should be made generic enough to acomodate future additions to objects


SCOPE
-----
For the initial implementation of this feature, I would like to limit it's implementation to certain tabs in the object page, namely:

1. Properties
2. Rackspace
3. Ports
4. IP
5. NATv4
6. Tags

The design, however, should be extendible to be used for other tabs as well, though small changes could be necessary.


PROPOSAL
--------
I propose to use the current implementation of the Object properties 'history' portlet as a starting-point in terms of design, in the sense that we add a portlet to the bottom (or another optimal location) of every tab, containing the history of the values that are specific for that tab. I thinkt this works better than a seperate tab with all history, as the history could turn out to be quite a lot of information for a single page, with no obvious way to break it down further (unless we would create sub-tabs, or add a 'show all' button to get more than X history items of a certain category). Also, this breaks this implementation up in a couple of sub-projects, where we can give priority to implementing this feature to higher-demand tabs.

The history portlet fields should at least contain:

* Change time
* Author

This will cover requirements 2 and 3.

The rest of the fields depend on the tab, and will cover requirement 4:

1. Properties

* Attribute
* Old value
* New value

2. Rackspace

* Removed rackspace
* Added rackspace

3. Ports

* Interface name
* Attribute
* Old value
* New value

In case of added ports, the old value should indicate it is a new port. In case of removed ports, and new value should indicate the port is removed.

When linking, the same fields can be used, where the attribute is 'Remote object and port'. Adding and removing links will work the same way as with ports.

4. IP

* OS interface
* Attribute
* Old value
* New value

Adding and removing OS interfaces will work the same way as with ports.

5. NATv4

* Match endpoint
* Attribute
* Old value
* New value

Adding and removing NATv4 will work the same way as with ports.

6. Tags

* Removed tag
* Added tag


DATABASE DESIGN
---------------
We should create a new table to hold the object history. As this new feature will encompass all the existing features of the current implementation of object history, which is displayed at the bottom of the Properties-tab, I think we should remove that implementation, and migrate the data to the new implementation.

I propose, during the upgrade proces, we move the 'ObjectHistory' table to something like 'ObjectHistoryOld', and create a new table for this new feature. After that, we fill the new table based on entries in the old table, using a migration script, which will be part of the creation of this new feature.

The new database should hold the following columns:

- id INT(10) unsigned NOT NULL AUTO_INCREMENT (primary key)
- type_id INT(10) unsigned NOT NULL (reference to a numeric representation of the tab for which the objecthistory row is added)
- date datetime NOT NULL (date & time of change)
- user_id INT(10) UNSIGNED NOT NULL (reference to user ID who made the change)
- identifier CHAR(255) NOT NULL (used for interface name (ports), OS interface (IP) or Match endpoint (NATv4)
- attribute CHAR(255) NOT NULL (attribute that was changed)
- old_value CHAR(255) NOT NULL (old value or removed rackspace/tag)
- new_value CHAR(255) NOT NULL (new value or added rackspace/tag)

The identifier, attribute, old_value and new_value are currently CHAR(255), as their referenced fields in the database can also contain 255 characters.

The identifier, attribute, old_value and new_value should be textual, and not references to other tables, as most (if not all) of them could be removed/renamed in the future. For instance: when an interface was linked to the interface of another object, and we log this using the object_id and interface_id of the other object, we would loose the historic information when the referred object and/or interface are removed (as we can't tell what their name was anymore). This covers requirement 5.

The type_id column references to a semi-hard-coded numeric representation of the tab in question. This could be implemented the same way as with the Dictionary value of 'ObjectType', where the lower numbers are reserved for Racktables itself (ie. 1 for properties, 2 for rackspace, 3 for ports), and the higher numbers (ie. above 50000) can be used for folks who want to make local changes for their own racktables installation, and add a history implementation.

The setup of this structure should accomodate additional object-tabs that are set up in a similar way as the current tabs. Also, the multi-use for columns like 'old_value' and 'new_value' make it possible to adopt the same structure for future implementations as well. This covers the database part of requirement 6.


TECHNICAL DESIGN
----------------
To be determined...