Using Document Access Tracking

This topic describes the Document Access Tracking module and using its capabilities.

Overview

The Cypress Document Access Tracking module provides a comprehensive solution for recording, extracting, and analyzing a wide variety of document viewing and delivery events that occur in your enterprise. You can use the information uncovered by the Document Access Tracking module to make your enterprise run more securely, efficiently, and economically.

The Document Access Tracking module is composed of a user interface element that enables it and an extraction program that enables you to export statistics from the DocuVault for conversion into comma-separated value (csv) files. You can open the csv file with a reporting/analysis application (e.g., Crystal Reports).You also can use the Cypress ODBC Driver to connect to the Cypress DocuVault through various reporting tools (e.g., ASG-Safari ReportWriter), which enables you to access Cypress information from other applications.

Enabling Document Access Tracking

The Document Access Tracking module allows you to record and extract a variety of document viewing and delivery statistics for further analysis. You can enable this feature from the Administration Tools module’s Parameter tab.

To enable the Document Access Tracking module

1. Open the Administration Tools module and select the Parameter tab.
2. From the Parameter tab, select the Statistics subtab, as shown in this example:

You can use this tab to enable tracking of these kinds of statistics:

•

Print statistics (proceed to step 3)

•

Inbox statistics (proceed to step 5)

•

View statistics (proceed to step 7)

3. To enable print statistics, select the Print Statistics check box.
4. Enter the desired print statistics retention time in the Retain For xx Days after JTIC Deletion input field. This value indicates how long Cypress should retain statistics associated with a particular job ticket. Cypress does not support decimal values in this field.

5. To enable Inbox statistics, select the Inbox Statistics check box.
6. Enter the desired Inbox statistics retention time in the Retain For xx Days after Document Deletion input field. This value indicates how long you wish to retain statistics associated with a particular document. Cypress does not support decimal values in this field.

7. To enable view statistics, select the View Statistics check box.
8. Enter the directory in which the log files should be created in the Log File Location input field.

9. Enter the size of the log file (in MB) in the Log File Size input field.

10. Click the Apply button on the button panel at the far right side of the application window. If you enabled view statistics, the directory that you specified in step 8 will be created.

Exporting and Converting Statistics

The Cypress Document Access Tracking module provides two classes of information: statistics related to printing and document delivery (i.e., Inbox activity) and statistics related to document viewing and access.

Extracting Statistics

The stat_prog utility is a .csv extraction program that enables you to extract print, Inbox, and view statistics for a specific date and time range. To execute this program, you specify the start and stop dates and times for statistics to be extracted as well as the destination directory to which the output is to be written.

•

If you are extracting Inbox statistics, stat_prog.exe creates the delivered_to_inbox.csv file and places it in the specified directory.

•

If you are extracting Inbox deletion statistics, stat_prog.exe creates the deleted_from_inbox.csv file and places it in the specified directory.

•

If you are extracting print statistics, the utility creates the print_completed.csv and stock_consumed.csv files and places them in the specified directory.

•

If you are extracting view statistics, the utility converts view statistics log files to CSV files and places them in the specified directory.

Although Cypress records all printing-related events in your output environment, you might find it helpful to understand when data is stored in a print statistics record so that you can more accurately interpret your statistical information.

Statistics are recorded for any event that begins within the specified date and time range, even if it actually completes after the specified stop time. Effectively, you indicate that you want to gather statistics for all events that began between specified start and stop dates and times.

When specifying dates and times, you can use either an absolute or relative format.

•

An absolute format specifies time as a specific hour, day, month, or year.

•

A relative format specifies time relevant to the current time (e.g., a month - 1, day - 5, hour - 12, etc.). If you are running stat_prog.exe from a batch program, you will want to specify time in a relative format.

For more information on using the time specification format, see the ASG-Cypress Knowledge Builder and Expression Criteria User’s topic.

If you will be extracting statistics for periods that span the occurrence of the daylight saving time change, consider specifying time in Coordinated Universal Time (UTC) format. This setting will avoid any ambiguity resulting from subtracting or adding hours due to the time changes. For example, a 20-minute job that began printing in the United States at 1:50 A.M. on the morning daylight saving time started will be recorded as stopping at 3:10 if you do not specify time in UTC format.

Converting View Statistics

The stat_prog.exe program allows you to convert view statistics log files from a Cypress-internal format into CSV files. To execute this program, include parameters in the command that indicate the type of statistics being converted, the path to the log files, and the file name of the CSV file to be created.

You can optionally add a time range using start and stop and specify doc_title to filter the responses to those matching the specified title, using wildcard characters.

Extracting Print Statistics

You can use the stat_prog utility to extract print statistics for a specified time range. This diagram shows the syntax for print statistics:

Print Statistics Fields

The stat_prog utility creates two comma-delimited files when you extract print statistics: print_completed.csv and stock_consumed.csv.

The print_completed.csv File

This topic provides the fields and event status codes for the print_completed.csv file, which is generated by the stat_prog utility.

Fields

This table describes the fields in the print_completed.csv file:

Col. No.	Field Name	Data Type	Width	Description
1	DocuVault Name	char	32	Name of the DocuVault containing the desired statistics
2	Print Serial Number	double		DocuVault-wide unique serial number identifying print attempt
3	Job Name	char	210	First level of the job ticket (JTIC) name
4	Job Ticket Name	char	210	Full JTIC name
5	Job Ticket Description	char	200	Description of the JTIC
6	User ID	char	64	JTIC owner
7	Reserved
8	Priority	double		JTIC priority
9	Reserved
10	Reserved
11	Device Name	char	32	Name of the device that processed the JTIC
12	Device Description	char	200	Description of the device
13	Device Type	char	32	Type of device (i.e., printer, RDM, etc.)
14	Device Printer Type	char	32	Type of printer (i.e., PostScript, PCL, etc.)
15	Link Type	char	32	Name of the device’s link DLL
16	Reserved
17	Constrained Device Name	char	32	Name of the device where the JTIC would have been queued if it had not violated a device constraint
18	Creation Timestamp	tstamp		Date and time at which the JTIC was created
19	Start Timestamp	tstamp		Date and time at which the JTIC started printing
20	Finish Timestamp	tstamp		Date and time at which the JTIC stopped printing
21	Event Status	int32		Enumeration indicating the status of this event, described in Event Status Codes.
22	Total Fail Count	int32		Cumulative number of failed print attempts
23	Data Byte Count	double		Number of data bytes sent to the device
24	Total Stock Sheets Printed	int32		Total number of sheets of stock printed
25	Total Production Pages Printed	int32		Total number of production pages—or faces—printed
26	Color Production Pages Printed	int32		Total number of color production pages printed to a color printer
27	Total Logical Pages Printed	int32		Total number of logical pages printed
28	Recipient Name	char	128	Name of the recipient to whom the JTIC was sent
29	Ad hoc address	char	128	Fax number, e-mail address, etc.
30	Banner Name	char	32	Name of the banner printed for the JTIC
31	Banner Recipient	char	32	Banner field: recipient
32	Banner Identity	char	32	Banner field: identity
33	Banner Address	char	32	Banner field: address
34	Document Title	char	200	Title of the document being printed
35	Document Creator	char	64	User who created the document
36	RDM Group	char	32	Report Distribution Manager (RDM) Report Group that generated the document
37	RDM Report	char	32	RDM Report that generated the document
38	RDM Subreport	char	32	RDM Subreport that generated the document
39	Document Logical Page Count	int32		Document size in logical pages
40	Document Production Page Count	int32		Document size in production pages
41	Document Format	char	32	Data format used to send the document via e-mail
42	Stock Match Flag	Boolean		1 if stock was matched; 0 if stock was ignored
43	DDoc ID	int32		DocuVault’s unique identifier for the document
44	Computer Name	char	32	Name of the computer that submitted the document for printing
45	Fax Number	string	32	The fax number to which the document was sent

Event Status Codes

This table lists the possible event status codes for the print_completed.csv file:

Code	Description
0	The job completed successfully.
1	An error occurred during connection or initial processing. No data was sent.
2	An error occurred during transmission. Some data was sent. Some pages might have been printed.
3	Transmission status cannot be determined. Some or all data might have been sent.
4	Operator Suspended—no data sent.
5	Operator Suspended—some data sent.
6	Operator Suspended—a job within a multi-JTIC job was suspended. Some data sent.

The stock_consumed.csv File

This table lists the fields in the stock_consumed.csv file contains these fields, which is generated by the stat_prog utility:

Col. No.	Field Name	Data Type	Width	Description
1	DocuVault Name	char	32	Name of the DocuVault containing the desired statistics
2	Print Serial Number	double		Unique DocuVault-wide serial number identifying print attempt
3	Stock Name	char	32	Stock upon which one or more production pages were printed
4	Sheet Count	char	32	Number of sheets consumed

To extract print statistics for a specified time range

1.

Create a directory on the Cypress Server for your print statistics files. The stat_prog utility will write the print statistics files to this directory.

If the print_completed.csv and stock_consumed.csv files already exist in this directory, the stat_prog utility will overwrite them. If you need to retain the statistical information in existing files, rename them or back them up to another directory.

2.

Execute the stat_prog utility. You can run this program manually from a command prompt window or automatically from a batch file. See Enabling Document Access Tracking for a full list of stat_prog parameters. A typical command to extract print statistics data might look like this:

C:\Cypress\Server\stat_prog.exe dir=“d:\cypress_stats”

start=tstamp(2002,09,01,17,00) stop=tstamp(2002,09,30,17,00) timezone=local type=print

3.

Check the stat_prog return code to verify that the program executed without error. You can check the code by examining the event log.

This table lists the possible return codes and their meanings:

Return Code	Description
0	Successful Completion
1	Document Access Tracking Module Not Licensed
2	Invalid Syntax or Missing Required Item in Command
3	Unable to Open Output Files
4	Error When Querying DocuVault for Statistics
5	Error During Sort
6	Error in Input File
7	Error in Output File
99	Unknown Error

This table describes the parameters supported by the stat_prog utility:

Parameter	Function
csv_file	Specifies the name of the CSV file that you want to generate. You must use an extension of .csv in the name of this file. Supported only for view statistics.
dir	Specifies the directory to which you want to save statistics. You can set this parameter to an absolute file path or a path relative to the Cypress\Server directory. Supported only for print and Inbox statistics.
heading	Adds a heading record at the beginning of the file. This heading provides the names of the columns. If you are creating a file that will be read by a program (e.g., Crystal Reports), do not include a heading in the file.
input_files	Specifies the path and name of the view statistics log file that you want to convert to a comma-separated value file. You must use an extension of .cdb in the file name. You can specify an absolute file path or a path relative to the Cypress\Server directory. Supported only for view statistics.
start	Specifies the beginning of the period for which you want statistics to be extracted. You must use Cypress’s date and time specification format when you set this parameter. Supported only for print and Inbox statistics.
stop	Specifies the end of the period for which you want statistics extracted. You must use Cypress’s time specification format when you set this parameter. Supported only for print and Inbox statistics.
timezone	Specifies the time zone of the timestamps that Cypress writes to the print statistics files. You can set this parameter to utc (for UTC format), local (for the time on the local machine), or server (for the time on the Cypress Server). Supported only for print and Inbox statistics.
type	Identifies the type of statistics you want to extract. You can set this parameter to print, inbox, or view.

Extracting Inbox Statistics

This table describes the fields in the delivered_to_inbox.csv file generated by the stat_prog utility. They are listed in sequential order by column number.

Col. No.	Field Name	Data Type	Width	Description
1	DocuVault name	char	32	The name of the DocuVault that contains the recipient Inbox
2	Document ID	int32		The Cypress Document ID (DDOC ID) of the content
3	DDOC Dbase	char	32	The name of the DocuVault that contains the document
4	Document Title	char	200	Title of the document
5	Document Creator	char	64	User who created the document
6	Document Logical Page Count	int32		Document size in logical pages
7	Document Production Page Count	int32		Document size in production pages
8	RDM Group	char	32	RDM Report Group that generated the document
9	RDM Report	char	32	RDM Report that generated the document
10	RDM Subreport	char	32	RDM Subreport that generated the document
11	Document Ticket Name	char	210	Full document ticket name
12	Recipient Name	char	128	Recipient to whom the document ticket was sent
13	Inbox Name	char	256	Recipient Inbox to which the document ticket was sent
14	Document Ticket Creator	char	64	User who created the document ticket
15	Computer Name	char	32	The name of the computer that submitted the document for printing
16	Creation Timestamp	tstamp		Date and time at which the document ticket was created

To extract Inbox statistics for a specified time range

1.

Create a directory on the Cypress Server for your Inbox statistics file.

The stat_prog utility will write the delivered_to_inbox.csv file to the directory.

2.

Execute the stat_prog utility.

You can run this program manually from a command prompt window or automatically from a batch file. See Enabling Document Access Tracking for a full list of stat_prog parameters.

This is an example of a typical command to extract Inbox statistics data:

C:\Cypress\Server\stat_prog.exe dir=“d:\cypress_stats” start=tstamp(2002,09,01,17,00)

stop=tstamp(2002,09,30,17,00) timezone=local type=inbox

3.

Check the stat_prog return code by examining the event log to verify that the program executed without error.

This table describes the possible return codes:

Return Code	Description
0	Successful completion
1	Document Access Tracking module not licensed
2	Invalid syntax or missing required item in command
3	Unable to open output files
4	Error when querying DocuVault for statistics
5	Error during sort
6	Error in input file
7	Error in output file
99	Unknown error

Extracting Inbox Deletion Statistics

This table describes the fields in the deleted_from_inbox.csv file generated by the stat_prog utility. They are listed in sequential order by column number.

Col. No.	Field Name	Data Type	Width	Description
1	DocuVault name	char	32	The name of the DocuVault that contains the recipient Inbox
2	Document ID	int32		The Cypress Document ID (DDOC ID) of the content
3	DDOC Dbase	char	32	The name of the DocuVault that contains the document
4	Document Title	char	200	Title of the document
5	Document Creator	char	64	User who created the document
6	Document Logical Page Count	int32		Document size in logical pages
7	Document Production Page Count	int32		Document size in production pages
8	RDM Group	char	32	RDM Report Group that generated the document
9	RDM Report	char	32	RDM Report that generated the document
10	RDM Subreport	char	32	RDM Subreport that generated the document
11	Document Ticket Name	char	210	Full document ticket name
12	Recipient Name	char	128	Recipient to whom the document ticket was sent
13	Inbox Name	char	256	Recipient Inbox to which the document ticket was sent
14	Deleting User	char	64	User who deleted or restored this document ticket
15	Deleting Machine Name	char	32	The name of the computer that executed the delete/restore
16	Deletion Timestamp	tstamp		Date and Time when the document ticket was deleted/restored
17	Type	char	25	The type of record, which will contain Sent to Recycle Bin, Restored from Recycle Bin, or Deleted from DocuVault

To extract Inbox deletion statistics for a specified time range

1.

Create a directory on the Cypress Server for your Inbox deletion statistics file.

The stat_prog utility will write the deleted_from_inbox.csv file to the directory.

2.

Execute the stat_prog utility.

You can run this program manually from a command prompt window or automatically from a batch file. See Enabling Document Access Tracking for a full list of stat_prog parameters.

This is an example of a typical command to extract Inbox statistics data:

C:\Cypress\Server\stat_prog.exe dir=“d:\cypress_stats” start=tstamp(2002,09,01,17,00)

stop=tstamp(2002,09,30,17,00) timezone=local type=inbox_delete

3.

Check the stat_prog return code by examining the event log to verify that the program executed without error.

This table describes the possible return codes:

Return Code	Description
0	Successful completion
1	Document Access Tracking module not licensed
2	Invalid syntax or missing required item in command
3	Unable to open output files
4	Error when querying DocuVault for statistics
5	Error during sort
6	Error in input file
7	Error in output file
99	Unknown error

 

Extracting View Statistics

This diagram shows the syntax for view statistics.

This table describes the fields in the comma-separated value file generated by the stat_prog utility. They are listed in sequential order by column number.

Col. No.	Field Name	Data Type	Width	Description
1	User name (domain/user)	char	259	The domain name and user name of the person who viewed the file’s content
2	Machine name	char	259	The name of the machine where content was viewed
3	IP Address	char	15	Not yet implemented
4	DocuVault name	char	32	The name of the DocuVault from which content was accessed
5	Document ID	int32		The Cypress document ID (DTIC) of the content
6	Document Title	char	203	The title of the viewed document
7	Source type	int32		The source location from which content was viewed: • 0: unknown • 1: web inbox • 2: web query • 3: UI inbox • 4: UI query • 5: UI EOM • 6: Cypress Server Page • 7: CPF • 13: Thin Client
8	Usage type	int32		How content was used: • 0: unknown • 1: viewing • 2: printing through local printer driver • 3: printing through Cypress printer • 4: export as file • 5: processing the page (CPF)
9	Source information	char	259	The name of the DocuVault, Recipient, and Inbox if the Source Type = 1 or 3 The name of the DocuVault, Printer, and JTIC if the Source Type = 5
10	Start timestamp	tstamp		The time at which viewing began (i.e., the content was opened for viewing). The time stamp is in this form: yyyy-mm-dd hh:mm:ss.
11	End timestamp	tstamp		The time at which viewing ended (i.e., the content was closed). The time stamp is in this form: yyyy-mm-dd hh:mm:ss.
12	Page numbers	char	variable	The pages that were viewed.

To extract view statistics for a specified time range

1.

Create a directory on the Cypress Server for your view statistics files.

The stat_prog utility will write comma-delimited view statistics files to this directory.

2.

Copy the stat_prog.exe file from the Cypress\Server directory to the directory created in step 1.

3.

Move the view statistics log files from the Cypress Server to the directory you created in step 1. The log files are named in the format viewstat_fileXXXXXX.cdb, where XXXXXX is a number automatically assigned by Cypress.

4.

Execute the stat_prog utility.

You can run this program manually from a command prompt window or automatically from a batch file. See Enabling Document Access Tracking for a full list of stat_prog parameters.

This is an example of a typical command to extract view statistics data:

d:\stat_prog.exe input_files="d:\cypress_view_stats\viewstat_file000001.cdb"

csv_file="03_12_viewstats.csv" type=view

5.

Check the stat_prog return code recorded in the Event Log to verify that the program executed without error.

This table lists the possible return codes and their meanings:

Return Code	Description
0	Successful completion
1	Document Access Tracking module not licensed
2	Invalid syntax or missing required item in command
3	Unable to open output files
4	Error when querying DocuVault for statistics
5	Error during sort
6	Error in input file
7	Error in output file
99	Unknown error

Using the ODBC Driver to Extract Data

The Cypress ODBC Driver enables you to connect to the Cypress DocuVault through various reporting tools (e.g., ASG-Safari ReportWriter). This section discusses the Cypress ODBC Driver and how you can use this capability to access Cypress information from other applications.

ODBC is a standard database access application programming interface (API) that allows an application to access data in diverse database management systems (DBMSs) through a single interface. Accordingly, the Cypress ODBC Driver provides an interface between Cypress and other applications, enabling common access to the data stored in a DocuVault. It currently supports read‑only access to statistical information gathered by the Document Access Tracking module. For example, you could use ASG-Safari ReportWriter and the ODBC connection to access data in the Cypress DocuVault for reporting and/or analysis of statistical data.

The ODBC Driver installer is an option available when you perform a Typical installation of Cypress. You can modify an existing installation and select the ODBC Driver to add its installer to your Cypress installation. These are the ways you can update your ODBC Driver:

•

Modifying an existing installation to add the ODBC Driver

•

Upgrading or repairing your ODBC Driver installation

•

Uninstalling and reinstalling the components

See the ASG-Cypress ODBC and JDBC Programmer’s topic for more information on installing and using the ODBC driver.

Using Sample Crystal Reports with the Document Access Tracking Module

The Document Access Tracking module includes sample report files that you can open in Crystal Reports to give you quick access to frequently needed print and view statistics. ASG provides a schema file and these sample files only as a starting point; you can create your own custom reports to meet the specific requirements of your enterprise.

If you want to use one of the sample reports provided by Cypress, you must create and configure an ODBC data source for each type of statistics you want to analyze. When you launch Crystal Reports, you can associate your data source with the sample report. (The Crystal Reports installation package automatically downloads the Microsoft ODBC text driver.)

Sample Reports

This table describes the sample reports provided in Cypress with the Document Access Tracking module:

Report File	Type	Description
chargeback.rpt	Print	Total pages and sheets printed for each user in each department.
docs_by_ddocid.rpt	View	Documents viewed by DDOC ID.
docs_by_user.rpt	View	Documents viewed by each user.
email_by_user.rpt	Print	Documents printed to e-mail devices by each user.
fax_by_faxnum.rpt	Print	Documents sent to fax devices by fax number.
fax_by_user.rpt	Print	Documents sent to fax devices by each user.
pagesviewbyuser.rpt	View	Documents and pages viewed by each user.
prt_by_user.rpt	Print	Documents printed by each user.
stkbystkname.rpt	Print	Monthly stock consumption by stock name.
stkperdevice.rpt	Print	Monthly stock consumption by device.
stkperuser.rpt	Print	Monthly stock consumption by user.
subrepbyrecip.rpt	Print	Subreport per recipient.

To create ODBC data sources for both print and view statistics

1.

Create a directory in which you can store your comma-separated value text files and the schema.ini file.

If you plan to extract both print and view statistics, you must create two separate directories. The directories will ultimately contain the stat_prog-generated comma-delimited text files and the schema.ini file appropriate for the type of statistics you are analyzing.

2.

Copy to the new directory the schema.ini file located in the Cypress\Server\Samples\Statistics\odbc_text_driver directory and the comma-separated value text file(s) created by the stat_prog utility.

3.

On the system where Crystal Reports is installed, open the Control Panel by selecting Start  }  Control Panel.

4.

From the Control Panel window, open the Administrative Tools directory.

5.

Double-click the Data Sources (ODBC) icon to open the ODBC Data Source Administrator dialog.

6.

Select the User DSN tab, if it is not already displayed.

7.

Click Add to display the Create New Data Source dialog.

8.

Locate and select Microsoft Text Driver (*.txt, *.csv) from the listview.

9.

Click Finish to display the ODBC Text Setup dialog.

a.

Enter the name of the ODBC text data source in the Data Source Name field. The name you enter will be displayed when you open a report file in Crystal Reports.

b.

Optional. Enter a brief description of the data source in the Description field.

c.

Click Select Directory, and browse to the directory you created in step 1. .

The print statistics directory will contain these files:

–

print_completed.csv

–

stock_consumed.csv

–

schema.ini

The view statistics directory will contain these files:

–

viewstat_filexxxxxx.csv (where xxxxxx represents a number automatically assigned by Cypress)

–

schema.ini

d.

Click Options to reveal additional settings.

e.

Clear the Default (*.*) check box.

f.

Select *.csv from the Extensions List.

g.

If you do not plan to use the schema.ini file supplied by Cypress, click Define Format and configure the data source as appropriate for your custom report.

10.

Click OK.

11.

Repeat steps 1 through 10 for your second ODBC data source, if needed.

To open a Cypress sample report files Crystal Reports

1.

Create a directory to contain the supplied sample report files on the machine running Crystal Reports.

2.

Copy to the new directory the desired sample file(s) from the Cypress\Server\Samples\Statistics\Crystal_reports directory.

3.

Launch Crystal Reports, and the Welcome to Crystal Reports dialog opens.

 

4.

Click Open an Existing Report. Select More Files from the list.

5.

Click OK to see the Open dialog:

6.

Navigate to the directory you created in step 1. , and open the desired report.

7.

When you open the sample file, Crystal Reports will be in design view. Change the view by clicking the Preview toolbar button . The Select Data Source dialog displays.

8.

Select the name of the data source you created when configuring your ODBC text data source, and click OK.

The Select Directory dialog displays:

9.

Select All Files (*.*) from the Save file as type drop-down list. If you do not select All Files (*.*), the schema.ini file will not open and the report structure will break.

10.

Select the directory that stores the schema.ini and comma-delimited text files, and click OK.