run_report

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

SYNTAX

http://www.myserver.com/evj/ExtraView/ev_api.action?
user_id=username
&password=password OR [&access_token=token-value]
&statevar=run_report
[&username_display=ID | LAST | FIRST]
[&api_reverse_lookup=NO | YES]
&report_id=nnnn
&page_length=100
&record_start=1
&record_count=120 ​[&p_output_type=MS_EXCEL | MS_WORD | PDF | TEXT]
[&persist_handle=xxx] [&exclude_data_images=no | yes]
[&field1=value1] [&field2=value2] [&fieldn=valuen]

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 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 parameter is not provided, the report will output to XML
• The fields returned in the results correspond to the fields defined within the report
• The parameter report_id specifies 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 or by using the get_reports API function
• 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 titles as opposed to the field’s UDF_ID or NAME.  This is used when the report has runtime filters, to simplify the operation of the command for end users who may not be aware of the ID’s and NAME’s of fields
• 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
• 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
• If you are using this API function from within ExtraView, for example from within an email template, it is the best practice not to hard code the site URL.  In this scenario, you should use the token $$SITE_URL$$ as a substitute for the address.  The value of SITE_URL is determined by ExtraView when the server starts.  If the behavior setting named SITE_URL holds a value, this is used.
• When p_ql_search_mode=ADVANCED, you must use the Advanced filters format in the run_report command. For example, if you have a hierarchy report with runtime filters such as:
  
  parent level STATUS = ask at runtime

child level STATUS = ask at runtime

and you want
  
  parent level status = Open and child level status = Closed
  
  then you must send the filters in the correct order:
  
  &p_fset=0&p_fieldName=STATUS&p_value1_EVDISPLAY=Open&p_fset=1&p_fieldName=STATUS&p_value1_EVDISPLAY=Closed
  
  and you can then use:
  
  &p_fset=0&p_fieldName=STATUS&p_fset=1&p_fieldName=STATUS&p_value1_EVDISPLAY=Open&p_value1_EVDISPLAY=Closed
  
  or alternatively:
  
  &p_fset=0&p_fset=1&p_fieldName=STATUS&p_fieldName=STATUSS&p_value1_EVDISPLAY=Open&p_value1_EVDISPLAY=Closed
  
  Both the above will work as long as p_fset=0 and p_fset=1 are in the same order as:
  
  &p_value1_EVDISPLAY=Open and &p_value1_EVDISPLAY=Closed
  
  If you want the base level filter to be Open and the child level filter to be Closed programming arrays are built:
  
  p_fset[]= {0,1}
p_fieldName[] = {STATUS, STATUS}
p_evdisplayvalues[] = {Open, Closed}
  
  This shows why the order of the parameters matter.
• An example of how to express the parameters for a hierarchical report is as follows.  Note the use of the p_fset parameters to specify the hierarchy levels.  The base hierarchy level is set with p_fset=0:
  user_id=user_id
&password=xx
&statevar=run_report
&report_id=711
&API_REVERSE_LOOKUP=YES
&p_ql_search_mode=ADVANCED
&p_fset=1
&p_fieldName=PRIORITY
&p_operator==
&p_value1_EVDISPLAY=P%202
&p_mvalue1=
&p_fset=0
&p_fieldName=PRIORITY
&p_operator==
&p_value1_EVDISPLAY=P%203
&p_mvalue1=