TIF ENOVIA/3DExperience Connector - Reporting

The TIF Reporting functionality is enabled/available if your TIF license contains the "reporting" component.

The TIF reporting module adds capabilities for generating reports from data in your ENOVIA/3DEXPERIENCE database.

This functionality was introduced in the 2024.5 release of TIF.

Please read the subchapters in this document to understand how to configure and use this feature.

Do not mix this component with neither of the products TVC Report Generator nor the ENOVIA/3DEXPERIENCE Report Generator. The TIF Reporting component is a stand-alone component running in TIF.

Usage

The creation of a TIF Report is done by triggering a job, whose Job Configuration is configured for Report creation.

One job can produce one or more reports as part of its execution. The job can be configured to transfer the produced reports to some destination once completed.

The reports are generated by first extract the necessary data from the ENOVIA/3DEXPERIENCE database using the payload configuration.

Once the data have been extracted, it needs to be transformed into the so-called "XSL-FO" format (see Wikipedia article) using XSLT transformations.

Configuration Format

An example of how the job configuration could look like is shown below.

<Job>
    <Name>BOM Report</Name>

    <CreateReport> (1)

        <Report name="BOMData.pdf"> (2)
            <Payload ref="tvc:payload:report1/BOM.xml" />
            <Transformer xslt="tvc:xslt:report1/BOMDataToFO.xslt">
                <Property name="test1" value="value1"/>
            </Transformer>
            <Generator type="fop">
                <Format>pdf</Format>
                <Properties>
                    <Title>BOM Report</Title>
                    <Producer>TECHNIA Integration Framework</Producer>
                </Properties>
				<PDFWatermark>
					<Definition>
						<Text>Hello world</Text>
						<StartX>20</StartX>
						<StartY>10</StartY>
						<FontSize>25</FontSize>
						<FontColor>rgb(255,0,0)</FontColor>
						<FontName>Arial</FontName>
					</Definition>
				</PDFWatermark>
            </Generator>
        </Report>

        <Destinations>  (3)
            <File id="file-dest-bomreport" />
            <!--
            <Http .../>
            <RabbitMQ id="rabbitmq-1" />
            <Checkin>
				<CheckinObject>
					<Append>true</Append>
					<ExistStrategy>overwrite</ExistStrategy>
					<Format>generic</Format>
					<UseCDM>true</UseCDM>
				</CheckinObject>
				<CreateObject>
                    ...
				</CreateObject>
				<ConnectObject>
                    ...
				</ConnectObject>
			</Checkin>
            -->
    	</Destinations>
    </CreateReport>
</Job>
1 This element declares that the Job will create a Report using the TIF Reporting functionality.
2 Here we declare one report to be created. It will use a specific Payload configuration for the data extraction AND a stylesheet to be used for converting the payload data into the XSL-FO format.

Additionally we also declare the generator used for generating the final PDF file
3 The destinations element is used for declaring where the final report or reports should be transferred.

The configuration details are defined in the subchapters below.

Create Report

The <CreateReport> element supports the following attributes.

Attribute Description Required

transferOneByOne

If your job produces more than one report, the default behavior is to wrap all reports into a ZIP file.

This attribute can be used to force a transfer of each report ony-by-one

No.

Default is FALSE.

Payload Element

The <Payload> element is used to either reference a payload configuration or declare the payload inline.

<Payload inline="true"> (1)
    ... (2)
</Payload>
1 If declared inline, the inline attribute needs to be set to true
2 The payload definition goes here. Please see this document for more details. 
<Payload ref="MyPayload.xml" /> (1)
1 Referencing the file ${TIF_ROOT}/modules/enovia/cfg/payload/MyPayload.xml.

Transformer Element

You need to configure a transformer that is capable of transform the payload data into the XSL-FO format.

To do so, you setup one or more transformers.

In its simplest form, you point out one XSLT stylesheet like below.

<Transformer xslt="tvc:xslt:report1/BOMDataToFO.xslt" />

It is possible to chain multiple stylesheets like below:

<Transformer xslt="tvc:xslt:report1/First.xslt" />
<Transformer xslt="tvc:xslt:report1/Second.xslt" />
<Transformer xslt="tvc:xslt:report1/Final.xslt" />

Passing properties to a transformer is done like below:

<Transformer xslt="tvc:xslt:report1/ToFO.xslt">
    <Property name="p1" value="v1" />
    <Property name="p2" value="v2" />
</Transformer>

See this chapter for additional details.

Some aspects of the actual stylesheets are discussed below.

Generator

The <Generator> element controls the generation of the final report from the XSL-FO data.

The supported type currently is fop and implies the Apache FOP processor. Thus omitting this attribute implies the fop as default. Future releases may add support for other generators.

<Generator type="fop">
    <Format>pdf</Format>(1)
    <Properties>(2)
        <Title>...</Title>
        <Producer>...</Producer>
        <Author>...</Author>
        <Creator>...</Creator>
        <Keywords>...</Keywords>
        <Subject>...</Subject>
    </Properties>
</Generator>
1 Defines the output format. The possible formats supported by the fop generator are:
raw

Produces the "raw" XSL FO data only

pdf

PDF output (The default if not specified)

rtf

RTF output

ps

Postscript

eps

Encapsulated Postscript

pcl

PCL format
2 Declares document properties.

PDF Watermark

A watermark can optionally be applied to the generated PDF report.

An example:

<Report name="BOMData1.pdf">
    ...
    <Generator type="fop">
        <Format>pdf</Format>
		<PDFWatermark>
			<Definition>
				<Text>Hello world</Text>
				<StartX>20</StartX>
				<StartY>10</StartY>
				<FontSize>25</FontSize>
				<FontColor>rgb(255,0,0)</FontColor>
				<FontName>Arial</FontName>
			</Definition>
		</PDFWatermark>
    </Generator>
</Report>

The report watermarking functionality utilizes the Java File Modifier from the TIF Batch Jobs module, specifically its <PDFWatermark> configuration.

Configuration options for <PDFWatermark> are described in the Batch Jobs documentation here and here. However, some options defined in <PDFWatermark> — such as <Checkin> and <Handler> — are not applicable in the report context.

Destinations

The <Destinations> element is used for declaring where the file report or reports should be transferred.

File Check-in Destination

The <Destinations> element also supports a special <Checkin> destination that can be used for checking in the final reports to the source object or e.g. to a new related object.

The <Checkin> element supportss the following attributes.

Attribute Description Required

triggerOff

Specifies whether to perform the check-in handler with triggers disabled

No.

className

Specifies the class name of a custom Java handler that customizes the behavior of the file check-in process.

The class can either extend com.technia.tif.enovia.job.destination.checkin.DefaultCheckinHandler or implement the interface com.technia.tif.enovia.job.destination.checkin.CheckinHandler.

No.

The <Checkin> element supports the following sub-elements.

Element Description Required

<CheckinObject>

This element contains configuration options for the file check-in.

Check the sub-chapter below for details.

No.

<CreateObject>

This element contains configuration options for creating a related object in which to check in the final report.

Check the sub-chapter below for details.

No.

<ConnectObject>

This element contains configuration options for connecting the newly created related object to the source object.

Check the sub-chapter below for details.

Required if <CreateObject> is specified.

The <CheckinObject> element supportss the following sub-elements.

When creating multiple reports, the final report is stored into a ZIP archive by default. Alternatively, you can set the transferOneByOne boolean attribute to true to check in the actual report files one by one.
Element Description Required

<Append>

Specifies whether to append the file. Use the boolean values true or false.

No. Default is true.

<UseCDM>

This element specifies whether to apply CDM on the check-in. Use boolean true or false

No. Default is false.

<ExistStrategy>

This element specifies the strategy to apply when there is an existing file with the same name.

The valid values are:

  • fail: Throws an exception.

  • newversion: Creates a new version by applying CDM model

  • overwrite: Overwrites the existing file

No. Default is fail.

<FileName>

Specifies a file name to be used for the check-in.

This setting is usually not needed. By default, the file name is derived from the name attribute in the <Report> element. Do not use this setting if there are multiple files to check in.

No.

<Format>

This element specifies a format for the check-in.

No.

The <CreateObject> element supports the following sub-elements.

Element Description Required

<Generator>

This element specifies the type of a generator to be used while creating the related object.

The valid values are:

  • aef: Use object generator from AEF/BPS.

  • tvc: Use TVC name generator.

No. Default is aef.

<GeneratorName>

Name of the generator.

No. If not specified, the first number for the specified type is used.

<GeneratorRevision>

Revision of the generator.

No.

<GeneratorCreateAdditional>

Specifies the create-additional flag for an AEF generator. Use boolean true or false

No. Default is false.

<GeneratorCreateAsSuperUser>

Specifies whether to run the generator as super-user. Use boolean true or false.

No. False if not specified.

<Type>

The type of the object to create.

True.

<Policy>

The policy governing the object.

No. If omitted, the best suited policy for the specified type will be used.

<Revision>

The revision of the object.

No. If omitted, the first revision in the sequence defined on the policy will be used.

<Vault>

The name of the vault to hold the object.

No. If omitted, the same vault as the object for which the report is created will be used. If the report is not created around a business object (e.g., it’s a global report), the "eService Production" vault is assumed.

The <ConnectObject> element supports the following sub-elements.

The <ConnectObject> element is only valid if the <CreateObject> element is also present in the configuration.
Element Description Required

<Relationship>

Name of the relationship to connect the newly created object with the source object.

Yes.

<Direction>

The direction of the relationship. Valid values are from and to.

No. Default is from.

Stylesheets

The stylesheets used should be placed within a directory called xslt somewhere within the ${TIF_ROOT}/modules/enovia/cfg directory of the TIF installation.

Some examples:

  • ${TIF_ROOT}/modules/enovia/cfg/xslt

  • ${TIF_ROOT}/modules/enovia/cfg/report1/xslt

The stylesheets are resolved using the same configuration resolving strategy as used in TIF in other places. TIF uses the TVC framework for this, and if you are familiar with TVC then this follows the same principles.

See the chapter Configuration files for more details.

Reusing Logic

The XSLT stylesheets may become large and to allow reusing formatting across different reports, such as header and footer sections; one can divide the stylesheets into smaller reusable parts.

The xsl:include directive can be used to include the other stylesheets. This is illustrated in the example below.

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                version="1.0">
    <xsl:include href="tvc:xslt:common/StyleAttributes.xslt"/>
    <xsl:include href="tvc:xslt:common/Header.xslt"/>
    <xsl:include href="tvc:xslt:common/Footer.xslt"/>
    ....
</xsl:stylesheet>

Images

To embed an image into the PDF report, there are some different options available depending on where the image is located.

In XSL FO images are declared using the external-graphic element.

<fo:block>
    <fo:external-graphic border-width="0" content-width="5cm" src="etc/resources/logo.svg" />
</fo:block>

If a simple file is referenced, a relative path is resolved against the root directory of the TIF server.

An image can also be resolved from a file checked-in to a business object in the ENOVIA/3DEXPERIENCE database. In such cases, the URL to the image will follow this syntax:

custom://busfile/<object-id>/<format>/<file-name>

Example:

custom://busfile/53160.3064.55240.19232/mxImage/test.png

The number of checked-in files included in the report may impact the final size of the report as well as the overall time taken to produce the report as the file check-out operations may be expensive for larger images.