Report Generator - Administration Guide : Configuring

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: