Installing a New Report
Top  Previous  Next

Background

When using the Advanced Report Explorer, the Configuration Form now displays an advanced form as shown.

report19

At first sight the values entered may appear to be somewhat cryptic and incomprehensible. When you are making a new report by deriving it from an existing report all the correct values are filled in for you automatically, which is why this tab is not visible in the Standard Report Designer. However, when making a report from scratch only you will know which area in RentalDesk that the report is meant to print and what the report is designed to do. The easiest way to determine what information needs to be entered here is to note the configuration settings for another report that prints from the same menu. For example all the Equipment List reports have the same settings. However, what follows is a list of what all the fields mean/do in RentalDesk.

FormNameThis is the actual form in RentalDesk that will place your report on the menu. TDFEqlist, for example, is the internal name for the equipment list form that is hosted by the Data Panel in RentalDesk, so a report with this form name entered will appear on the Data Panel report menu.  
 
SingleRecFilteredSome reports require RentalDesk to supply a records selection criterion with a value that can only be determined just before a report prints. For example, when printing a quote the report needs to know to select only the equipment that is currently visible in RentalDesk. Setting SingleRecFiltered will tell the report to expect a value to be passed to the first selection criterion in defined in the report. We call this the Primary Selection Criterion. Once you tick this option, you will need to supply information for other options that follow. You would NOT want to check this option when the report alone is responsible for getting all the data, e.g. for the report we have just written.  
 
DataModuleIf SingleRecFiltered is checked then RentalDesk needs to know which one of its internal DataModules holds a special data retrieve component. We specify this here.  
 
MasterTableIf SingleRecFiltered is checked then RentalDesk needs to know which data retrieve component to use.  
 
MasterTableNameIf SingleRecFiltered is checked then RentalDesk needs to know which underlying table in the database the report will be setting a selection criterion against, e.g. the equipment list header table, eqlist_head.nx1  
 
MasterFieldIf SingleRecFiltered is checked then RentalDesk needs to know which field to will be supplying the report selection criteria with a value for the data retrieval. Its normally the "key field" for the table which uniquely identifies each record in it.  
 
DesignerFilterDisplayIf SingleRecFiltered is checked then when working in the Report Designer it is useful to be able to select a specific job, equipment list, invoice, etc. to preview your data against. You will know that this can be selected on the General Tab of the Reporting Configuration form. In the DesignerFilterDisplay we would therefore supply the field in the table that is the document "reference" or textual identifier for the records, i.e. something you would recognise like an invoice number. The drop down control is then populated with values from this field.  
 
MultiRecFilteredSome reports need RentalDesk to pass multiple values to their main selection criterion. Examples are reports which print from the Address Book and Accounts Book.; these reports will respond to the data in RentalDesk that has been filtered by the user (for example, all invoices that are unpaid). MultiRecFiltered and SingleRecFiltered are therefore mutually exclusive options.  

Installing our new report

report20

Now that we have an insight into the meaning of the Advanced Configuration tab, we are in a position to install our new report. We realise that the report does all of the work itself and does not depend on any single or multiple record selection criterion, so we only need to supply the FormName for the report. It makes sense to put it in the Job Book, and we will want it to be available for print regardless of what form is loaded in the Job Book, so it makes sense to load in on the Explorer Panel menu since the form in this panel is always persistent, unlike the Data Panel, which hosts the job header form, equipment list form, invoices, etc. We can look up what the FormName is for other reports that print from here and then enter the same value, which is TZFJobs. Now all that's left to do is to set a meaningful menu caption on the General Tab and then publish the report in the Report Explorer.


Technical Details on Record Selection Criteria

The SingleRecFiltered options supplies a value to the first record selection criterion (Primary Selection Criterion) in any list of criteria that you specify in the Data tab. Take a look at the selection criteria for a Quote report: the first entry (Eqlist Head.Eqlist Head-idx = X) is what RentalDesk will be supplying a value to. Here X will the number of the equipment list that you are currently looking at in when you want to print a quote for it. The field that stored this information is called Idx. The Mandatory checkbox tells RentalDesk that this selection criterion is required by the report so on the Filters Tab of the Configuration form, the options to change the criterion are disabled.

Note: when working in the Designer you might see that the Primary Selection Criterion already has a value supplied, e.g. "EqlistHead.EqlistHead-idx = 69". This is because you will have specified a sample equipment list to work with in the Designer (General tab of the Configuration form).

If a selection criterion is using a Date field and the Mandatory flag is set, then RentalDesk will supply default values for the dates. The rules are a little complicated but worth noting:

·If the selection criterion only wants a single date to be passed then this date will be Today. If you want the option to modify this when the report runs then you can check the Autosearch option to invoke the prompt form. Today is used because it has great utility is many reports. Take a look at the Late Returns report in the Planner folder; the first selection criterion there (Eqlist Head.End Date < DATE) needs Today to be passed.  
 
·If the selection criterion wants two dates to be supplied to a date range, then the first date will be Today and the second date will be Today + 1 Month. Take a look at the Jobs Back List report in the Job Book | Job Forecasting folder to see this configure on the Designer's Data tab. Note how the operator for the selection criterion uses the keyword between to tell the report that a range of values is required.  
 
·If the Mandatory flag is not checked against a date base criterion (as in our newly designed report) then RentalDesk will not attempt to supply default dates.  

If the MultiRecFiltered option is checked then the operator for Primary Selection Criterion is always set to In List. Open the Filtered Customer List report from the Address Book | Matching Entries folder to see and example of this. An 'In List' operator tells RentalDesk to pass a list of comma separated values to the query that retrieves the data. If the field Idx matches any of the values passed then that record is retrieved. So, for example, if you set a filter in the Address Book to select only Suppliers, and this narrowed down you list of companies to just ten enteries, when you print the Filtered Customer List report, the values of the each of these companies' Idx field will be passed to the report and it too will only print the details for the companies.
a