Creating a report criteria form

Report criteria forms are specialized forms that can be used to specify how reports are to be generated. This topic presents the basic process to create such a form for a report-template form or an SSRS report.

To create a report criteria form:

  1. In Design Mode, launch the New Form Wizard and create a new Build from Scratch form.
    The name for the form should consist of the subject of the report, appended with "Report" to identify it as a report form. For example, you might have a report on user tasks named UserTasksReport.

    You need not select a data source for this form, because it is simply a form that passes report criteria parameters to the report object.

  2. In the Form properties sheet, specify a Caption for the form.
  3. Save the form.
  4. Optionally, if you are using a source control system, check your new form in and then back out.
  5. Create the report input fields and parameters that will determine what data is to be processed and included in the generated report.
    Although you can include virtually any type of component for this, there are several common types of components used on report forms. They include these:
    • To create ranges for possible return values, you can use pairs of combo boxes or date combo boxes, using one for the starting value and the other for the ending value. These are especially useful with DataView reports.
    • To create checklists of property values to include, you can use check boxes or possibly option (radio) buttons. These are more common with Report-template type forms.
    • It is also common to create "Reminder" date fields/ranges; options to increment the date when the report is generated; and options to display (or not display) the report header.

    It is beyond the scope of this topic to provide specific procedures for each of these options. To view procedures to create each of these options, however, see the Related Topics.

    Note: For each task parameter that you want to pass to the report object, you must include it as part of the BGTaskParms variable definition. The parameter specification depends on what type of parameter you are passing.
  6. Create a form variable with these specifications:
    • Name: BGTaskName
    • Value: The name of the background task for this report, as defined on the Background Task Definitions form.
    • Persistent: True
    • Global: False
  7. Create a form variable with these specifications:
    • Name: BGTaskParms
    • Value: The syntax to use in this field depends on the type of report object the criteria form is being created for.
      • If the report object is a Report-template type form, then use this syntax for each variable value:
        Note: You can group multiple variables into one SETVARVALUES declaration.

        SETVARVALUES(targetVariable=V(sourceVariable))

        where:

        • targetVariable is the name of the variable in the report object that is to receive the value of the parameter being passed.
        • sourceVariable is the name of the variable you are using in the report criteria form to send the value as a parameter to the report object.
      • If the report object is a DataView or an SSRS report definition file, then use this syntax for the variable values:

        V(variable1),V(variable2),V(variable3),...

        If the list of variables is for a DataView report, they must be listed in in the same sequence as they appear on the Input Parameters tab of the DataViews Setup form.

    • Persistent: True
    • Global: False
  8. Create the Print button.
    See the help topic Creating a button to print a report.
  9. Save the form and close it.
  10. Reopen the form and test the Print functionality.
    Note: At this point, the entire contents of the template form should print, because you have not yet set up the associations between this form and the report object.
  11. Create the Preview button.
    See the help topic Creating a button to preview a report.
  12. Save the form and close it.
  13. Reopen the form and test the Preview functionality.
    Note: At this point, the entire contents of the template form should preview, because you have not yet set up the associations between this form and the report object.
  14. Make sure you go back to the report object and set up the associations between that form and this one.
The report criteria form is now ready to be used to manually generate reports. If you want or need the report to be generated automatically, probably on a recurring basis, you must perform additional steps to enable the report to be generated in the background.