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',
Here is a short description of the report table fields:
hash=md5('softwareswLoc4Usage'), display=1, typeId=5, description='Description field.....',
Once the report was inserted correctly, you should be able to view in the reports list in Inventory (assuming your
display value = 1).
- 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 below1 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.
- 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',
Here's a short description of the field in the query:
typeIcon='icon.png', description = 'Type Desc...';
- 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.