About this plugin
The JasperReports IO WordPress plugin extends the WordPress REST API to act as a proxy for the TIBCO JasperReports® IO microservice engine and thus allows generating reports and visualizations that are fast, highly interactive, and seamlessly embeddable into pages and blog posts or can be exported to PDF, Excel, Word or other popular document formats.
It provides several shortcodes for embedding the reports or data visualizations into the page or blog post, for opening them in a special interactive viewer, or for including the links for directly exporting those to specific document formats.
The main configuration option needed to use the JasperReports IO WordPress plugin is the URL where the TIBCO JasperReports® IO microservice engine is running. This URL should normally be accessible only by the server hosting the WordPress instance and should not be publicly accessible from the browser (see the Security section below).
Shortcodes
Report Embedding Shortcode
The following shortcode can be used to embed an interactive report or data visualization into a page or blog post:
>
[jrio report='/uri/of/the/report/in/the/jrio/repository']
The size of the embedded report container can be controlled with the width and height shortcode parameters, while the scaling behavior can be controlled using the scale shortcode parameter as seen in the following shortcode example:
>
[jrio report='/uri/of/the/report/in/the/jrio/repository' scale='width' width='300px']
If the JasperReports IO report or data visualization has parameters of its own, you can pass values for those using shortcode parameters having the same name as the respective report parameters.
However, since shortcode parameters are case insensitive, for camel case report parameters, a special report name mapping shortcode parameter called mappings needs to be used.
In the following example, the ChartThemesReport from the JasperReports IO repository has a parameter called chartTheme, which controls the color pallette of the chart being displayed. Notice the camel case name of the report parameter. Using a shortcode parameter with the same name should be used to pass the value of this report parameter to the JasperReports IO microservice, but it will be converted to lower case automatically by WordPress and thus would not be recognized by the reporting service.
This is why we use the mappings shortcode parameter to indicate that charttheme shortcode would correspond to the chartTheme report parameter.
>
[jrio report='/samples/reports/chartthemes/ChartThemesReport' chartTheme='aegean' mappings='charttheme:chartTheme']
Such report parameter mappings are not needed if the report parameters are entirely lower case.
Report Viewing Shortcode
The following shortcode can be used to include a hyperlink in the page or blog post to open the report or data visualization in a fullscreen interactive report viewer that would be displayed on top of the current browser page.
>
Open the report by clicking [jrio_viewer report='/samples/reports/chartthemes/ChartThemesReport']here[/jrio_viewer].
The report viewing shortcode supports report parameters and the same parameter mapping technique as the report embedding shortcode.
Report Export Shortcode
This shortcode can be used to insert report or data visualization export links into the page or blog post.
By clicking such links, the report or data visualization would be exported into one of the supported document formats and sent to the browser as a download file.
The output shortcode parameter specifies the target export format and can be one of the following: html, pdf, xls, xlsx, docs, pptx, rtf, ods, odt, csv.
>
Click [jrio_export report='/report/path/in/jrio/repository' output='pdf']here[/jrio_export] to export to PDF.
Built-in Parameters
When executing reports and generating data visualizations with JasperReports IO, the plugin is automatically sending some parameters behind the scenes. The so-called built-in parameters have values that are provided internally by WordPress and cannot be overridden, by specifying them in the shortcodes.
This is the list of the build-in parameters that the JasperReports IO plugin injects into every report or data visualization generated by the JasperReports IO service:
- WP_User_ID
- WP_User_login
- WP_User_email
- WP_User_firstname
- WP_User_lastname
- WP_User_display_name
- WP_User_roles
These built-in parameters can be used in reports to parametrize queries and filter information that only pertain to the current user being logged into WordPress and on whose behalf the report was executed.
Security
The TIBCO JasperReports® IO microservice does not have a security infrastructure of its own and relies on the caller/consumer to provide it. This is why when used in combination with this WordPress plugin, the reporting microservice has to be deployed behind a firewall and not be publicly accessible from the browser.
If it were to be publicly accessible, anybody could make REST API calls to it and have reports and data visualizations delivered without requiring any credentials or security related information from the caller.
The JasperReports IO plugin offers controlled access to the TIBCO JasperReports® IO by acting like a proxy that sits between the end user and the reporting microservice and channeling through the communication between the two. By doing so, the plugin also deals with the security part by ensuring that reports and data visualizations generated from a browser session are available only to that browser session only.
It thus offers session isolation to the microservice, which does not have such functionality itself.
Basically every user of this WordPress plugin has access only to the reports and data visualizations that have themselves generated based on unique execution IDs that are available only from within the current browser session.