Customer1377: How can I configure my Traction TeamPage server to automatically erase articles that have reached a certain age?

Title: How can I configure my Traction TeamPage server to automatically erase articles that have reached a certain age?

This article describes how to download and configure the Automatically Erase Old Articles plug-in with TeamPage 4.0 build 37 and later that can be configured to automatically erase articles that have reached a specified age.

Some notes about this plug-in:

The Automatically Erase Old Articles plug-in described in this article requires Traction TeamPage version 4.0 build 37, and will not run or work with earlier versions.
This plug-in requires explicit administrator setup beyond simple installation before it will actually take effect. But it uses the standard TeamPage capability to erase articles and their attachments. All versions of articles that are erased, including attachments, are destroyed. The data are not recoverable without resorting to an alternative physical backup of your TeamPage journal.
Although it is possible to filter which projects in your TeamPage journal will be targeted, there is no way to specify what articles will be erased at any finer-grained level. All articles and comments will be erased, regardless of their moderation status (published, draft, rejected, etc.) or other properties of the articles.
Article age is determined with respect to the post date of the original version of the article. Therefore, for example, if you is configured this feature to automatically erase articles older than one year, even if an article was updated last week, it will be erased one year from its original posting.

Please consider carefully whether you really want to erase older articles automatically. You may, for example, prefer to use Traction's moderation features to reject or hide articles selectively, or erase specific articles manually.

You can also use Traction's ability to present any time slice (month, quarter, year) to allow older information to "roll off" the front page automatically while retaining the ability to find older information by searching or rolling back to an earlier time slice using the built in calendar control.

Unless you have a regulatory or contractual requirement to erase information older than a certain date we recommend that you keep your Traction Journal intact and use editing, selective erasure and Traction's time slice navigation instead of erasing older articles.

Downloading and Installing the Plug-in

Note that before you proceed, your user account must have "Server Setup" permission on the Traction TeamPage server in order to install and configure this plug-in.

Please download the plug-in ZIP package from its standard TeamPage 4.0 plug-ins library location, teampage.traction…

For other versions in the future, please look in the appropriate sub-folder in the teampage.traction… folder.

The plug-in should be installed from the Server Setup | Plugins page. If you are not running Traction TeamPage version 4.0 build 37, you will see that the plug-in is not enabled even after you have installed it:

You can download the latest version of TeamPage from download.traction… -- please be sure to select the correct version for your platform and operating system.

If you are running the required version or later, you will something like this instead:

Configuring Automatic Old Article Erasure

This feature works using TeamPage's support for daemon processes. These are tasks that run in the background at specified intervals. If you visit the Server Setup | General page after installing the plug-in package, you will see that you have a new daemon:

Although the daemon is enabled, it will have no effect until it is configured. On Server Setup | Plugins page, you can click the title of the plug-in to open the configuration editor.

Enable

Don't turn this on yet; please read this entire article first. This setting is a basic on/off switch for the daemon. Until it is set to "yes", even though the daemon is installed on the server and will be executed at the scheduled interval, it will have no effect. Turn this setting from "no" to "yes" last -- after you have ensured that the rest of your configuration is in place and has the intended effect.

Before you flip this switch to enable the feature, please read the "Testing Your Configuration" section below.

Maximum Article Age

This feature is built for organizations that would like to set a maximum age for articles in their TeamPage journal in accordance with a policy or preference. This setting allows the administrator to implement that policy by selecting the maximum age for articles on the server: articles older than the selected age will be erased. Until a maximum age is specified, this feature will have no effect even if the daemon has been enabled and the "enabled" setting has been set to "yes".

Target Projects

Not every project needs to be cleaned of old articles. Uncheck the "Use Default Value" checkbox and move projects from the "Don't Erase Old Entries" list to the "Erase Old Entries" list to indicate which projects' content should be considered for automatic erasure. As soon as a project is added to the "Erase Old Entries" list, its articles and comments will be eligible for automatic deletion. Until at least one project is explicitly targeted, no articles can be erased.

Log Message

Erasure operations are accompanied by a log message, usually a brief note explaining why the article or articles were erased. These settings allow you to choose the project in which the erase log message should be posted, and the content of the log message. Note that erasure log messages, including the ones created by the automatic erasures using this feature, will not be automatically erased.

Maximum Erasure Targets per Batch

Manually erasing old articles is not only time consuming; it can be costly in terms of resources on the computer where your TeamPage server is running. Since this feature automatically runs at intervals of 5 minutes, even if it erases only a relatively small number of articles at a time, it can easily catch up with your organization's policy on maximum information retention time without overtaxing your computer. The default number of articles to erase at a time is 5. The safe maximum value for this setting will vary from installation to installation, so if you need help calibrating this setting, please contact Traction support by posting an article to our Help project.

Erase as User

Since this feature uses Traction TeamPage's daemon framework, it must be run, as all daemon processes are, as a particular user. Use this setting to select the user account the process should run as. Be sure to choose a user account that has permission to erase articles in all the target projects you have selected above.

Testing Your Configuration

Since the "Automatically Erase Old Articles" daemon process will destroy the data in your journal, it is extremely important that before you finally enable the feature that you test it. You should also consider setting the "Enabled" feature from "yes" to "no" and re-testing each time you make another configuration change.

The first step to testing is to enable the appropriate debugging facilities on your TeamPage server. Please turn on debug logging, along with the daemon and erase debugging streams on the Server Setup | Server Files page's Debug tab.

After you have clicked the Apply button on the Server Files page, please click the View button on the Debug tab next to the drop-down list of current and archived debug log files, and navigate to the end of the file using the double right arrow button. If you have access to the console of the computer where your TeamPage server is running, you can tail or otherwise look at the contents of the debug.log file which should be located in the server/logs directory of your Traction TeamPage installation, e.g., C:\Program Files\Traction\traction\server\logs\debug.log.

Back on the Server Setup | Plugins page, launch the configuration dialog for the for the Automatically Erase Old Articles plug-in, and specify values for each of the settings described above, except the Enabled setting, which must remain set to no until you are finished testing. Keep the plug-in configuration dialog open after you make your changes to make it easier to tweak the configuration if necessary.

In a new browser window, you can now trigger your newly configured daemon in order to force it to report some details on its configuration which will allow you to confirm that it is going to target the appropriate projects and the appropriate age for articles. In a new browser window, you should enter the base URL for your TeamPage server plus the following:
/traction/read?daemon=eraseoldentries
e.g.,

teampage.example….

This will trigger the daemon so that you will not have to wait 5 minutes for the next time it runs automatically. In your debug log viewer, you should be able to click the two right arrows button to see the output for the daemon (or you can see it on your console). If there are gaps in your configuration, you may see messages like this:

[daemon Mon Oct 20 16:11:33 EDT 2008] [EraseOldEntries] No projects have been targeted.
[log Mon Oct 20 16:11:33 EDT 2008] localhost/127.0.0.1 (admin) requested /traction/read?daemon=eraseoldentries on port 8080

After you haveused the plug-in configuration dialog to correct any of these issues, you should see a block of messages like this:

[daemon Mon Oct 20 16:12:09 EDT 2008] [EraseOldEntries] Targeting 19691231190000-0500 to 20071020161209-0400 in the projects Private, Wiki
[daemon Mon Oct 20 16:12:09 EDT 2008] [EraseOldEntries] This daemon requires an administrator to explicitly enable it using the plug-in settings.
[log Mon Oct 20 16:12:09 EDT 2008] localhost/127.0.0.1 (admin) requested /traction/read?daemon=eraseoldentries on port 8080

The debug output tells us that the daemon did nothing, because we have not enabled it using the Enabled setting, but the first line tells us the date range and the projects that are targeted. In this case, with a maximum article age of 1 year, we can see that the date range ends one year before the current time -- in this case, that brings us back to 20071020161209-0400, or October 20, 2007, at 4:12:09 local (server) time. We can also see in our example that the Private and Wiki projects will be targeted. Please make sure that the time range and the projects match your expectations.

Final Activation

Only after you have tested should you flip the Enabled setting in the plug-in configuration editor from "no" to "yes".

Please understand that all entries that are older than the maximum age you have specified will be erased if you enable the feature. There is no way to recover any data erased in this fashion. If you keep backups of your TeamPage journal, which we strongly recommend, and can provide guidance in setting up, please ensure that your backup is up to date before proceeding.

If you switch this setting to "yes", it will be enabled, and articles older than the age you have specified will be automatically erased, starting with the newest articles that are old enough. (You may need to restart your server before the daemon scheduling is correctly initialized.) You may wish to leave the erase and daemon debug streams active for awhile, and to review the contents of the debug log file to ensure that the correct articles are being deleted; the erase debug stream will report what articles were actually erased, including intermediate versions, and will indicate the Traction ID of the erasure record, so that you can easily review your audit trail at any time. If you are satisfied that the feature is working as promised, you could shut off daemon and erase debug streams. You may also see other daemon and erase activity unconnected with this feature, such as FAST InStream indexing and manual erasures performed by users on your server.

Changing the Execution Delay

The current default is for the automatic erasure process to run every 5 minutes. If you need to change this, although it is not recommended you do so, you must first compute the number of milliseconds that are equivalent to the desired interval (e.g., x ms for 2 days = 1000 ms/s * 60 s/min * 60 min/hr * 24 hr/day * 2 day = 172,800,000 ms. Next, you must find the server/plugins directory in you TeamPage installation directory, e.g., C:\Program Files\Traction\traction\server\plugins. You should open the file the com.traction.eraseoldentries/config/daemons/eraseoldentries.properties in a text editing program, such as WordPad or Emacs, and enter the number of milliseconds in place of the existing value of the "period" property, 300000, such as

# 300,000 ms = 5 minutes
#period=300000
# I like this time better
period=3000000

(In this example, we commented out the old value and made a whole new line for our own "period" property; and we added a comment using the # syntax.)

It is not recommended that you change this value; if you re-install this plug-in on your Traction TeamPage server, this customization will be overwritten. And in no event is it recommended to set this value lower than 300000 (5 minutes delay between processing runs). This will ensure that your TeamPage server process remains does not run out of resources.

Attachments:

upgrade-required.jpg
plugins-page.jpg
daemon-configs.jpg
setting-enable.jpg
setting-age.jpg
setting-projects.jpg
settings-log.jpg
setting-max.jpg
setting-user.jpg
debug-logging.jpg

referenced by (1)

Customer1379: Changelog for TeamPage 4.000038

Article: Customer1377 (permalink)
Categories: :Doc:FAQ, :Doc:changelog
Date: October 20, 2008; 4:50:43 PM Eastern Daylight Time

Author Name: Dave Shepperton
Author ID: shep