Search for issues with a combination of filters and display the search results.

SYNOPSIS

evsearch [-n] [-i] [-c field1,field2, … fieldn] [-f myfile.txt] [-s skipcount] [-l pagelength] [-p reportID] [-T templatefile] [field1=value1[;value2[;valuen]]] [field2=value1[;value2[;valuen]]] … … [q]

evsearch -r [-n] [-s skipcount] [-l pagelength]

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

evsearch -d

DESCRIPTION

This command allows the user to search for issues that meet specified filter criteria, and displays results (field values) for issues that match the filter criteria. The user must provide both search criteria, and a list of fields to display. Note that any field selected must be on the detailed report layout for the business area and project currently selected, and that the user must have permission to read the fields.

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 fields values to use as search criteria. If the command line is terminated by the letter q, the search will be immediately executed. 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 must be 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.

A variety of formats are supported for searching date fields:

datefield=6/24/2003 Searches for a date equal to 6/24/2003
datefield=−6/24/2003 Searches for dates up to and including 6/24/2003
datefield=6/24/2003-6/30/2003 Searches for all dates between 6/24/2003 and 6/30/2003 inclusive

These formats may be used either on the CLI, or through the interactive menu.

Keyword searching is also supported through the CLI. On the command line, use the -k option, and provide one or more keywords as a space-delimited list. When performing a keyword search, all text fields in the issue are searched for occurrences of the keywords entered. When multiple keywords are entered, the search will return issues that match any of the keywords. For example:

evsearch -k ‘core stack’ q

will search for issues containing either the word ‘core’ or the word ‘stack’. Keyword search criteria must be specified on the command line. This option is not available through the interactive menu.

If a command line is not terminated with the letter q, evsearch will display a menu of all the fields available as search criteria, with each field identified by a number. After the menu is displayed, the user will see the prompt:

Enter number or q to submit:.

When a field number is entered, evsearch will prompt for the search value. If the field is a list, the list of available values for that list will be displayed.

After all desired search criteria have been entered, press q to exit the menu and submit the search query to ExtraView.

List of Fields to Display

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 /.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 of the user’s current Business Area and Project, 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, evsearch cannot display attachments. To view attachments, users may use the evfiles command.

If the file /.evsearch exists, and neither the -c option nor the -f option are 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 hash character (#) 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

-r Returns search results in XML format. When this option is specified, the -c, -f, -i, -p, and -T options are ignored
-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 /.evsearch is ignored.

Again, the fields selected must exist on the detailed report for the currently selected business area and project for the user
-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 /.evsearch, described above. When the -f option is used, the file /.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
-k “keyword1 keyword2 … keywordn” Allows the user to provide a space-delimited list of keywords to search for. When performing a keyword search, all text fields in the issue are searched for occurrences of the keywords entered. When multiple keywords are entered, the search will return issues that match all of the keywords
-n Causes the search to ignore case
-i causes the search to use the ExtraView data dictionary names and list value names, as opposed to the data dictionary titles and the list titles for the search. For example, there is a data dictionary field named STATUS that may have a title of ‘Status of Issue’. This field may have as one of its values a name of NEW that has a title of ‘Newly Submitted’. The following searches are synonymous:

evsearch -i status=NEW q
evsearch ‘Status of Issue=Newly Submitted’ q
-l pagelength causes the output to paginate pagelength records at a time. The default for pagelength is 10
-s skipcount causes the output to skip over ‘skipcount-1’ issues, and begin the report starting with record number skipcount
-d shows a list of available reports by Name (also referred to as Title), with their report ID’s. The report ID’s may be used with the –p option. When this flag is specified, all other flags are ignored
-p reportID by default, evsearch can only retrieve field data for fields that are on the system-wide Detailed Report. This option allows the user to specify an alternate Report, from which field data may be selected
-T templatefile allows the user to specify a server side template file to be used for formatting the output of the search.

NOTES

  • The output from evsearch may be piped to the evxmlc command, as an alternate method for formatting of the output
  • Keywords can be used as a name in the search although the name is not a database field. This is used to provide an unlimited number of keywords in a space-delimited list to ExtraView. When you enter a keyword for the search, all text fields in the issue record are scanned for occurrences of the keyword entered
  • If no records are returned by the search, the message “No records found.” will be displayed.

EXAMPLE 1

$ evsearch status=Open priority="Priority 1" q
--------
      ID: 12449
Priority: Priority 1
   Title: SM crashes when TMX allocates address
--------
      ID: 12446
Priority: Priority 1
   Title: My phone does not work
--------
      ID: 12426
Priority: Priority 1
   Title: Lever arm broken
--------
      ID: 12424
Priority: Priority 1
   Title: new color scheme inconsistent
4 records found.
$

EXAMPLE 2

The output from a search can be piped to the evxmlc command, to give control over the formatting of the output.

$ evsearch -r Status=Open q | evxmlc -c "ID(8),ASSIGNED_TO(-13),SHORT_DESCR(-48)"
Defect # Assigned      Title
-------- ------------- ------------------------------------------------
   10152 Don Powell    User interface does not refresh before menu is displayed
   10132 Don Powell    On pressing the enter key on the home page, nothing happens
   10120 Steve Hoydic  Architecture Diagram Needs Review
   10118 Jom Smith     There is a typo in the doc. On page 234
   10108 Don Powell    I found a problem with calculation on stairs
   10105 Dave Green    When the timer goes past zero, an error is generated
   10034 Don Powell    When you click on the Product edit box it throws an error

7 records processed.
$