(2024.2) Custom Reports
- David Engblom
- Brian Dixon
- 1 About Custom Reports
- 1.1 Overview
- 2 Writing a Custom Report
- 2.1 Creating a New Report
- 2.1.1 Logic Tab
- 2.1.1.1 Custom Report Functions
- 2.1.2 assign: Assigns a variable from the Logic to be used in the Template
- 2.1.2.1 Example
- 2.1.3 loadReport: Loads another Report based on the Report Identifier
- 2.1.3.1 Example
- 2.1.4 barcode: Generates an HTML IMG tag of a barcode
- 2.1.4.1 Example
- 2.1.5 addError: Forces the Report to render an Error Message instead of the Report
- 2.1.6 Parameters Tab
- 2.1.7 Template Tab
- 2.1.8 Options Tab
- 2.1.9 Attachments Tab
- 2.1.10 Batch Processing Tab
- 2.1.1 Logic Tab
- 2.2 Updating an Existing Report
- 2.1 Creating a New Report
- 3 Importing/Exporting a Custom Report
- 4 Linking a Custom Report
- 5 Running a Custom Report
- 5.1 Back Office generating the Report
- 5.1.1 Admin: Custom Reports
- 5.1.2 Reporting: Available Reports
- 5.1.3 Report Preview
- 5.1.4 Saved Reports
- 5.2 CustomerCenter providing the Report
- 5.3 Automatically running the Report
- 5.3.1 Report Batch Process
- 5.3.1.1 Invoice - Logic
- 5.3.1.2 Invoice - Template
- 5.3.1 Report Batch Process
- 5.1 Back Office generating the Report
About Custom Reports
Overview
Custom Reports is a built-in HTML Template Engine that uses HTML Coding and external frameworks to allow Users to write their unique Reports using PCR-360 data and format them however their Organization desires. Before writing a Report, a User should be familiar with HTML programming and should first read the external documentation for Smarty and Bootstrap 4.0.
Custom Reports empower users to customize their organization's customer experience. Your organization can make the Reports available on CustomerCenter, in a backend reports grid or directly on specific backend application grids and forms. PCR has structured the Custom Report creation process to mimic best the workflow needed to build the Report.
Additionally, Custom Reports allow Users to run a Report and save the output directly to the server. The saved report can be shared with others without re-running it or worrying about the data within the Report changing.
An example Custom Report is available at the bottom of this article.
Writing a Custom Report
The Admin > Reports > Custom Reports menu option brings the User to the Custom Reports grid. From this grid, a User can 
Creating a New Report
A Custom Report is composed of multiple components. Every Custom Report has a unique Identifier, a Report Name, and Roles assigned to access it.
Custom Reports consist of Logic (for querying system Data), Parameters (for determining Report content), a Template for formatting the Report, Options (for adding a Report Title, Footer, and additional CSS), Attachments (for external files to be used within the Report) and details to define it for Batch Processing.
Custom Reports also maintain a short-term log of any Debug information, which is useful for refining the report's Logic and checking for possible errors within that Logic.
Logic Tab
Custom Reports utilizes the internal PCR-360 Custom Logic functionality that is also available to Custom Events, Custom API and Custom Validations.
Custom Report Functions
assign: Assigns a variable from the Logic to be used in the Template
Example
/**
* @param string $name - name of the assigned variable in the Smarty Template
* @param array $value - value of the assigned variable in the Smarty Template
* @return void
*/
$this->assign('variableName', $variableValue);loadReport: Loads another Report based on the Report Identifier
Example
/**
* @param string $identifier - another report's identifier
* @param array $params - array of parameters used to render the other report
* @return string - the Rendered Report
*/
$report = $this->loadReport('customReportIdentifier', ['paramName' => $parameterValue]);barcode: Generates an HTML IMG tag of a barcode
Example
/**
* @param string $code - string text to encode
* @return string - barcode IMG tag
*/
$barcodeImgTag = $this->barcode('test test');addError: Forces the Report to render an Error Message instead of the Report
Example
The Logic Tab is used for querying PCR-360 data. The Logic section has two parameters available for use in the Custom Logic: $params and $user.
$params
A key/value paired array of parameters that were passed into the Report are available within this array. Any changes to this array are also assigned to be accessed from the Smarty HTML Template.
$user
A key/value paired array of User information about the currently logged in User. The example below shows the options that are available within this array. This data enables Custom Reports to be specifically tailored to the User viewing the Report.
Debug Tab
Only data sent to the debug() function is displayed in the Debug section. Debug information only exists for 24 hours before it is automatically cleared out by the system. For more information on the debug() function, please see our article on Syntax.
Parameters Tab
A User can click the [Add] button to define each Parameter for the Report.
Parameters require a Name to be accessed within the Report Logic, as well as a Description to allow the User to know what they are entering. Parameters must also be defined as a specific Input Type, much like User-Defined Fields are. Parameters can also be assigned an Order value to determine the order in which they are presented to be populated by the Report generator. Finally, all Parameters have a Display checkbox to determine if that Parameter value will be shown in the Report's Preview.
Input Types accepted:
Checkbox
This is the only type of Input that can not be defined as required, as checkboxes are either Checked or Not Checked.
Currency
Date
Date/Time
Decimal
Drop Down
When a Drop-down Input is assigned, the User must define the Value and Text for each option within the Drop-down menu.
Number
Picker
When an Input is assigned to the Picker Type, the User must also define what type of Picker it is. Almost all types of Records within PCR-360 can be accessed by a Picker
Text
When a User runs a Custom Report, the related Parameters will be available to be set in the panel on the left side of the screen.
Template Tab
The Template Tab is where the bulk of the Report is made. The User can write HTML code here to access the information obtained in the Logic Tab, and format it into its desired finished product. A User should be familiar with HTML programming and should first read the external documentation for Smarty and Bootstrap 5.1 before attempting to develop the Template for a Report.
Options Tab
The Options Tab is used for creating the Report's Title (either a fixed Title, or generated based on information obtained when the Report was run, with a 100-character limit), as well as adding in additional Footer and other general CSS formatting. The Report's Footer is limited to 500 characters or less. A User can also define specific options for when the Report is requested as a PDF file, such as Header and Footer details. For assistance in using these PDF settings, please review the 
PDF Options Example:
PDF Options
Logic
PDF Footer Result
Attachments Tab
Before Files can be uploaded to a Custom Report, the Custom Report must first be saved.
Unlike other Attachment Tabs within PCR-360, files Attached to a Custom Report are uploaded to the /media/custom/ directory on the Server. This makes ALL Attachments to ANY Custom Report available to all other Custom Reports, as long as the User knows the path to the file name.
Attachments can be uploaded from the User’s PC using the 
When using 
Warning: because all files are easily accessed using the same basic File Path, Uploading a File with the same name as a previously uploaded File will overwrite that File on the Server. When a Custom Report is exported, only Attachments on the Report will be exported.
Note: It is highly recommended NOT to attach JavaScript files to Custom Reports as that can be a severe security risk
Batch Processing Tab
The Batch Processing Tab displays information about Scheduled Batches, and allows a User to 
Updating an Existing Report
To edit a Custom Report, a User simply needs to select the desired Report from the Custom Reports grid and click on the [Edit Selected] button. This will open the Report and the User can change any Logic, Parameters, Options, Attachments Batches, or the Template as needed.
Importing/Exporting a Custom Report
For convenience, PCR-360 has built in functionality to Import and Export Custom Reports. This is particularly useful when building a report in a Test Environment, and then loading it into your Organization’s Production Environment without building the report fresh.
Exporting a Custom Report
To Export a Custom Report, the User must select the desired report in the Admin > Reports > Custom Reports grid. Then the User can click on the 
Importing a Custom Report
To Import a Custom Report, the User must click on the 
Linking a Custom Report
Reports can be linked to Data-Entry forms or Data Grids. When opening a Custom Report that has been linked a single parameter called “recid” is passed. To process this parameter the report requires that the “recid” parameter is added to the Parameters tab in the Report Builder.
Running a Custom Report
Back Office generating the Report
Back office users can generate Custom Reports from multiple places in PCR-360: Admin, the Reporting menu, CustomerCenter, Form → Reports menus, and Grid → Reports menus.
Admin: Custom Reports
From the Custom Reports grid Users can click on to generate a Report.
Reporting: Available Reports
Users can generate new Reports from the Main > Reporting > Custom Reports > Available Reports menu option. However, when accessed from the Main menu, the Grid is limited based on the logged in User's assigned Roles, based on what Reports are assigned to those Roles.
To view a Report, a User must select the Report from the grid and click on [View Report]. For User convenience, a User can also [Bookmark Selected] Reports to access more quickly through the PCR-360 Footer.
Report Preview
On the Report Preview page, the User must fill in any required parameters and then click on the [Open Report] button to open the report in a new tab. After entering the required parameters, a preview of the report may be run by clicking the "Refresh" button.
When a Report is run, Users can share the Report using the functions provided.
The [Copy Link] button will copy a link to the Report, including the parameters, to the User's clipboard so that they can share it as a Web URL. | |
The [Save a Copy] button will save the Report so that it becomes available from the Saved Reports grid. | |
The [Download PDF] button will download a PDF Copy of the Report to the User's local system. |
Saved Reports
Alternatively, Users can view previously saved Reports from the Main > Reporting > Custom Reports > Saved Reports menu option.
From this grid, the User can click on [View Report] to open the saved Report directly or click on [Delete Selected] to delete the saved Report.
Admin Users can also click on [Bulk Assign] to have a Report display for other Users.
CustomerCenter providing the Report
Custom Reports are available in CustomerCenter. Just like the Main > Reporting > Custom Reports > Available Reports menu option, the page is limited based on the logged in User's assigned Roles, based on what Reports are assigned to those Roles.
Automatically running the Report
From the Custom Reports grid, Users can open a Report, and click the 
Report Batch Process
The Report Batch Process allows an Admin User to apply SQL Filters, define a Notification Message when the Report Batch is generated, and set a specific Schedule for the Report to run automatically.
When the Batch executes, each Record from the User defined SQL Filter Query will be fed into the Report's Logic as the parameters. Each unique row of the Filter Query will generate a particular Report. The CONTACTS_RECID of each record will determine which Contacts are assigned to the individual Reports.
Users can define a custom Subject Line for an automatic notification, as well as provide a message for the Notification. Users can also opt to attach the PDF of the Report to the Notification automatically.
Users can have a Batch run Immediately or set a Frequency for the Report to execute on, as well as set a date for when to run the Report next.
The Frequency can be set for:
Run Once
Daily
Weekdays
Weekly
Monthly
Quarterly
Yearly
Example Custom Report: Invoice
Below is an example of how Custom Reports can generate a Custom Invoice.
Invoice - Logic
Invoice - Logic
Invoice - Parameters
Invoice - Template
Invoice - Options