Generating Reports

This section explains how to write your own reports. It assumes that you are familiar with using the reports built into Inventory, and with the Inventory table structure.

Sections in this document: Building the report function | Referencing other functions, and passing variables | Adding your report to Inventory | Adding a report category

Building the report function

Reports are stored in files in the reports/ sub directory. Each report file must be called in the following format: report.XYZ.php (where XYZ may change depending on your file). Each file can contain multiple report function that belong to the same report topic: computers, OS, licenses etc.

You may add your functions to an existing file, or create your own. That's up to you. If you want your reports published with the main version of Inventory, you'll have to coordinate with the developers.

You can generate two main types of reports: A. dialog based reports: asking for user input as preparation to displaying data. (e.g. search dialog). B. Reports which display actual data in tables or lists or whatever strikes your fancy. You can see example for both dialog and data reports in file supplied with inventory like reports/report.computers.php and reports/report.os.php.
You need to master to following techniques and function usage:

• Callng reports by report id and report unique hash name
• Passing arguments from search dialogs, and translating to SQL WHERE clause
• Using sorting functions on displayed data
• Inserting your report into the SQL database, and associating it with a report function

Generally, your report function should display the dialog data, or query the SQL database and display results, all in an independent way. (meaning the function is a whole unit, which will be run by the reports engine to produce the dialog/data-report).

Referencing other functions, and passing variables

When creating two stage reports, where the first stage requires input from the user, and the second displays the resulting report, you'll need to call the second report when submitting data in the first (dialog), and also to pass the variable from the dialog to the second function/report. In the following instructions "first" will refer to the first step/report where user input is required, and "second" will refer to the resulting report where data is displayed.

More info about the report calling mechanism: When a report function is called, an id or hash are provided, these are used to retrieve report information from the databse. This allows the report mechanism to include the corrent file for the report, and then call the correct function to run the report. The function is passed an array of input variables (that can also be empty). The report then uses the given data to display output to the user.

Calling a report is done through the variable $get which is put into the first report's hidden form vars and is used to call the second stage report. The form's action is always the reports.php file which generates the report, and it is responsible to run the next (second) report. The value of the $get var should be an MD5 hash of the file name containing the report concatinated with the report function name. Thus, if you'd like to run the report function myCompReport() that is defined in the file reports/report.computers.php you'll assign the hash value to be: MD5("computers" . "myCompReport")

Passing variables between reports is done through one array of variables called $formVars[] that is passed by report.php when calling the report function of the second stage. This is done to match variable processing/parsing for functions like whereWolf() which create the WHERE clause for SQL queries and other such utilities. You may want to look at implementaiton examples in the functions compDialg() and compSimple() which are in the reports/report.computers.php file and implement a two stage search-dialog and report display pair.

Adding your report to Inventory

You will need to use SQL directly to add your report into Inventory. (use MySQL client, phpMyAdmin or whatever tool you like best). You'll need to run a command similar to:

insert into report set name = 'Software Name',
hash=md5('softwareswLoc4Usage'), display=1, typeId=5, description='Description field.....', fileName='software',funcName='swLoc4Usage',printFlag=0;

Here is a short description of the report table fields:

• The name column will store report's name. This can be any short string you wish, and will be displaying in the reports list.
• The hash value is a unique identifier for the report, and is used to get reports. You can read below¹ more about the reasons for using the hash value. It is very important to generate a correct hash value for the report, or the report will be be called properly from other dialogs. The hash field is generated from the fileName field concatinated with the funcName field, and passed through the MD5() hashing function. Thus, if your report is run by the function "myGreatReport()" which is in the file "reports/report.computers.php" your correct hash value will be:
  hash = MD5('computersmyGreatReport')
  
• The display field is a boolean value which decides if the report will show in the report list or not. Zero = hide, One = show. This is useful if your report must not be accessed directly by the user.
• The typeId field refers to the id field of a row in the typeReport table. This links the current report to a report category. Since there's a forreign key constraint on this field, the database will not accept invalid type id numbers. If you require a new report type, read in the section below for instructions.
• The description field is free text to describe your report. This text will appear as a tooltip when hovering over the report in the report list
• The fileName field holds information about the file where the report function is found. You must only supply the middle part of the filename - if your report file is: reports/report.MyReport.php the fileName field must be set to 'MyReport' only. Also make sure this matches the hash value (explained above).
• The funcName field holds information about the function to call to generate the report. You must store the function name directly without the parenthesis signs.
• The printFlag field is a boolean value which tells the report engine if this report can be printed. (Zero = No, One = Yes). Most data reports can be printed, and when displayed the top toolbar will contain icons which will allow the report to be printed and exported to spreadsheet format. Some reports display dialogs and should not be printed - this is the case where the flag is set to zero and the print/export icons will not appear for them.

Once the report was inserted correctly, you should be able to view in the reports list in Inventory (assuming your display value = 1).

Adding a report category

Adding a report category is also done manually as SQL command similar to the one below:

insert into typeReport set name='Cat Name',
typeIcon='icon.png', description = 'Type Desc...';

Here's a short description of the field in the query:

• The name field is the category name (that will be displayed in the report list / report type listbox). This should be a short and descriptive name.
• The typeIcon field is a reference to the filename of an icon from the /themes/default/icons/general/ directory (where 'default' will be automatically replaced with your current theme directory).
• The description field is free text giving the description for the current category.

¹ The hash value used in the reports table is a unique way to identify the report. It uses MD5() hash on the fileName + functionName string to generate the hash. This method is used because relying on the report id field (as we do with other items like computer/os/software records) is not reliable in this case. If you consider that reports can originate from different persons, installed / removed from Inventory in an independent way - there was a technical requirement to identify reports by something other than the id number, since this value can change from one installtion to the other. (This is becuase we expect external users (non Inventory developers) to add their own private / public reports). The hash value allows us to call the desired report in a reliable way, not matter what the report id is, or in what order reports were added to your Inventory installation.

Generating Reports