Product Documentation

Display field data for issues modified since the specified date. The primary purpose of this command is to provide an efficient and convenient method of providing all the changed data since a specific date (and time), so that this data may be used to load another database, such as a company’s data warehouse. The options on the command allow the dumping of a specific field list, using a specific set of filters.

SYNOPSIS

evhist date [time] [-i] [-c field1,field2, ... fieldn] [-f myfile.txt] [-p reportID] [field1=value1[;value2[;valuen]]] [field2=value1[;value2[;valuen]]] ... ... [q]

DESCRIPTION

This command returns all field data (for which the user has read permission), for all issues that have been modified since the specified date, in XML format. The default list of fields that is dumped is the fields on the detailed report layout for the user’s current area and project. The list of fields can be modified by using your own field list as parameters to the command. In addition, you can set a set of filters. For example, you may return only the data for a specific business area, or for a specific product.

ID numbers, and ‘last modified’ dates are also returned for any issues that were deleted since the specified date.

The format for date and time within the output is not the current user’s own date / time format, but always uses the following format –

yyyy-MM-dd HH:mm:ss.SSS ZZZZ

As an example, this is a valid date and time to use to extract information from midnight on May 1st 2009 in the pacific standard time zone:

2009-05-01 00:00:00.0 PST

This ensures that a script created by one user can be used within other scripts and CRON jobs, so that many other users can share the output. It also ensures that the format for date and time is unambiguous and can be used by other systems that may read and interpret the XML in the command output. This format is also known as ExtraView internal timestamp format.

In using this command to output data for use within a separate data warehouse you should take care to prepare a list of the fields needed, as opposed to outputting all the fields. In most warehousing applications, you will not require the text area, log area and other similar fields within ExtraView, yet these fields may occupy more than 90% of the volume of data in an issue. The time to execute a data dump from ExtraView with the evhist command may be dramatically reduced if you only output the fields required in the warehouse.

Similarly, the filters you apply to the command allow you to only output the data for any specific criteria you require. Typically this will be for a business area, or project, but it may be any other segment of data, such as the data for a specific product.

Search Criteria

The user may specify search criteria in two ways, either on the command line, or through an interactive menu.

On the command line, the user may specify fields and field values to use as search criteria. If the command line is terminated by the letter q, the export will be executed immediately. If the command line does not terminate with the letter q, any search criteria specified on the command line will be passed along to the interactive menu, for additional filter criteria specification.

By default, command-line-specified fields must be identified by their Display Titles. For fields with a display type of List, values must be identified by their display titles. When the -i option is used, fields are identified by their fixed database names, and list values must be identified by their fixed names (for non-UDF lists), or by their internal list ID’s (for UDF lists). The evmeta command displays both of these list names for all list items.

A search may be performed for more than one value of a field by using a semi-colon to separate the values. For example:

STATUS=OPEN;FIXED;CLOSED

will search for issues with a status of Open, Fixed or Closed.

List of Fields to Export

There are three ways of specifying the list of fields to be displayed -

1. The -f option
2. The -c option
3. The existence of a file named $HOME/.evsearch (evsearch.txt on Windows). One of these three approaches must be used. If no field list is provided, no field data will be displayed.

By default, only fields on the Detailed Report layout for the user's current Business Area and Project, and to which the user has read permission, may be requested. You cannot request fields that do not appear on the detailed report for the currently selected business area, project and user role. However, the -p option may be used to specify a different report to be used as the source of field data.

Note: Even though attachments may be displayed on a report layout, evhist does not export attachments.

If the file $HOME/.evsearch exists, and neither the -c option nor the -f option is provided, evsearch will use the contents of this file as the list of field names whose values will be displayed. The format of this file is:

• This file may only contain printable, ASCII characters
• Tabs, spaces, and blank lines are ignored
• Only one field name may be placed per line
• Only fixed database names may be used
• Lines whose first non-blank character is a ‘#’ are ignored
• A line containing only the string, __END__ marks the end of the field list. This line, and all lines after this line in the file are ignored

OPTIONS

-c "field1, field2, ..., fieldn"

Allows the user to provide a comma-separated list of fields to be displayed, as command line options. Field names must be identified using the fixed database names. If the -f option is used in combination with the -c option, all the fields included in myfile.txt will be displayed in addition to the fields specified with the -c option. When the -c option is used, the file $HOME/.evsearch is ignored.

Again, the fields selected must exist on the detailed report for the currently selected business area and project for the user.

field1=value1[;value2[;valuen]]] [field2=value1[;value2[;valuen]]] ...

This is a set of name value pairs that specify the filters to be used as search criteria for the output. You may either have a simple name value pair, such as field1=value1, or you can use the longer form field1=value1;value2;valuen to set up a search that performs an "or" operation on all the values provided.

-f myfile.txt

Allows the user to specify a file that contains a list of all the fields to be displayed. The format of this file is identical to the format of the file $HOME/.evsearch, described above. When the -f option is used, the file $HOME/.evsearch is ignored. As with the -c option, the fields selected must exist on the detailed report for the currently selected business area and project for the user.

-p reported

By default, evhist only retrieves field data for fields that are on the Detailed Report. This option allows the user to specify an alternate Report, from which field data may be selected.

EXAMPLE