The Report Service
The main resource /report provides a flexible rest service interface to create dynamic reports defined by through the imixs Report Service. The report rest service can be used to create and update report definitions and to process the result of a report providing a set of different parameters.
The /report resources GET
The /report GET resources are used to get business objects provided by the Imixs Report Manager:
URI | Description |
---|---|
/report/reports | a list of reports provided by the workflow instance |
/report/reports/{name} | a report description for a specific report |
/report/{name}.ixr | the result of a specific report |
/report/{name}.html | a html table of the result for a specific report |
/report/{name}.xml | a xml representation of the result for a specific report |
A report definition need to provide a set of informations to define the layout and content of a report
- JPQL Statement - selection of workitems to be selected in a report
- contentType / Encoding - defines the MIME-TYPE and encoding for a report (e.g. text/html for html output, application/pdf for pdf files)
- processing instructions - xsl template to format the xml output of an workitem collection
The following example shows a simple XSLT file to format a workitem collection into a html output:
<?xml version="1.0" encoding="UTF-8" ?> <xsl:stylesheet xmlns="http://www.w3.org/1999/xhtml" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:output method="xhtml" encoding="UTF-8" indent="yes" doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN" omit-xml-declaration="no" /> <xsl:template match="/"> <html> <body> <xsl:apply-templates select="/collection/entity" /> </body> </html> </xsl:template> <!-- Template --> <xsl:template match="/collection/entity"> <div id="address"> <xsl:value-of select="item[name='name']/value" /><br /> <xsl:value-of select="item[name='address']/value" /><br /> <xsl:value-of select="item[name='street']/value" /><br /> <xsl:value-of select="item[name='zip']/value" /><xsl:text> </xsl:text> <xsl:value-of select="item[name='city']/value" /><br /> </div> </xsl:template> </xsl:stylesheet>
Providing JPQL Parameters
A report definition can also contain dynamic JPQL parameters. These parameters can be defined in the JPQL statement of the report. See the following example of JPQL statement:
SELECT workitem FROM Entity AS workitem JOIN workitem.integerItems AS p WHERE workitem.type = 'workitem' AND p.itemName = '$processid' AND p.itemValue = ?1
To provide the Report with the expected parameter ?1 the parameter can be appended into the query string.
http://Host/WorkflowApp/report/reportfile.ixr&1=5130
In this example request the URL contains the parameter “?1=5130” which will be inserted into the JPQL statement during the report execution.
Dynamic Date Values
The JPQL Statement executed by the ReportService may contain dynamic date values. These XML Tags can be used to compute a date during execution time. A dynamic date value is embraced by the ‘date’ tag:
<DATE />
The date tag supports the following optional attributes:
Attribute | Description | Example |
---|---|---|
DAY_OF_MONTH | set day of month | (first day of month, use ‘ACTUAL_MAXIMUM’ to get last day of month |
MONTH | set month | (January) |
YEAR | set year | |
ADD | add offset (see Calendar.class) | subracts one month from the current year |
See the following example to set the start and end date of the last month:
SELECT workitem FROM Entity AS workitem WHERE workitem.created BETWEEN '<date DAY_OF_MONTH="1" ADD="MONTH,-1" />' AND '<date DAY_OF_MONTH="ACTUAL_MAXIMUM" ADD="MONTH,-1" />'
Apache FOP / PDF Reports
The Imixs Report rest service provides the option to generate PDF Reports based on the Apache FOP API. This is a flexible way to display workitems in PDF or other File formats supported by Apache FOP. To use FOP API during report processing the Apache FOP API need to be included into the Web Module of the rest service. A report definition also need to define the corresponding content type. This is for example ‘application/pdf’ to create a pdf file. The XSL instructions need to be replaced with the XSL formatting objects (XSL-FO) instructions. The following example shows a simple FO template
<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version="1.1" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:fo="http://www.w3.org/1999/XSL/Format" exclude-result-prefixes="fo"> <xsl:output method="xml" version="1.0" omit-xml-declaration="no" indent="yes"/> <xsl:template match="/"> <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"> <fo:layout-master-set> <fo:simple-page-master master-name="simpleA4" page-height="29.7cm" page-width="21cm" margin-top="2cm" margin-bottom="2cm" margin-left="2cm" margin-right="2cm"> <fo:region-body/> </fo:simple-page-master> </fo:layout-master-set> <fo:page-sequence master-reference="simpleA4"> <fo:flow flow-name="xsl-region-body"> <fo:block font-size="16pt" font-weight="bold" space-after="5mm">Project: <xsl:value-of select="projectname"/> </fo:block> <fo:block font-size="12pt" space-after="5mm">Version <xsl:value-of select="$versionParam"/> </fo:block> <fo:block font-size="10pt"> <xsl:for-each select="collection/entity"> Workitem ID:<xsl:value-of select="item[name='$uniqueid']/value" /> </xsl:for-each> </fo:block> </fo:flow> </fo:page-sequence> </fo:root> </xsl:template> </xsl:stylesheet>
Apache FOP / PDF Report Plugin
Reports can also be computed during the processing life cycle by adding the following plug-in into the process model:
org.imixs.workflow.jee.plugins.ReportPlugin
The Report Plugin can compute dynamic collections of workitems based on a JPQL statement as explained before. As the Plugin runs in the phase of workflow processing the current workitem is typical not selectable with JPQL. Therefore the Report Plugin replaces the result-set with a new instance of the current workitem if the workitem is included in the result-set.
The /report resources DELETE
The /report DELETE resource URIs are used to delete business objects:
URI | Description |
---|---|
/report/reports/{name} | deletes a specified report |
The /report resources PUT and POST
The /report PUT and POST resources URIs are used to write business objects:
URI | Description |
---|---|
/report | creates or update a specified report |
Resource Options
You can specify additional URI parameters to access only a subset of workitems by a collection method URI. This is useful to get only a subset of the whole worklist and to navigate through a list of workitems. Append optional arguments to define the number of workitems returned by a URL and the starting point inside the list. Combine any of the following arguments for the desired result.
option | description | example |
---|---|---|
count | number of workitems returned by a collection | ..?count=10 |
start | position to start workitems returned by a collection | ..?start=5&count=10 |
type | Optional type property workitems are filtered | ..?type=workitem |
download | Optional filename for a download request This generates the HTTP Header Content-disposition,attachment;filename=example.pdf | download=example.pdf |
Note: The Imixs JEE Workflow manages the access to workitems by individual access lists per each entity. So the result of a collection of workitems will only contain entities where the current user has a read access right. Without that right the workitem will not be returned by the workflowManager and so it will not be included in the list.