TIF ENOVIA/3DExperience Connector - Batch Jobs

A batch job in TIF is a job that typically performs some operation onto files and/or objects inside the ENOVIA/3DEXPERIENCE database.

Example of batch job could be converting Microsoft Word™ document into PDF and apply a watermark upon release of the document object.

File Modification - Overview

TIF provides functionality for performing batch operations on files checked in to ENOVIA/3DEXPERIENCE. The kind of operations supported are:

  • Converting Microsoft Word, Excel and PowerPoint files into PDF

  • Setting document properties on Microsoft Word, Excel and PowerPoint files

  • Adding watermark to PDF files

This feature has been part of TIF since its first release. However, the first implementation required the TIF instance performing the conversion jobs to be run on a Windows machine. This first implementation is referred to as Modifier for Windows.

Now, TIF also contains an implementation in Java, which performs most of the operations within the JVM using some open-source libraries to perform the different tasks with.

Some operations could also be dispatched to an external process, for example invoking a program such as Adlib™ that does the conversion. This implementation is referred to as Modifier for Java.

The next chapters describes the different implementations.

The Java Modifier is not a drop-in replacement for the Windows Modifier. There will be differences in the output depending on the content of the files.

When using the File Modifier feature on a TIF instance running on Windows, the "windows" implementation is per default selected unless otherwise configured.

On any other platform, the Java implementation will be the default and the Windows implementation cannot be chosen.

File Modifier - Windows

This functionality only works if TIF is running on a Windows based OS. If you are using Linux/UNIX OS’es and want to use this implementation, one option is to set up an additional TIF instance running on a Windows OS, and configure that TIF instance to process jobs from one dedicated queue.

Then you just have to ensure that all jobs that are performing file modifications as describe in this page is using that dedicated queue.

If a Windows based OS is not available, switch to use the Java based implementation. See chapter Custom Java implementation below.

Windows Service

If you run TIF as a service, ensure that the following folders exists in the filesystem:

32bit-server

C:\Windows\System32\config\systemprofile\Desktop

64bit-server

C:\Windows\SysWOW64\config\systemprofile\Desktop

Note also that you may need to configure the service to run as a specific user. See image below:

image
Figure 1. Windows Service Settings

Additionally, you may also need to configure the DCOM settings in Windows like shown in the images below:

image
Figure 2. DCOM settings for Excel

and

image
Figure 3. DCOM settings for Word

The user selected should be the same user as running the TIF Service.

The component services can be started via WINDOWS-R (Run):

mmc comexp.msc

Windows Pre Conditions

The following software needs to be installed on the server for PDF functionality:

  • Microsoft .NET version 4 (or newer)

  • Microsoft Office 2007 (or newer)

In some cases you might also need to disable the User Account Control (UAC).

Usage

Depending on the event that triggered a file modification job, the job may get information about one particular file from the business object in question to operate upon. That is for example the case if the job was initiated via a checkin-event. However, for other events that triggers the file modification job, TIF will then operate upon all files attached to the business object in question.

To start with, below is an example job configuration showing how to utilize the file modification functionality.

<Job>
    <Name>Convert to PDF</Name>

    <FileModifier>
        <FileFilter
            includeFormats="generic,other"
            excludeFileNames="*.pdf"/>

        <!-- or
        <FileFilter
            excludeFormats="PDF"
            includeFileNames="*.*"/> -->

        <UpdateProperties>
            <PropertyHandler>com.acme.foo.MyPropertyHandler</PropertyHandler>
            <Property name="Property 1" selectExpression="type"/>
            <Property name="Property 2" selectExpression="attribute[attribute_Foo]"/>
        </UpdateProperties>

        <CreatePDF>
            <ExcelOptions>
                <MarginTop>10</MarginTop>
                <MarginRight>10</MarginRight>
                <ScaleToFit>true</ScaleToFit>
            </ExcelOptions>
        </CreatePDF>

        <PDFWatermark>
            <Definition condition="current == Released">
                <Text>${current}</Text>
                <FontSize>72</FontSize>
                <FontColor>rgb(0,255,0)</FontColor>
                <TextRotation>45</TextRotation>
            </Definition>
            <Definition>
                <Text>NOT RELEASED (${current})</Text>
                <FontSize>144</FontSize>
                <FontColor>rgb(255,0,0)</FontColor>
            </Definition>
            <Checkin format="PDF" fileName="${name}.pdf"/>
        </PDFWatermark>
    </FileModifier>
    <Events>
        <Error>
            ...
        </Error>
    </Events>
</Job>

The example above will be executed only if the object (which the job is running against) has a file checked in under the format "generic" or "other" and not ending with ".pdf". Shortly, what happens in this case is:

Properties are updated on the file

The example here illustrates the usage of a custom class defining key/values to set as well as defining properties mapped to select-expression.

Secondly, a PDF is created

If the source file is an Excel file then there are some additional settings available for handling margins / scaling.

Finally, watermarking

A watermark is applied to the PDF file and the final PDF file is checked-in to ENOVIA/3DEXPERIENCE under the PDF format. The actual watermark text is selected based upon the if condition.

The root tag in the definition is always <Job>. The first child element of the Job element defines the kind of job, in this case we will use the <FileModifier> element to define the use of the file modification functionality.

Below the FileModifier element, the following child elements are available.

<FileFilter>

Defines what files to perform operation upon.

<UpdateProperties>

Defines that the document properties shall be updated

<CreatePDF>

Converts the Office document into PDF and optionally also adds cover/title page and/or ending page.

<PDFWatermark>

Applies a PDF watermark to the PDF file

The child pages will go through the configuration possibilities in more detail.

File modification jobs support job events for handling errors etc. Read more in the Job Events chapter.

File Filter

The <FileFilter> element is used to define what files to operate on. A business object may have several files attached and they may be attached into different formats (ENOVIA/3DEXPERIENCE feature).

On the <FileFilter> element, you have a couple of attributes that can be used to define either inclusion rules or exclusion rules. See table below:

Attribute Description

includeFormats

Comma separated list of formats to accept

excludeFormats

Comma separated list of formats to reject

includeFileNames

Comma separated list of file name patterns to accept

excludeFileNames

Comma separated list of file name patterns to reject

if

Comma separated list of parameter names that should be present in order for the filter to accept the file. The parameters are resolved from the originating job.

unless

Comma separated list of parameter names that NOT must be present in order for the filter to accept the file.
The values of the parameter specified in either the if and/or unless attribute are not relevant. We are only checking the presence of such parameter.

Example:

<Job>
    <FileModifier>
        <FileFilter
            if="special.condition"
            includeFormats="format_Generic,format_SomeOther,format_AThirdFormat"
            includeFileNames="*.doc,*.docx"/>
        ...
    </FileModifier>
</Job>
The patterns are case insensitive.

Update Properties

The <UpdateProperties> element defines that you want to update the document properties on the file (only for Microsoft Office™ files such as Word™, Excel™, Powerpoint™).

You may point out a Java class that provides the properties (key/value pairs) to set and/or define in the configuration properties mapped to some select expression that in turn gives the value for the property.

The possible child elements are listed in the table below:

Child Element Description Example

<Property>

Defines a single property to be transferred to the document.

<Property name="Type" selectExpression="attribute[Product Type]"/>

<DefaultProperties>

Defines that the default property handler provided by TIF shall be used.

<DefaultProperties prefix="MX" suffix=""/>

<PropertyHandler>

Points out a Java class implementing the interface com.technia.tif.enovia.job.executors.file.PropertyHandler

<PropertyHandler>com.acme.integrations.file.SetProperties</PropertyHandler>

<Checkin>

If you want to check-in the document after the properties has been set, use this element to do so.

<Checkin/>

<Checkin overwrite="true"/>

<Checkin format="some other format" fileName="${name}.modified.${ext}"/>

<Checkin fileName="${name}.pdf" className="com.acme.tif.CustomCheckin" />

Property

Defines a property to be transferred.

Example

<UpdateProperties>
    <Property name="Type" selectExpression="${attribute[attribute_ProductType]}"/>
    <Property name="Status" selectExpression="current"/>
</UpdateProperties>

Default Properties

This element uses a default property handler available inside TIF. This property handler will extract a large amount of properties from the business object and propagate it to the file.

This property handler provides the same/similar properties as done in the TVC File Manager application.

The prefix and suffix attributes are optional and may be used to add a prefix/suffix to the property name.

Custom Property Handler

The interface com.technia.tif.enovia.job.executors.file.PropertyHandler is defined as below:

package com.technia.tif.enovia.job.executors.file;

import java.util.Map;
import com.technia.tvc.core.TVCException;

public interface PropertyHandler {

    /**
     * Returns the properties for a specific file/object/format combination.
     *
     * @param objectId The ID of the business object, which the file belongs to.
     * @param format The format, which the file is being checked in to
     * @param fileName The name of the file
     * @return A {@link Map} containing string keys and values representing the
     *         properties to transfer
     * @throws TVCException When some DB communication occurs.
     */
    Map<String, String> getProperties(String objectId, String format, String fileName) throws TVCException;
}

Checkin

Optionally, you may want to check in the file containing the modified properties. If so, then use the <Checkin> element for that.

Without any attributes specified, the file will be checked in using the same name and format. If the file is checked-in to a CDM object (Common Document Model) a new version will be created unless the "overwrite" attribute has been set to true.

Supported attributes are:

fileName

The file name to check-in to (if undefined, same file name is used).

Note that you may use the following macros:

${filename} : the original filename (full name)

${name} : the original filename excluding the file extension

${ext} : the original file-extension

format

The format to check in to (if undefined, same format is used).

overwrite

Boolean (default is false) specifying if to overwrite the current version with the modified file. False causes a new version (CDM version) to be created.

className

Check-in can be optionally customized with a Java class. The class must either implement the interface com.technia.tif.enovia.job.executors.file.CheckinAction or extend the default action com.technia.tif.enovia.job.executors.file.DefaultCheckinAction.

For example:

import com.technia.tif.enovia.job.executors.file.CheckinContext;
import com.technia.tif.enovia.job.executors.file.CheckinResult;
import com.technia.tif.enovia.job.executors.file.DefaultCheckinAction;

public class CustomCheckin extends DefaultCheckinAction {

    @Override
    public CheckinResult checkinFile(CheckinContext context) {
        CheckinResult result = super.checkinFile(context);
        // TODO: Add your custom code here...
        return result;
    }

}
The default check-in action persists information about the check-in. The information is persisted as job parameters, which are visible in the Admin UI. The parameters can be utilized e.g. when triggering new job or sending mail via job event handlers. See job parameters starting with prefix fileCheckin.

Create PDF

The <CreatePDF> element defines that you want to convert the Microsoft Office file into a PDF file.

The possible child elements are listed in the table below:

Child Element Description Example

<ExcelOptions>

Defines additional options that applies to conversion of a Microsoft Excel file into PDF

<ExcelOptions> …​ </ExcelOptions>

<WordOptions>

Defines additional options that applies to conversion of a Microsoft Word file into PDF

<WordOptions> …​ </WordOptions>

<ISO>

Defines if the ISO standardized PDF format (archive) should be used.

<ISO>true</ISO>

<ISO>false</ISO>

<Checkin>

If you want to check-in the generated PDF file, use this element to do so

<Checkin format="some other format" fileName="${name}.pdf"/>

<TitlePage>

Can be used to merge a title page with the main PDF document

See below

<EndingPage>

Can be used to merge another document with the main PDF at the end.

The title page and ending page elements are configured in the same way.

See below

Excel Options

The ExcelOptions element can have the following child elements:

Child Element Description Example

<MarginTop>

Defines the top margin

<MarginTop>40</MarginTop>

<MarginRight>

Defines the right margin

<MarginRight>40</MarginRight>

<MarginBottom>

Defines the bottom margin`

<MarginBottom>100</MarginBottom>

<MarginLeft>

Defines the left margin`

<MarginLeft>200</MarginLeft>

<PageOrientation>

Page orientation for the PDF file. Possible values are "landscape" and "portrait"

<PageOrientation>portrait</PageOrientation>

<ScaleToFit>

A boolean specifying if to scale the Excel sheet to fit the PDF page

<ScaleToFit>true</ScaleToFit>

Word Options

The WordOptions element can have the following child elements:

Child Element Description Example

<Bookmarks>

Defines if to export bookmarks to PDF.

The accepted values are:

  • headings: Create bookmarks using headings in document.

  • word: Create bookmarks using Word bookmarks in document.

<Bookmarks>headings</Bookmarks>

<DocStructureTags>

Specifies whether to include extra data to help screen readers. Default value is true.

<DocStructureTags>false</DocStructureTags>

Checkin

See above.

TitlePage and EndingPage

Both these elements are used to when you need to merge another document with the main PDF document. The other document to merge can either be a file from the local file system, or, a file checked into an object inside the ENOVIA/3DEXPERIENCE database.

The other document you point out can be an Office document OR a PDF document. If it is an Office document, the same properties as declared for the main document will be set on the document (unless configured not to, see below) before it is being converted into PDF.

Below are two examples how to use the <TitlePage> configuration:

<FileModifier>
    <CreatePDF>
        <Command>C:/Program Files/LibreOffice/program/soffice.exe</Command>
        <Command>-env:UserInstallation=file:///${workdir}</Command>
        <Command>--nolockcheck</Command>
        <Command>--headless</Command>
        <Command>--convert-to</Command>
        <Command>pdf</Command>
        <Command>${file}</Command>

        <Extensions>doc;docx;ppt;pptx;xls;xlsx</Extensions>
        <Timeout>60000</Timeout>
        <OutputFile>${fileprefix}.pdf</OutputFile>

        <TitlePage if="someproperty" unless="anotherproperty"> (1)
            <Template> (2)
                <Query type="type_Document"
                       name="DOC-000010"
                       vault="vault_eServiceProduction"
                       limit="1"
                       where="revision == last AND ${attribute[attribute_IsVersionObject]} == 'False'"
                       format="format_generic"
                       fileName="FrontPage.docx" />
            </Template>
        </TitlePage>
        <EndingPage condition="current == 'Release' and ${attribute[attribute_Title]} != ''"> (3)
            <Template omitProperties="true"> (4)
                <File fileName="${TIF.DATADIR}/templates/EndPage.pdf" />
            </Template>
        </EndingPage>

        <Checkin fileName="${filename}_no_watermark.pdf"/>
    </CreatePDF>
</FileModifier>
1 The if / unless attributes can be used to conditionally evaluate if to include the other document. These if/unless checks if corresponding property is present among the Job parameters
2 This template is living inside the ENOVIA/3DEXPERIENCE database. The query must return exactly ONE object and the format/file name combination must match with ONE file from this object.
3 In addition to if/unless, the attribute condition may contain an expression that is evaluated against the current business object - and if evaluated to false will omit merge with the template.
4 The template is located on the disk available for the TIF server. Note also that we here have explicitly configured to not set any properties. In this case it is redundant as there is no support for setting any PDF file properties.
The more narrow query you declare, the better performance you will gain once TIF is querying the DB for the template.

The following attributes are available on the <Query> element:

Attribute Description Example

type

Declares the type pattern.

type_Document

name

Declares the name pattern

DOC-*

revision

Declares the revision pattern

A1,B1

owner

Declares some Owner pattern

DocUser

vault

Declares the vault pattern

vault_eServiceProduction,vault_AnotherVault

limit

Declares a query limit

1

where

Specifies some additional where clause

revision == last AND ${attribute[attribute_IsVersionObject]} == 'False'

format

Specifies the file format.

format_generic

fileName

Specifies the file name

NameOfFile.docx

Some tips:

  • The type, vault and format attributes accepts symbolic names.

  • The where expression may contain expressions with symbolic names if wrapped inside ${}

  • Neither the format nor the fileName attributes are required, but needed in order to uniquely find the template file. So if the document only have one file, these can be omitted.

PDF Watermark

The <PDFWatermark> is used to define how to generate (or add) watermarks onto a PDF file.

You may have several watermark definitions and depending on some condition of the business object, for example if the object itself is in a particular state you may want to use a different watermark definition than in other cases.

This is implemented by allowing you to specify an ENOVIA/3DEXPERIENCE expression that should evaluate to true on the current business object holding the PDF file.

The possible child elements are listed in the table below:

Child Element Description Example

<Definition>

Contains the watermark definition (specified by child elements).

You may add several "Definition" elements using different "conditions".

Note that the first Definition whose condition evaluates to true on the current business object will be used.

 
<Definition condition="current matchlist 'Release,Approved' ','">
    ...
</Definition>

<Checkin>

If you want to check in the generated PDF file, use this element to do so.

<Checkin format="some other format" fileName="${name}.pdf"/>

Images

Alternate to text, you may also add image onto a PDF file.

Please note image transformations such as rotation or transparency are not supported. Instead, use an external image manipulation tool to rotate the image and/or save it in a format that supports the transparency, such as PNG.

Definition

The <Definition> element may have an attribute named "condition" containing an ENOVIA/3DEXPERIENCE expression, which if evaluated to TRUE for the current business object result then is used to create the watermark.

The expression itself must be a valid ENOVIA/3DEXPERIENCE expression and you can test your expression from for example MQL via the following syntax:

print businessobject 1.2.3.4 select evaluate[YOUR EXPRESSION] dump;

example:

<MQL> print businessobject 1.2.3.4 select evaluate[current matchlist 'Release,Approved' ','] dump;

If you omit the "if" attribute or let it be empty, it will evaluate to TRUE for any business object.

The <Definition> elements are evaluated in the order they are defined.

The possible child elements are listed in the table below:

Child Element Description Example

<Text>

Contains the text definition.

You may mix static text along with macros referring to select statements that will be evaluated against the business object holding the file.

Alternate to static text along with macros is to point out a custom Java class that provides the text. The class must implement the interface com.technia.tif.enovia.job.executors.file.TextProvider.

<Text>Current state is ${current} and attribute x is $\{attribute[attribute_X]}</Text>

<Text>${type}, ${name}:${revision} (${current})</Text>

<Text className="com.acme.tif.MyTextProvider" />

<FontName>

The name of the font to be used. Default is Arial

<FontName>Verdana</FontName>

<FontSize>

The size of the font to be used. Default is 50.

<FontSize>72</FontSize>

<FontColor>

Defines the color of the font. Different ways of specifying the color is supported, for example:

  • RGB value. Example: rgb(255,124,92)

  • HEX Value. Example: #FFEA00

  • Named color. Example: black, red, white, yellow, green, blue

The default color is black.

<FontColor>rgb(127,56,24)</FontColor>

<FontColor>red</FontColor>

<FontColor>#ae0122</FontColor>

<TextRotation>

Defines the rotation in degrees. -360 - 360 are allowed values. Default value is 0.

<TextRotation>45</TextRotation>

<TextTransparency>

Defines the transparency of the watermark. Allowed values are in the range 0 to 255. Default is 255.

<TextTransparency>100</TextTransparency>

<Count>

Number of times the text is printed between (start-x, start-y) and (end-x, end-y). Default is 1.

<Count>4</Count>

<StartX>

Start position on X-axis. Valid value is a percentage between 0 and 100. Default is 50.

<StartX>50</StartX>

<StartY>

Start position on Y-axis. Valid value is a percentage between 0 and 100. Default is 50.

<StartY>0</StartY>

<EndX>

End position on X-axis. Valid value is a percentage between 0 and 100. Default is 50.

<EndX>50</EndX>

<EndY>

End position on Y-axis. Valid value is a percentage between 0 and 100. Default is 50.

<EndY>100</EndY>

<ImageFileName>

Defines file name of an image to be used as a watermark.

<ImageFileName> can be either a local file path or a file URL along with TIF macros. Alternate is to point out a custom Java class that provides the file name. The class must implement the interface com.technia.tif.enovia.job.executors.file.FileNameProvider.

<ImageFileName>c:\pictures\picture.jpg</ImageFileName>

<ImageFileName>$\{tif.home}$\{job.param.imageFileName}</ImageFileName>

<ImageFileName className="com.acme.tif.MyFileNameProvider" />

<ImageStartX>

Image start position on X-axis. Valid value is a percentage between 0 and 100. Default is 50.

<ImageStartX>0</ImageStartX>

<ImageStartY>

Image start position on Y-axis. Valid value is a percentage between 0 and 100. Default is 50.

<ImageStartY>0</ImageStartY>
Windows version of File Modifier assumes the position (0,0) is top left corner of PDF page.

Checkin

See above

Custom Text Provider

The interface com.technia.tif.enovia.job.executors.file.TextProvider is defined as below:

package com.technia.tif.enovia.job.executors.file;

import com.technia.tif.enovia.job.EnoviaJob;
import com.technia.tvc.core.TVCException;

public interface TextProvider {

    /**
     * Returns text for a specific job/file/object/format combination.
     *
     * @param job Job object
     * @param objectId The ID of the business object, which the file belongs to.
     * @param format The format, which the file is being checked in to
     * @param fileName The name of the file
     * @return Text
     * @throws TVCException When some DB communication occurs.
     */
    String getText(EnoviaJob job,
                   String objectId,
                   String format,
                   String fileName) throws TVCException;

}

File Modifier - Java

Instead of using TIF’s built-in Windows based file modifier, it is possible to run File Modifier via Java implementations / via external processes such as Adlib™ PDF Converter or LibreOffice PDF converter.

To enable Java implementation, the attribute type must be present with value java in the configuration element FileModifier. On non Windows platforms, this is however not needed, since the Java implementation is the default selected. However, for clarity it is recommended to specify that.

The default implementations in Java are implemented as described below:

UpdateProperties

Uses the Apache POI library to set document properties.

CreatePDF

Invokes an external process for the creation of the PDF document. For example you can use Adlib™ PDF converter or LibreOffice to conduct the conversion.

PDFWatermark

Uses the Java library iText (version 2.1) for applying the watermark.

Below is a complete example illustrating how to use the Java file modifier

<Job>
    <Name>PDF Converter</Name>
    <FileModifier type="java">

        <FileFilter
            includeFormats="generic"
            includeFileNames="*.docx"/>

        <UpdateProperties>
            <DefaultProperties prefix="MX" suffix=""/>
            <Checkin fileName="${filename}"/>
        </UpdateProperties>

        <!-- NOTE: Use one of the below CreatePDF elements -->
        <CreatePDF implementation="adlibPDFConverter">
            <Input destinationId="adlib-in-folder" />
            <Output destinationId="adlib-out-folder" />
            <Error destinationId="adlib-err-folder" />
            <Checkin fileName="${filename}.pdf"/>
        </CreatePDF>

        <!-- OR Use this: -->
        <CreatePDF>
            <Command>C:/Program Files/LibreOffice/program/soffice.exe</Command>
            <Command>--headless</Command>
            <Command>--convert-to</Command>
            <Command>pdf</Command>
            <Command>${file}</Command>

            <Extensions>doc;docx;ppt;pptx;xls;xslx</Extensions>
            <Timeout>60000</Timeout>
            <OutputFile>${fileprefix}.pdf</OutputFile>

            <Checkin fileName="${filename}.pdf"/>
        </CreatePDF>

        <PDFWatermark allowMultiple="true">
            <Definition if="current == 'Preliminary'">
                <Text>${current}</Text>
                <FontSize>30</FontSize>
                <FontColor>rgb(255,0,0)</FontColor>
                <TextRotation>-45</TextRotation>
                <StartX>15</StartX>
                <StartY>15</StartY>
                <TextTransparency>50</TextTransparency>
                <Count>1</Count>
            </Definition>
            <Definition if="current == 'Released'">
                <Text>RELEASED</Text>
                <FontSize>50</FontSize>
                <FontColor>rgb(0,255,0)</FontColor>
                <TextRotation>45</TextRotation>
                <StartX>15</StartX>
                <StartY>15</StartY>
                <TextTransparency>70</TextTransparency>
                <Count>1</Count>
            </Definition>
            <Checkin fileName="${filename}.pdf"/>
        </PDFWatermark>

    </FileModifier>
</Job>

Update Properties

Follows the same format and syntax as described above for the Windows File Modifier implementation. The difference is that this implementation performs the property update using the Apache POI library.

See Update Properties above.

Create PDF - Using External Program

Create PDF will per default assume that you use an external program that converts the input file to PDF. E.g. the attribute implementation="externalFileConverter" on the <CreatePDF> element is the default value unless otherwise specified.

Starting with an example below:

<Job>
    ...
    <FileModifier type="java">
        ...
        <CreatePDF>
            <Command>/opt/LibreOffice/program/soffice</Command>
            <Command>-env:UserInstallation=file://${workdir}</Command>
            <Command>--nolockcheck</Command>
            <Command>--headless</Command>
            <Command>--convert-to</Command>
            <Command>pdf</Command>
            <Command>${file}</Command>

            <Extensions>doc;docx;ppt;pptx;xls;xslx</Extensions>
            <Timeout>60000</Timeout>
            <OutputFile>${fileprefix}.pdf</OutputFile>

            <Checkin fileName="${filename}.pdf"/>
        </CreatePDF>
    </FileModifier>
    ...
</Job>

There is a legacy format accomplishing the same, which is shown below for reference. Note however that this format should not be used.

<Job>
    ...
    <FileModifier type="java">
        <CreatePDF implementation="externalFileConverter">
            <Arg name="commands"   value="C:/Program Files/LibreOffice/program/soffice.exe;--headless;--convert-to;pdf;${file}" />
            <Arg name="extensions" value="doc;docx;xls;xlsx;ppt;pptx" />
            <Arg name="timeout"    value="60000" />
            <Arg name="outputFile" value="${fileprefix}.pdf" />

            <Checkin fileName="${filename}.pdf"/>
        </CreatePDF>
    </FileModifier>
    ...
</Job>

You can also configure default configurations within ${TIF_ROOT}/modules/enovia/etc/module.custom.properties. These will be used in case you omit something in the Job Configuration itself. E.g. if you don’t specify any command in the job configuration, TIF will look for such in the property file.

# A ; separated list of allowed file extensions
externalFileConverter.extensions=
#  A ; separated list containing commands to launch converter process with arguments
externalFileConverter.commands=
# Converter process timeout in milliseconds
externalFileConverter.timeout=
# Expected output file name after conversion
externalFileConverter.outputFile=

Supported macros in the configuration:

Macro Description

${file}

Input file name

${workdir}

The current working directory using forward slashes as directory separator char

${workdir_win}

The current working directory using Windows backslash char as directory separator char

${fileprefix}

Input file name prefix (for example: test.docx → test)

${filesuffix}

Input file name suffix (for example: test.docx → docx)

${iso}

Value of configuration element <ISO>

${scaletofit}

Value of configuration element <ScaleToFit>

${marginbottom}

Value of configuration element <MarginBottom>

${marginleft}

Value of configuration element <MarginLeft>

${marginright}

Value of configuration element <MarginRight>

${margintop}

Value of configuration element <MarginTop>

Below are examples how to configure externalFileConverter to call LibreOffice in headless mode to convert MS Office document to PDF and finally check in the converted PDF.

Example 1: Job configuration and module.custom.properties

Job configuration:

<Job>
    ...
    <FileModifier type="java">
        <CreatePDF implementation="externalFileConverter"> (1)
            <Checkin fileName="${filename}.pdf"/>
        </CreatePDF>
    </FileModifier>
</Job>
1 Implementation attribute can be omitted, since the external file converter is the default implementation.

${TIF_ROOT}/modules/enovia/etc/module.custom.properties:

externalFileConverter.extensions=doc;\
    docx;\
    ppt;\
    pptx;\
    xls;\
    xlsx
externalFileConverter.commands=C:/Program Files/LibreOffice/program/soffice.exe;\
    --env:UserInstallation=file:///${workdir};\
    --nolockcheck;\
    --headless;\
    --convert-to;\
    pdf;\
    ${file}
externalFileConverter.timeout=60000
externalFileConverter.outputFile=${fileprefix}.pdf

Example 2: Job configuration with everything configured in the job configuration

<Job>
    ...
    <FileModifier type="java">
        <CreatePDF>
            <Command>/opt/LibreOffice/program/soffice</Command>
            <Command>--headless</Command>
            <Command>--convert-to</Command>
            <Command>pdf</Command>
            <Command>${file}</Command>

            <Extensions>doc;docx;ppt;pptx;xls;xslx</Extensions>
            <Timeout>60000</Timeout>
            <OutputFile>${fileprefix}.pdf</OutputFile>

            <Checkin fileName="${filename}.pdf"/>
        </CreatePDF>
    </FileModifier>
</Job>

LibreOffice is a free and open source office suite. More about LibreOffice here. Also, about file conversions in headless mode here.

Above example is based on LibreOffice version 6.0.3.2 (x64).

Create PDF - Using Adlib

If you have the Adlib™ PDF converter available, an option is to use the Adlib™ folder connector for PDF conversion. To use this, you need to set the attribute implementation="adlibPDFConverter" on the <CreatePDF> element.

Below is an example how to configure this:

<Job>
    <Name>PDF Converter</Name>
    <FileModifier type="java">
        <FileFilter
            includeFormats="generic"
            includeFileNames="*.docx"
            excludeFileNames="*.pdf"/>
        <CreatePDF implementation="adlibPDFConverter"> (1)
            <Input destinationId="adlib-in-folder" /> (2)
            <Output destinationId="adlib-out-folder" />
            <Error destinationId="adlib-err-folder" />
            <PollTimeout>5000</PollTimeout>
            <MaxTimeout>600000</MaxTimeout>
        </CreatePDF>
    </FileModifier>
</Job>
1 You can either use the element <AdlibPDFConverter> or saying <CreatePDF implementation="adlibPDFConverter">. The result is equal.
2 The Input, Output and Error element accepts either a destinationId attribute OR a path attribute. The destinationId refers to a File destination with the given id inside the destinations.xml file.

The poll timeout and max timeout are default set to 5 seconds and 10 minutes. Override if necessary. Note that the times are defined in milliseconds.

PDF Watermark

The PDF Watermarking implementation used when the Java file modifier is chosen, is using the iText/Lowagie library that is part of the TVC-Core library to conduct the watermarking.

Absolution positioning of watermark

By default, start and end positions of watermark are configured relatively as percentages. lowagiePdfWatermark additionally supports absolute positioning of watermark.

To enable it, set the attribute position to absolute on the elements <StartX>, <StartY>, <EndX>, <EndY>, <ImageStartX> and/or <ImageStartY>. Use a decimal value to define position. Default value for position is relative, if not set.

lowagiePdfWatermark assumes the position (0,0) is bottom left corner of PDF page.

Multiple watermarks

This implementation can stamp multiple watermarks (in opposite to the Windows file modifier implementation). To enable it, set the boolean attribute allowMultiple to true on the <PDFWatermark> element.

When allowMultiple is set to true, all watermarks are stamped of which <Definition> is evaluated to TRUE.

For example:

<Job>
    ...
    <FileModifier type="java">
            ...
        <PDFWatermark allowMultiple="true">
            ...
            <Definition>
                ...
                <!-- Absolute position -->
                <StartX position="absolute">10.0</StartX>
                ...
                <!-- Relative position -->
                <StartY>20.0</StartY>
            </Definition>
            ...
            <Definition>
                ...
            </Definition>
        </PDFWatermark>
    </FileModifier>
    ...
</Job>

Custom Implementations

The elements <UpdateProperties>, <CreatePDF> and <PDFWatermark> all supports overriding its default functionality by setting a className attribute pointing to a class that extends from com.technia.tif.enovia.job.executors.file.FileAction.

For example:

<Job>
    ...
    <FileModifier type="java">
        <UpdateProperties className="com.acme.tif.CustomUpdateProperties">
        </UpdateProperties>

        <CreatePDF className="com.acme.tif.CustomCreatePDF">
        </CreatePDF>

        <PDFWatermark className="com.acme.tif.CustomPDFWatermark">
        </PDFWatermark>
    </FileModifier>
    ...
</Job>

The base class have one method that is required to be implemented:

import com.technia.tif.enovia.job.executors.file.FileActionContext;
import com.technia.tif.enovia.job.executors.file.FileActionResult;

protected FileActionResult process(FileActionContext ctx) throws Exception;

The FileActions part of TIF is available in source code format. See below:

Report Generation

If you have the TVC Report Generator or the ENOVIA/3DEXPERIENCE RPT component available, you may let TIF perform the creation of the reports.

This will replace the need to using som called Report Daemon/Agents and let TIF also handle this.

To setup a Report Daemon inside TIF you configure this within ${TIF_ROOT}/modules/enovia/etc/module.custom.properties.amp

The syntax is shown below.

reportGeneratorQueue.<ID>.enabled = true
reportGeneratorQueue.<ID>.queue = Test Queue
reportGeneratorQueue.<ID>.threadCount = 1
reportGeneratorQueue.<ID>.sleepInterval = 15000

For each queue you need to setup one block like above, each block must have its own unique <ID>.

In the Report Generator you may also configure a Queue to keep it’s job and additionally define a time period for how long the Jobs will be kept after completion. In such case, you can easily setup a cleaning routine with TIF to remove those jobs that are out-of-date.

This is examplified below.

${TIF_ROOT}/modules/enovia/etc/timetable.xml
<timetable>
    <group id="maintenance">
        <report-job-cleanser> (1)
            <schedule>
                <hour>2</hour>
                <minute>0</minute>
                <second>0</second>
            </schedule>
        </report-job-cleanser>
    </group>
</timetable>
1 Special tag that is used to enable the report job cleanser routine