Report Generator - Administration Guide

Sometimes it is needed to get some input from the user before the report is being created. This is solved by using a custom pre-process page.

Some examples of what a pre process page allows the user to do:

Internally, the Report Generator uses a component from the Apache Software Foundation called FOP for converting XML-FO data into for example PDF. The report generator has two versions of the Apache FOP software available, 0.20.5 and 1.1. The default version being used is 1.1 (this has been changed as of TVC 2010.3.0). See this chapter for information how to change the version used.

As of TVC 2013.1.0, the Report Generator contains another XML-FO converter that can produce DOCX, RTF, ODT (Open Office) and Wordprocessing ML output. This XML-FO converter is called XFC.

First, create a trigger program object similar as shown below.

Next, define the attributes of the trigger program object, as shown in the picture below.

Next, attach the program to the desired event as shown below:

You can invoke the report generator from MQL like the example below illustrates.

Remember that you need the tvc JAR files in the MX_CLASSPATH, including the tvc.license file.

Also note if you are using report definitions stored as XML files below the /WEB-INF/tvc folder of your web-application, you need to set an environment variable before starting your MQL session.

Example:

Otherwise the Report Generator cannot resolve the XML files that are used.

When working inside the TVC Structure Browser, a common use case for the user is to be able to create a report against one of the objects inside the table / structure. The normal steps to do this, would be to open the desired objects category tree (emxTree.jsp) page and select the reports page from there, and then select the report to create. This is not only a time consuming task, it also makes it harder for the user to come back to the structure and continuing the work he/she was doing before creating the report.

A better approach would be to utilize the side panel and display the available reports in there, for the selected object. This is exactly what the command "TVC Show Reports In Sidepanel" does. It is installed with the report generator, and can be added to any toolbar-menu or context menu inside the structure browser.

When this command is invoked, the available reports for the selected object will appear in the side panel and the user can create the report directly from the structure browser without the need for leaving the page.

An example screenshot is shown below:

Reports defined in XML files are stored within a folder called "report" below the "/WEB-INF/tvc" folder of your web application. The file must have the suffix ".xml".

Referencing a report stored as XML on disk is done using a specific naming syntax. To reference the report stored in /WEB-INF/tvc/report/MyReport.xml, one would use the following name:

You can also group these XML resources within domains. For example, you might want to store the configuration files related to Engineering Central in a certain place. As an example the file /WEB-INF/tvc/enc/report/MyReport.xml would then be referenced as.

The root element of the XML file defines what type of report definition it is. The mapping between report definition type and its root elements are listed in the table below:

Many configuration options on a Report Definition are the same regardless what Report Definition type you have chosen. The sub-chapters describe these in detail.

Even though the configuration options are on the common level, there are some Report Definition types that may not use some of the configuration options mentioned here. These exceptions are described per Report Definition type later on within this document.

Defines if the report is global or context dependent (e.g. requires a business object as input). See chapter 3.1 and 3.2 for more information.

To define the global value within your report definition, use the syntax below:

Defines an expression that is used to evaluate if the definition is available or not for the object that the report is being created for. The expression is used with the MQL command "evaluate expression" and must therefore conform to that syntax.

Note that if your report definition is marked as being "global", then the filter expression has no meaning.

To define a filter expression within your report definition, use the syntax below:

Remember to escape XML sensitive characters. This can be made as in the example above using XML entity references, or surround the value with <![PCDATA[ …​ ]]>.

Also note that you should test your expression in advance against a business object. Below is an example from MQL how to do so:

E.g. you surround the filter expression with evaluate[].

In some situations (depends also on used ENOVIA version), you might need to use the keywords AND instead of && and OR instead of ||.

Remember also that some keywords are reserved by ENOVIA. For example evaluating that current state equals to "Exists" requires the usage of the "const" keyword since "Exists" is a reserved word; see example below:

To define the access to use a particular report definition, one can do this either based upon role or group assignment or to named users.

The access is defined like shown below:

+ E.g. a user having either the role "Engineer" or "Manager", or is member of the group "System Administrator", or the user actually is either Joe or Sue will have access to this report.

Defines the output format that is being used for the report. Currently, the following formats are available:

To define the output format within your report definition, use the syntax below:

If defined, this value is shown in the GUI on the page where the user selects a report. If undefined, the value of the Output Format is shown instead.

To define the displayed output format within your report definition, use the syntax below:

Defines the stylesheet (XSLT) to be used to convert the extracted data from ENOVIA with.

The value refers to an XML file or to a page object within the database that holds the content. To define the stylesheet within your report definition, use the syntax below:

Defines if the definition object is visible for the user when s/he is selecting a report to be created from the user interface.

For example, some report definitions are only used by triggers, hence these are not intended for use manually and setting the Hidden value to TRUE will make them unavailable.

To define the hidden value within your report definition, use the syntax below:

Defines the name of a custom JSP page that is invoked before the report is being created.

Using a pre-process page enables more control over the created report. Depending on the pre-process page – more or less sophisticated functionality may be added, but typically a form with some options are displayed and the user does some selection that finally applies to the final report. See this chapter for details regarding implementation details of pre-process pages.

To define a pre process page within your report definition, use the syntax below:

The path to the JSP page, must be context relative. E.g. start from the root of your web-application.

A report can be associated with a custom icon. This icon will be shown in the user interface where the user selects a report to be created. The purpose of associating a custom icon is to make it easier for the user to find the report to be created.

To define an icon, use the sytax below:

The path must be context relative, e.g. start from the root of your web-application.

Within the list of reports presented for the user, the order of appearance for the available reports can be adjusted.

To define the sort order, use the syntax below:

Defines different parameters that control the behavior of the report creation.

To define the settings/conversion properties within your report definition, use the syntax below:

The table below shows the different parameters that are adjustable. Note that each output handler or post processor, or other feature, might have support for additional settings that are not listed in this table.

Parameters that you pass to the XSLT transformation (your stylesheet) can be declared within the report definition. To define these, use the syntax below:

An expansion report is used to generate a report over the objects and connections inside one structure. This is equal to browsing the relationships going from or to the selected business object in the defined number of levels. For more information about expanding business objects, see the ENOVIA MQL guide.

The root element within an expansion based report definition must be <ExpansionReport>.

The expansion report has following configuration options.

The inquiry report uses an inquiry to retrieve the objects and relationships that will be included in the report. The inquiry report definition has the following configuration options.

Below are two examples that show how the inquiries should be constructed in order to work properly with the report generator.

NB: The name of the fields in the format part of the inquiry must be same as below.

Inquiry for retrieval of flat data (a list of object without relationship information):

An inquiry for structured data might look like this:

The inquiry report definition is very flexible. You may pass additional parameters in the URL that are sent further to the inquiry. This is accomplished by adding URL parameters to the command described in this chapter.

The arguments that can be passed to the inquiry must have the following syntax:

URL example:

The arguments that are passed must also be defined on the inquiry itself.

Following example illustrates how these custom parameters can be used to create a report of objects stored in a set. The inquiry will retrieve the id of the objects stored in a set, and the name of the set is passed as input parameter.

The advanced report definition allows dividing a report into sections, where each section contains data that is generated by evaluating one table over a set of objects / connections, which are provided by a so called dataset’s. The report might contain as many sections as needed to build up the complete report.

The definition of the data extraction logic is defined within the Report Definition configuration. For an example how such report is constructed, see the example below:

This report contains two sections; Information about all the revisions and information about the BOM structure below the item. These sections are evaluated using different tables.

The data-set defining the revisions looks like this: (/WEB-INF/tvc/dataset/Revisions.xml)

The data-set defining the EBOM structure looks like this: (/WEB-INF/tvc/dataset/EBOM.xml)

A table data section uses a table (system table or an XML defined table) and evaluates this table over the data returned by the data-set being used. Moreover, a section is in the final report grouped inside its own element, which is defined in the attribute "element" on the "TableDataSection" tag.

The minimum configuration requred for a Table-data-section, is to define a data set and a table. You can omit the table, however, then all basic properties including all attribute values are extracted for the business objects and connections, which the data-set returns.

The description element is optional, but can be used to provide a user friendly description describing the purpose of the section. This can be utilized from a pre-process page to allow the user to de-select a section from a particular report. There are two additional attributes that can be used to define the selection behavior of a section, namely: selectable and selected. The first one defines whether or not the user can control the inclusion of the section and the latter one defines if the section is selected by default or not. Below is an example where these attributes are used:

Moreover, the XMLSpec element allows you to configure how the XML data for this particular section should be formatted. The details are provided in the next chapter.

MQL output can be included by defining a MQLSection. This could either be just invoking a MQL command that returns XML output or invoking some other program that produces XML output.

See example below:

The sub elements of <MQLSection> are:

In case you have a need for creating a report that are not possible to create by using any of the previously mentioned Report Definition types, or you want to leverage some existing code within the Report Generator; you should use the "Custom Report" type.

This report definition type requires you to point out a Java class, which is derived from the base class com.technia.tvc.reportgenerator.impl.CustomReport.

Even though you have defined to use a certain post processor using the "postProcessors" property; it is possible to disable a particular processor by setting a different property. The example below will disable the PDF Stamp processor.

This can be utilized from a pre-process page to decide at runtime whether or not a post processor is enabled.

The following properties can be used to configure where the PDF should be stamped.

The "pdf.stamp.text" property may contain a macro.This chapter describes the possible macros that can be used.

The following properties can be used to configure the ZIP processor

Even though you have defined to use a certain output handler using the "outputHandlers" property; it is possible to disable a particular handler by setting a different property. The example below will disable the mail and ftp output handler.

This can be utilized from a pre-process page to decide at runtime whether or not an output handler is enabled.

The check-in handler can be used to either attach the report to the object for which the report is being created for (e.g. the context object), or create a new object to where the report will be checked in.

A new object can be created using a number generator. Current release supports using the object generators from the AEF/BPS or by using the number generators from TVC to generate new names. To setup object generators in the AEF/BPS, please consult the Framework/Business Process Services documentation. To setup a TVC number generator, see this chapter.

Once an object generator is configured, following properties are used to control which object generator to use.

Important notes:

Either if you check in the object to the original object or if you are creating a new one using an object generator, a set of additional settings can be specified in order to being able to check-in the report.

The following properties control the check-in:

The mail handler will send the mail to the user who initiated the report creation. A mail address must be specified on his/her person admin object.

The settings for mail sending is defined in the global page configuration object, but the following properties may be set/overridden in the report settings.

In order to have dynamic content in the mails that are sent, there are possibilities to use macros within the subject and mail message properties. This chapter describes the possible macros to be used.

The report is by default sent to the user that created the report. It is possible to change this behavior, and send the report to someone else.

The properties below can be used to define other recipients.

The property "mail.max.fileSize" can be used to disable the mail delivery in case the generated report is equal to or larger than the specified size. The size can be specified in various formats, example:

The FTP handler sends the report via FTP. Following properties controls the built in FTP handler:

The properties ftp.dir and ftp.file may contain macros. This chapter describes the possible macros to be used.

An example of how a macro could be used is shown below:

The property ftp.min.fileSize can be used to restrict the delivery of the report via FTP unless the size is greater than the specified value. See previous chapter regarding the mail delivery handler for details regarding the format of this value, including how this setting can be used in conjunction with the mail handler.

The ftp.sendNotification property can be used to inform the user about the delivery of the report to the FTP destination.

The "fileStore" output handler is used when the file should be stored on a mounted drive.

Following properties controls this outputhandler.

Both these properties may contain macros. This chapter describes the possible macros to be used.

An example of how a macro could be used is shown below:

The print output handler sends the report directly to the printer.

The printers should be pre-configured with the necessary drivers & available on the application server where the report generator component is running.

Following property controls this outputhandler.

It is also possible to pass a comma-separated list of printer names to the property above, in which case the report will be sent to each of the printers. The name of the printer, in this case, refers to the actual name of the printer as referred to by the operating system on the application server.

The above property could be statically defined in the report configuration or a more likely scenario is for them to be over-ridden at run time by the end user through a pre-process page.

Following table contains macros that may be used on some properties used by some of the output handlers.

Find the page object called TVC Report Generator Properties. Add or find the line containing "defaultUseLatestFOP". Set the value to either TRUE or FALSE:

Note that if you omit this line, or comment it out, the value will be treated as TRUE.

If any of those values return true, the setting made on a single report will never be used.

*This can, for example, be used to verify if the reports are compatible with the latest FOP or not, without having to modify the reports themselves. *

The example below illustrates how to configure the use of the latest FOP version on a per report basis.

If you don’t specify this value per report, the global setting will be used.

The sorting of the reports on the list page can be configured through a TVC init parameter (system parameter) through the web.xml file.

Below are some examples how this init parameter could be applied:

The first example is the default sort order in TVC if no other configuration has been made. It will sort the reports first by its format secondly by the display-name.

The second example will sort the reports by their internal name (the name of the business object or the name of the XML report).

The third example will utilize the sort-order value set on the report definition itself. This is either specified on the business object report through the "TVC Sort Order" attribute, or on the XML report as shown below:

All acceptable values for the init parameter are listed below: (they can be combined by separating them using the "," character (comma)).

By default, the ascending sort order is used, however, a "!" character before the property will force descending sort order.

You can associate an image to each report. By default, the system will try to figure out what icon to be shown depending on the output format. To customize what icon to be displayed, you should either use the attribute "TVC Icon" for business object defined report and for XML reports do as shown below:

A value containing date values, will be generated like following:

The mx-value is the date as formatted by ENOVIA. This will vary depending on the "ENOVIA ini-parameters".

The displayDate value is the value as formatted according to the locale, and the iso-date and iso-datetime contains ISO formatted dates with and without the timestamp.

Following table contains the parameters that automatically are passed to the transformer process.

SpreadsheetML is an XML format accepted by Microsoft Excel 2003 and later.

When producing reports following this standard, you need to specify the following on the report definition:

Below are some useful references that describe the SpreadsheetML format deeper:

http://msdn.microsoft.com/en-us/library/bb226687%28v=office.11%29.aspx

http://msdn.microsoft.com/en-us/library/bb226693%28v=office.11%29.aspx

POI is an open source library provided by the Apache organization for working with Microsoft Office files. Through POI, you can for example create native Excel files (XLS).

POI is part of the TVC-Core library, which RPT depends upon. The POI classes are available within the "com.technia.tvc.poi" package.

To create custom reports, see the developer documentation.

To summarize, you need do the following:

The table below illustrates the attributes being used.

The types Queue, Agent and Job have its own policies. These are described in the table below:

When the report generator is installed, you will have a folder under the WEB-INF directory in the web-application called "reportgenerator". This folder contains a Windows start script and a UNIX start script. These scripts are called:

The script has been made as generic as possible and to use it, you will typically invoke the script with the following arguments:

The first things you need to modify within these scripts are the following variables:

Example:

If you are running in RIP mode, you will need some additional Matrix related settings also in the script. However, it is out-of-scope in this document to describe the Matrix details.

On UNIX you can modify the MX_ENV_SCRIPT variable to point to a valid mxEnv.sh script.

The available values for the action argument provided to the script are defined in the table below:

Within the Report definition you define the stylesheet to be used using the <Stylesheet> element. E.g.

At runtime when the report is being created and the stylesheets are being resolved, they are resolved based upon the locale used when the report is being invoked. Many times this is the locale as the user has, however, the user may choose another locale (see chapter below).

Example: A french speaking user located in Canada has the locale fr_CA is about to create a report. When the stylesheet is resolved, the search order for the stylesheet to be used will in this case be:

The first found will be used.

Hence, within the language specific stylesheets, you can declare all your language specific variables and then finally include the language neutral templates that produces the output.

Example:

If you are launching the report generator through a direct link or via a command in a toolbar, you are most likely using the following URL:

By adding the parameter "locale" with a valid value, you can create multiple versions of such link/command. Example:

To support selecting the locale/language from a pre-process page, you need to in the pre-process page include a language chooser.

Example of such here:

When invoked via a trigger, one can override the locale via adding a parameter like this -locale=fr.

The request parameters that are submitted from the pre-process page must have one of three different prefixes, in order for the report generator to know how to handle them. These prefixes are:

The URL used to start the report creation from a pre-process page is generated by using following JSP custom tag:

The definition types "Expansion Report" and "Inquiry Report" are both using a "Table". Sometimes it is useful to allow the user to select columns to be included in the table. Following JSP code does this:

The definition type "Advanced Report" is built up by sections. The user can select sections that should be included / excluded from the report. Following JSP code does this:

A pre process page example showing how to add a printer selector is shown below. The bold marked sections show the related code for the printer selector. Everything else is just there for illustration purposes on how to create a complete working example.

It is possible to combine different data producers within a data-set. For example, you might want to use an inquiry for loading the root-nodes of a structure before you perform the expansion.

Or you need to expand in one direction to find some objects before you can expand those in a different direction along a different relationship pattern. All of this is described within the following chapter(s).

The data producer used for expanding a structure, Expand, can be driven by a nested Data Producer. E.g. the root nodes in the new structure can be originated from the result of a Query, Inquiry or another expansion. Or after have used any of the Flatten, EndItems or Filter elements that are described in the next chapters.

All in all, the data producers building up a data-set can be very powerful and you will be able to accomplish a lot without the need of writing any code at all.