This API call allows you to search the ExtraView database and to return a set of records that match the search criteria. This function is equivalent to the search capability within the browser version of ExtraView. It is extremely powerful as multiple search filters can be set on different fields. For example, it is straightforward to set up a search that responds to a query such as “tell me all the open issues against a specific module within a specific product that contain a specific keyword.
SYNTAX
http://www.myserver.com/evj/ExtraView/ev_api.action?
user_id=username
&password=password OR [&access_token=token-value]
&statevar=search
&page_length=100
&record_start=1
&record_count=10
[&p_template_file=file.html]
&persist_handle=xxx
[&username_display=ID | LAST | FIRST]
&status=OPEN &module_id=WIDGET
&product_name=MY_PRODUCT
&keyword=wireless%20PDA
[&report_id=nnn]
. . .
For example, a return from a valid search may be as shown in the following XML:
|
<?xml version=”1.0″?> |
Note that if you do not have permission to view any of these fields, they will not appear in the output from the action.
This action purposely returns only a small number of fields from the database. If you require additional fields, you can parse the ID out of the returned information and then use the get action to read the remaining fields within the database.
You should be careful in your use of this action as it can conceivably return extremely large result sets to you.
NOTES
- The fields returned in the results correspond to the fields on the detailed report layout of the user’s current business area, current project and current role. However, if the behavior setting named REPORT_DTL_ITEM_DATA_LAYOUT is set to YES, then the detailed report for the user’s current role and the issue’s business area and project are used to define the fields being returned
-
The optional
access_tokenparameter allows you to use a valid OAuth2 token obtained with theget_tokencommand. If you provide theaccess_tokenparameter, then theuser_idandpasswordparameters should not be provided. This prevents the password being sent in clear text over your network connection -
All searches within text type fields are processed using a contains operator, not an equals operator. For example
&short_descr=problemreturns all records where theshort_descrfield contains the word problem, not just those where theshort_descrequals a value ofproblem - The keywords parameter is not a database field, but can be used to provide an unlimited number of keywords as search filters in a space-delimited list to ExtraView. Note that you must “escape” characters such as spaces in this list
- If you want to search for text contained within a text field, you can use a wildcard convention using asterisks (*) as the wildcards
- You can search using an inequality filter as a parameter. For example, &release!=1.2 used as a parameter will work
- You can search looking for null values in the results with a filter similar to &release={null} will search for all records with a null value in the field release
- The parameter named p_page_length is required and gives the ExtraView API the maximum number of records to return with one call. In conjunction with the parameter named p_record_start, you can build script functions to retrieve paginated results, if you believe your searches can bring up large number of records
- The parameter named p_record_start is required and gives ExtraView the number of the first record in the search results to display. In conjunction with the parameter named p_page_length, you can build script functions to retrieve paginated results, if you believe your searches can bring up large number of records
- You need to supply the parameter named p_record_count whenever p_record_start is greater than p_page_length
-
The parameter named p_template_file is optional. If it is not provided, ExtraView returns the results of the query in XML format. If it is provided, its value is the name of a server-side file that contains a template to format the results of the query. Using this template provides a means of formatting the output from the search command to a style of your own choosing. Most commonly, this is used to provide a style of output consistent with that of the remainder of your own company’s web site. An example of the source to a template file is shown below.
<TABLE cellpadding=”2″ cellspacing=”2″ border=”1″ bordercolor=”#FFCCCC”>
<TR bgcolor=”#CCCCFF”>
<TD align=right width=80><font size=”-1″>Defect # </font>
</TD>
<TD width=800><font size=”-1″>__TAG_ID__</font></TD>
</TR>
<TR>
<TD align=right><font size=”-1″>Title</font></TD>
</TR>
<TR>
<TD><font size=”-1″>__TAG_SHORT_DESCR__</font></TD>
</TR>
<TR>
<TD align=right><font size=”-1″>Product</font></TD>
</TR>
<TR>
<TD><font size=”-1″>__TAG_PRODUCT_NAME__</font></TD>
</TR>
<TR>
<TD align=right><font size=”-1″>Description</font></TD>
</TR>
<TR>
<!– __DESCRIPTION__ –>
</TR>
<TR>
__TAG_DESCRIPTION_TEXT__
</TR>
<TR>
<TD align=right><font size=”-1″>Comments</font></TD>
</TR>
<TR>
<b>__TAG_COMMENTS_USER__: __TAG_COMMENTS_TIMESTAMP__</b>
</TR>
<TR>
<!– __COMMENTS__ –>
</TR>
<TR>
__TAG_COMMENTS_TEXT__
</TR>
</TABLE> - The optional parameter username_display may be used to override the behavior setting named USERNAME_DISPLAY, for the duration of the execution of a single API call. This allows the developer to return the user names in a different format than the system-wide default
- If no records are returned by the search, the message “No records found.” will be displayed
- You must provide at least one name and value for the search criteria. If you do not do this, you will see the message “No parameters entered”
- Many of the fields within the ExtraView database, such as product_name, status, priority, severity_level, assigned_to, category, etc., must be given valid values that already exist within the metadata of your installation. If you attempt to enter a value that is not known to ExtraView, an error message will result
-
The optional parameter named persist_handle may be used to paginate the result set by spreading the results returned over several separate calls using this API command. The persist_handle identifies the result set, qualified by the user_id, that is used to maintain the result set information across multiple API calls. The rules for using persist_handle are as follows:
- A new result set is generated whenever record_start=1; an existing result set is used whenever record_start > 1
- The same persist_handle value can only be used for subsequent pages of the result set on the same node; in clustered environments, if a subsequent call is directed to another node, the result set will not be found and results will not be returned
- The maximum number of pages returned is 10. This means that the page_length must be greater than 1/10th the size of the result set (# of rows returned) or the results will be truncated with no error indication.
-
The optional parameter
report_idwill use the layout associated with a report with the ID to format the results. Note that the filters specified within the report are not used, but the filters used in thesearchURL are used instead -
The format of date filter parameters, as used in runtime filters in a report is as follows:
<date> || <date> – <date> || -<date> || <date>-
The latter three are date ranges; rangestart to rangestop, rangestop, and rangestart respectively.
Where <date> is:
<unquoted date> || <sq><unquoted date><sq> || <dq><unquoted date><dq>
where <dq> ::= “ (a double quote)
and <sq> := ‘ (a single quote)A date may contain a dash if it appears in quotes. Otherwise, a dash is not permitted except as a date range signifier.