Report Development: Getting Started
Learn about what a report is, a report's basic structure and how to initially configure your own report.
What is a Report?
A report is a set of useful statistics, charts and tables that can be used to monitor performance of your help desk. Different reports exist to track different measures, for example:
- First response time and time to resolution on tickets.
- If SLA targets are being met or breached.
- Feedback ratings and responses.
All reports belong within the /addons/Reports directory, each with its own directory that is named the same as the report name. Each report usually has the following basic file structure:
| File/Folder | Description |
|---|---|
config.php |
The configuration file for the report, where you set the name, version and other important details about the report that shows in the operator panel when activating the report for the first time. |
Controllers/ |
Your report must have a controller class with the same name as the report in this folder, which is used to initialise the report. This class will also contain the logic to register all dashboards. |
Lang/ |
If you wish to support multiple languages, you can store the translations in this folder. |
Reports/ |
Your dashboards and cards should be stored in this folder. |
Views/ |
Any templates used by HTML cards are stored in this folder. |
Choosing a Name
Each report must have its own unique name for it to function alongside the other reports active in the system. The name you use must have a capitalised letter for each word with no spaces, such as TicketBacklog and ThisIsMyReport.
Starting with the Make Command
We recommend to use the included make:report command to generate the initial codebase for your own report. The command can be run on the CLI (in the base SupportPal directory) by entering php artisan make:report. It will then show a number of options that must be configured, which are explained in more detail below.
| Setting | Description |
|---|---|
| Author Name | Include your or your company's name here. |
| Author URI | Include a link to your website here. |
| Vendor Name | The name of your company, can be the same as the author name. |
| Add-on Name | Set the name of the report, it must be unique and contain no spaces as described in the Choosing a Name section. |
| Add-on Description | A quick description of what the report will achieve, is shown to operators in the report grid when they are going to activate/manage reports. |
Once you finish running through the options, it will automatically create the report in the filesystem. You will now be able to see it on the Manage Reports page (Reports -> Manage Reports) in the operator panel.
Configuration Options
The values you enter for the options above will be automatically inserted to the generated config.php file under your report folder. There are a few more configuration options available that you may wish to edit:
| Setting | Description |
|---|---|
| Name | Set the user-friendly name for the report. For example, for the TicketBacklog report, this would be set to "Ticket Backlog". |
| Report URI | If you are developing this report to be distributed to other users, you may include a specific link about the report from your website. This is particularly useful if you will have a specific page and/or documentation on your website. |
| Version | Set the version of the report, such as '1.0'. |
| Icon | Set an icon to be displayed in the reports list. It must be a full file path, we recommend to use __DIR__ to avoid hard coding the report directory name. If no icon is set, it will generate an icon based on the first letter in the name. |
Debugging Errors
To help with debugging while developing your report, we recommend the following settings. In the operator panel, please go to Settings and click the Debug tab:
- Enable the Debug Mode option. This will display errors in the browser in a user-friendly format.
You can also check the application log for errors, which can be found at /storage/logs/supportpal-[date].log on the file system or at Utilities -> Logs -> Log File Manager in the operator panel.