Setting Up Update Tracking

Update Tracking is a feature available in NXT 4.2 or higher. It provides publishers with the ability to track which updates a given user has downloaded and applied. It is particularly userful to corporate publishers who must track compliance and/or ensure that their users are current on corporate documents. Update tracking is also potentially useful to commercial publishers who wish to track customer update patterns.

Update tracking only provides a record of which content collections and versions are on the client system. To provide a compliance record that gives the exact text history, publishers must back up each collection version distributed.

Use this document to:

Set up the update tracking server.
Test the update tracking server.
Enable update tracking for NXT libraries.
Understand uploaded library tracking reports.

Set Up the Update Tracking Server

To set up the Update Tracking Server to receive Update Tracking reports:

Copy the following files from Builder\bin\Update Tracking Server Samples to an appropriate scripts folder on your Update Tracking Server machine. (The Update Tracking Server may be the same machine as your Update Server).
---TrackReportSample.asp
---TrackReportTest.asp
If desired, modify the TrackReportSample.asp LOG_FOLDER variable to specify a different target folder.
Create the target folder, matching the name and path specified in LOG_FOLDER variable. Make sure that this folder has the appropriate write permissions. (The IWAM_USER should have read and write permissions.)

Library Installer will only send tracking information for libraries that have been enabled with Report URL (see Library Manager help for more information).

Test the Update Tracking Server

Use the TrackReportTest.asp file to test the Update Tracking Server: Access the TrackReportTest.asp file through a browser (such as http://localhost/scripts/TrackReportTest.asp), enter any information for the test report, and submit the test report.

A log file should be written to the folder you specified in the LOG_FOLDER variable in the TrackReportSample.asp page.

Enable Update Tracking for an NXT Library

To enable update tracking for an NXT library, you must set a update tracking server to Library Manager. This setting is then propogated to the library.libinst file, which you distribute with your library or via your update server.

To set the update tracking for a library:

Open your library in Library Manager and view the Library Properties grid.
In the Content Update Servers property field, click the "(List of Update Servers)" property value and then click the "..." browse button. The Edit Content Update Servers dialog appears, which contains a list of web servers that your clients can use to obtain updates for the content in your library. The update servers listed for a library allow end users of the library to automatically update their content.
In the update server list, select the update server for which you are setting up Update Tracking.
In the Report URL field (in the properties grid), enter the complete URL where you want the update tracking report sent. For example, if your update tracking server was "MyUpdateTracking.com," then you would enter the URL:
http://MyUpdateTracking.com/Scripts/TrackReportSample.asp
Build the library (even if the content hasn't changed) to propagate the changes.
Post the updated library.libinst file to your Update Server. The next time a user downloads an update, they will receive this new library.libinst and will start uploading their library tracking files to your update tracking server.

Understand Uploaded Library Tracking Reports

Tracking reports are XML files, which gives you great flexiblity in how your process them. The files are sent via a FORM POST, so you may more easily trap them in a database application.

The sample Update Tracking Server application simply writes the uploaded update tracking files in the LOG_FOLDER specified in the TrackReportSample.asp file.

If you desire a more sophisticated application to place information from update tracking reports (UTR) in a database or to analyze them for users who are not up to date, you must develop your own update tracking server application or contract with Rocket Professional Services or a Rocket Busines Partner.

This section shows a sample LibTrack.xml file and explains some of the fields.

Sample LibTrack.xml file

   <?xml version="1.0" ?>
   <LIBTRACK xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <REPORTTIME>2003-11-11T22:58:40.0000000-07:00</REPORTTIME>
      <USER>
         <NAME>John.Smith</NAME>
         <DOMAIN>ROCKET</DOMAIN>
      </USER>
      <LIBRARYSTATE>
         <ID>764db0e1-99be-421c-ac64-8d3a04d3dbae</ID> (library ID, not folder id)
         <PUBLISHER>Publisher Name</PUBLISHER>
         <Title>My Library</Title>
         <STATUS>Updated</STATUS>
         <TIME>2003-11-11T22:58:07.0000000-07:00</TIME>
         <COLLECTIONS>
            <COLLECTION>
               <ID>10.1048/NXT4/4.2/Docs</ID>
               <FILENAME>mycc.nfo</FILENAME>
               <VERSION>3090482906.7</VERSION>
               <UPDATETIME>2003-11-11T22:40:06.0000000-07:00</UPDATETIME>
               <STATUS>Updated</STATUS>
               <TIME>2003-11-11T22:40:06.0000000-07:00</TIME>
            </COLLECTION>
            <COLLECTION>
               <ID>10.1048/NXT4/4.2/Docs2</ID>
               <FILENAME>mycc2.nfo</FILENAME>
               <VERSION>3090482908.5</VERSION>
               <UPDATETIME>2003-08-31T01:35:06.1340000-07:00</UPDATETIME>
               <STATUS>Not licensed</STATUS>
               <TIME>2003-11-11T22:57:04.0000000-07:00</TIME>
            </COLLECTION>
         </COLLECTIONS>
      </LIBRARYSTATE>
   </LIBTRACK>

Field explanations

Field Explanation

<LIBRARYSTATE> Shows the current state of library and collections as <TIME> field.

<VERSION> The version of the collection currently installed (including updates) on the client's NXT system. The number to the left of the decimal is the unique collection file version. This will not change unless a collection is completely rebuilt. The number to the right is the version number of the given collection. The original collection is numbered 1. Each number after that indicates an update, with the first update being numbered 2.

<UPDATETIME> Shows the time the indicated collection version was installed to the client's NXT system. This time will not change unless a collection is installed new or a version update is actually applied to the collection.

<TIME> The time that the library or collection status was reported. This may be the same as the <UPDATETIME> if the status is Installed or Updated.

Possible "Status" Values for <LIBRARYSTATE>

In the sample file provided, notice that the <LIBRARYSTATE> field has a <STATUS> section. In the sample, the status value is set to "Updated." Every tracking report sent will report the status for the complete library. The possible status values for the library are:

None
Installed
Updated
UpdatedPartialCancelled
Removed

Possible "Status" Values for <COLLECTION>

In the sample file provided, notice that the <LIBRARYSTATE> field has a <COLLECTIONS> section. Under the <COLLECTIONS> section are different subsections for each collection. Every tracking report sent will report the individual status for each collection (or .NXT file). The possible status values for each collection are:

None
Installed
Updated
FileNotPresent
NotLicensed
CheckedNoChange
Removed

Field	Explanation
<LIBRARYSTATE>	Shows the current state of library and collections as <TIME> field.
<VERSION>	The version of the collection currently installed (including updates) on the client's NXT system. The number to the left of the decimal is the unique collection file version. This will not change unless a collection is completely rebuilt. The number to the right is the version number of the given collection. The original collection is numbered 1. Each number after that indicates an update, with the first update being numbered 2.
<UPDATETIME>	Shows the time the indicated collection version was installed to the client's NXT system. This time will not change unless a collection is installed new or a version update is actually applied to the collection.
<TIME>	The time that the library or collection status was reported. This may be the same as the <UPDATETIME> if the status is Installed or Updated.