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 report_id specifes the ID of the report as stored in ExtraView.  This ID may be seen on the report screen or within the report editor for the report
• 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 useful 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 provide 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.  More sophisticated runtime filters may be defined as follows in the following example.  This defines 3 runtime filters, each predefined in the report editor within the desktop user interface:

  • The predefined example runtime filers are:

    • DATE_CREATED - Date Created
    • TIMESTAMP - Last Modified
    • PRIORITY - Priority

  • The example parameters for the call are:

    user_id=xx&password=xx
&statevar=run_report
&page_length=100
&record_start=1
&username_display=LAST
&report_id=1234
&api_reverse_lookup=YES
&p_ql_search_mode=ADVANCED
&p_fset=0
&p_fieldName=DATE_CREATED
&p_operator=between
&p_value1_EVDISPLAY=09/01/2017
&p_mvalue1=09/01/2017
&p_value2=09/30/2017
&p_fset=0
&p_fieldName=TIMESTAMP
&p_operator=>
&p_value1_EVDISPLAY=09/08/2017
&p_mvalue1=09/08/2017
&p_fset=0
&p_fieldName=PRIORITY
&p_operator==
&p_value1_EVDISPLAY=P 2
&p_mvalue1=

  • The basic syntax of each runtime filter is a set of following six form parameters

    1. p_fset
    2. p_fieldName
    3. p_operator
    4. p_value1_EVDISPLAY
    5. p_mvalue1
    6. p_value2

  • The values of each parameter are:

    1. p_fset - p_fset is always set to 0, like p_fset=0

    2. p_fieldName - p_fieldName is the Data Dictionary name, such as p_fieldName=DATE_CREATED, p_fieldName=TIMESTAMP, and p_fieldName=PRIORITY

    3. p_operator - p_operator is one of the following values but depends on the display type of the field, the same as in the desktop user interface

          =
      >
      <
      <>
      <=
      >=
      contains
      not_empty
      empty
      between

    4. p_value1_EVDISPLAY - for POPUP, DATE and DAY display type fields, you need to specify this value

          For DATE and DAY fields,  an example is p_value1_EVDISPLAY=09/08/2017

          For POPUP fields an example is p_value1_EVDISPLAY=P 2

          Note: you need to have the parameter api_reverse_lookup=YES to enable the reverse lookup of list fields using their title rather than their name or the database UDF_LIST_ID.

    5. p_mvalue1 - All display types, except POPUP need to specify the database values

          For DATE and DAY fields, you need to specify the same value of p_value1_EVDISPLAY, for example p_mvalue1=09/08/2017

          For POPUP fields, you don't need to specify any parameter if api_reverse_lookup=YES

          For other display types, you need to specify the database values

    6. p_value2 - p_value2 is only used for DATE and DAY fields when you using the between operator, for example p_value2=09/30/2017

• The optional access_token parameter allows you to use a valid OAuth2 token obtained with the get_token command.  If you provide the access_token parameter, then the user_id and password parameters should not be provided.  This prevents the password being sent in clear text over your network connection
• Not all report types are supported by this command.  The supported report types are Column, Summary, Matrix and Aging.  The remaining report types generate graphical information which is not suitable for alphanumeric output
• 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.
• The report may be output to different file formats with the optional p_output_type parameter.  You may output the report to Microsoft Excel, Microsoft Word, Adobe PDF or text.
• If the data returned includes an image, the data for the image will be base 64 encoded.  However, the optional parameter exclude_data_images will inhibit images embedded within HTML Area fields from being output, if set to a value of yes.