Product Documentation

This function runs an existing report, using its report_id obtained from the get_reports function.

SYNTAX

NOTES

• This command runs a report from the available list of public and private reports using the report_id obtained from the get_reports function
• The output is returned in XML format
• 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 parameter named 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 JavaScript functions to retrieve paginated results, if you believe your searches can bring up large number of records
• The parameter named record_start is required and gives ExtraView the number of the first record in the search results to display. This is used in conjunction with the parameter named p_page_length, which defines the number of results to retrieve. If there is a possibility that record_start can be greater than page_length, you must use the parameter named record_count. Using these parameters, you can build functions to retrieve paginated results if you believe your searches can bring up large number of records
• The optional parameter api_reverse_lookup has a default value of NO. If set to YES, then all the user defined field values are expressed with the field's title as opposed to the field's ID. This is usful when using fields with a display type of list, where the programmer needs to know the internal ID of a list value in order to use it as a parameter in the API call. With api_reverse_lookup=YES, then the programmer can use the field's title. Usually this is well known and obvious as opposed to ID's which need to be discovered through a SQL query on the database

• 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. 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 parameters represented by field1=value1 and field2=value2 are used to provide any number of runtime filters that are required by the report. For a name value pair to be valid with this API call, the field must have been defined within the report as a runtime filter. You must provide a name value pair for each and every runtime filter in the report you are running. Failure to do this will result in an error being displayed
• If the report you are running uses the advanced report filters, then this automatically implies that the report will also use expanded report filters
• This API command uses the filters specified in the report.  Any runtime filters you have within the report can be replaced with filters specified within the command.  Note that if you wish to run a report with runtime filters and want to use advanced search features such as numeric and date operators, you should use the search API command.  The search API command has more flexibility in this case.