File Manager - Administration Guide

The first task is needed in order to include some functionality within the "emxNavigator.jsp" and "emxNavigatorDialog.jsp" pages, which are located within the common folder in your ENOVIA™ application directory.

These changes are needed in order to integrate the TVC File Manager with the ENOVIA™ applications.

Just after the "body" element tag in each of the files, add the corresponding include directive.

/common/emxNavigator.jsp

/common/emxNavigatorDialog.jsp

This step is not valid for Info Central based applications.

The second task will replace the functionality in two JPO’s that generates the action links for a document (i.e. the links that are generated to download, view, checkout, check-in, lock, unlock or update a file).

The names of the programs to replace are:

While the TVC Office component was installed, two programs were added to the database. The two programs mentioned above must be replaced with these new programs. The MQL code below illustrates how to do so. Simply launch the commands from a MQL prompt (ensure that correct user and password is used).

Due to issues of ENOVIA, you need to modify web.xml after installing TVC and add a by-pass filter as shown below:

This is needed for Applet based clients, which needs to be able to download the JAR files.

The actions shown in the table are all visible depending on the actual access rights the current user has to the document object. However, in some situations, you might want to reduce the amount of available actions; for example just providing a view and/or download link. This might be the case if you want to show the document actions within a search result page for example.

There are a couple of Settings that could be applied to the actions column, in order to reduce the visible actions.

The following table lists those settings:

All of these settings accept a Boolean value. The default value for all of them is true.

The column showing the file actions can be configured.

For example, you can define if the name of the file should appear only when there are multiple files attached or if they always should be present. The position of the filename could be displayed either on the left or right side of the actions. Moreover, the file name could be truncated to only show a certain amount of characters.

All of these options can be configured via system parameters, which affects all tables showing the actions column. The table below shows these parameters

The system parameters mentioned above, are typically defined in the "web.xml" file, and will affect all tables showing the file actions column.

However, to apply a different behavior to a certain table; you are able to define that by using settings on the column in that table. The following table shows the settings that can be used to apply table specific behavior.

To display the actions column in tvc table, you can use this column definition:

To display the actions field in tvc TopPanel, you can use this field definition:

The TVC File Manager client allows the user to configure its own preferred behavior. As a user you can select a folder wherein all files should be saved automatically when downloaded. You can also define what should happen if that folder contains a file with the same name as the file being downloaded.

It is also possible to select whether downloaded files should be deleted (moved to the recycle bin) when the entry is removed from the user interface and whether the client should check for new versions of downloaded files. Note that if you want the client to check for new versions it will do so every time you login to the application and every 10 minutes while you’re logged in. Also, the file manager can only check for new versions of downloaded files that follow to the Common Document Model.

Another option that you have as a user is to select whether the integration window should appear when you login to the system. The file manager can be configured to always open the window, only open it if you have active files (e.g. files currently being edited), or to never open it.

The files that are downloaded for view could be placed in a separate temp folder to avoid file name collisions that could occur when comparing document versions.

Support for downloading/uploading files from/to the FCS servers are by default disabled, since those operations violates the same-origin-policy and hence are denied by modern web-browsers.

It is possible to enable FCS support but that requires implementing so called CORS (Cross Origin Resource Sharing). That can be done by adding a servlet filter enabling CORS support to ALL FCS instances. Information on how to enable this can be found in the TVC Installation Guide under the chapter "FCS Support"

You also need to inform the File Manager that you have enabled CORS support on the FCS servers. This is done via an init-parameter like below:

A drop zone can be added above a table that typically displays a set of documents related to an object. When dropping files into this area, a new document object will be created and connected to the related object and the file (or files) will be checked in to the newly created object.

Below is a screenshot illustrating the drop zone above a table page.

By default, the drop zone can also be clicked to show a file browser dialog, allowing the user to select files in a standard way. This can be disabled with a setting. See parameters below for details.

The drop zone above a table is configured via the page configuration that you use on the page.

Note that you must launch the Structure Browser instance using the following URL in order to get the Drop Zone available:

If your command is defined in the database, the HREF is:

There is a new column type available called "dropzone" that can be used to allow the user to drop files into existing documents or onto another object in a Structure Browser table. In the latter case, the dropped file(s) will be checked-in to new document objects that are created and connected to the object, which the file was dropped on.

To enable the drop zone in a table page, add a column into the table and set the setting "Column Type" to "dropzone". There are a number of settings available that you can use to customize the behaviour of the drop zone column, these are mentioned later in this chapter.

When the drop zone column is enabled in the table, it will look like the example screenshot below:

Or in a table page showing folders and documents:

When the user drags files over this column, the appearance of the cell will change to display an icon indicating that the user can drop the files therein. See next screenshot.

A special variant of the drop zone is available that allows dropping image files and create so called "Image Holder" objects, which the file is checked in to.

To use the image drop zone, you can configure your table as the example below:

To display the primary image in a table, you can use this column definition:

As of 6.1, a new data handler and cell renderer are added in the File Manager component to show whether or not a business object has related document(s). The data handler can be configured to define what relationships it should use when looking for related documents. If there are documents related to the object, an icon will display that and the user can click the icon to get the list of files in the side panel. See screen shot below.

The list will show all related documents and the files related to each document.

For the documents, the user will be able to check-in new files if she/he has access to do so, see basic properties of the document or open the document object in a popup window.

Also, per file, the user will be able to download, view, checkout, unlock, lock or update the file (again, depending on access rights, all actions might not be available).

Unless you provide any settings at all to this data handler, it will default look for "Reference Documents" and "Part Specifications" connected from the object in the table. You can change the behaviour by changing the following settings:

The File column type is useful to display the related document(s) and their files in the side panel. However, the File column type will only display the related document(s) connected via the given/default relationships.

There might be cases when the table row object can have the document(s) connected via path (A virtual relationship). The File column type is not capable of fetching the document(s) connected via the path.

A new built-in column type PathAttachment has been added which is capable of showing the related document(s) connected via the given/default relationship(s) and also the related document(s) connected via the path.

A new data handler and cell renderer are added in the File Manager component to show whether or not a business object has related document(s). The data handler can be configured to define what relationship(s) and path type it should use when looking for a related document(s). If there are document(s) related to the object, a paper clip icon will be displayed and the user can click the icon to get the list of files in the side panel. See screenshot below.

The list will show all related document(s) and the files related to each document.

For the document(s), the user will be able to check-in new files if user has access to do so, see basic properties of the document or open the document object in a popup window.

Also, per file, the user will be able to download, view, checkout, unlock, lock or update the file (again, depending on access rights, all actions might not be available).

Unless you provide any settings at all to this data handler, it will default look for "Reference Documents" and "Part Specifications" connected from the object in the table. You can change the behaviour by changing the following settings:

The example below illustrates how user/admin can construct the column of PathAttachment column type:

The list page content and sorting can be configured by pointing out a custom list page configuration xml resource file.

To do that you first have to point out the file (reachable by the classloader) using a tvc property or an init-param.

Pagination size of list page can be configured from tvc property or init-param or custom list page configuration xml resource file. If pagination size is not defined in page configuration xml file, its value is set from init-param. If init-param is also not defined for list page pagination size, default value will be 20.

Example configuration

Init parameters are defined within the deployment descriptor ("web.xml" file) for your application. In that file, you should have a section for the TVC Servlet (if not, please advice the Installation Guide for TVC).

Within that section, init-parameters are added as the example below:

The following table shows the mapping between the configuration item and the parameter name,

Additional parameters related to the client settings are described later

Either if the File Manager is configured via a file found in the classpath or through a page object, the format of such is the same. The example below illustrates the format of such file.

When the TVC File Manager has been disabled for a user, the user will not work with the files through the File Manager client. However, the JPO’s that are generating the "file-actions" in the user interface will still call the TVC logic for creating the images/actions.

It is however possible to instruct the TVC File Manager to skip generating those actions, and let the default JPO’s do it. To configure this behavior, either modify the init-parameter as below (default is FALSE) or configure that through the XML configuration object.

Or

The triggers are registered within the XML file mentioned in this chapter. If the configuration of the TVC File Manager were made through the init-parameters, you will need to create an XML file containing the trigger part only. How the trigger section is defined, is illustrated below.

Each trigger defined, has its own Trigger element inside the Triggers element. On the Trigger element, you must define the className attribute, and the value must contain the fully qualified name of a Java Class that extends from the abstract class "com.technia.tvc.office.server.trigger.Trigger". This chapter describes how such a Trigger class could be implemented.

Moreover, the Trigger element allows nested elements that can be used to mask when this trigger will be used. Se example below:

The examples shown above, illustrates the capabilities of how the Matches element could be used. These examples might not be realistic, but they show how they could be used.

As seen, the Matches element can be nested in arbitrary levels. Each level is satisfied, if at least one Matches element evaluates to true.

As mentioned earlier, a custom trigger must derive from the abstract class "com.technia.tvc.office.server.trigger.Trigger". The code below shows the methods that could be implemented.

Those methods that can abort a transaction, has in its signature defined that the TriggerAbort exception could be thrown.

Each of the interfaces provided as argument to the trigger methods (ending with *Input), is derived from the interface TriggerInput. The chapters below, shows the available methods on all classes and interfaces used around the trigger execution.

All classes and its related methods involved in the execution of a Trigger are listed below. Note: In some cases, each class/interface might have more methods than shown in the table below. Do not use any other method than those mentioned below.

In addition to registering an ordinary Java class as trigger, one can instead configure the TVC File Manager to use a JPO that generates the properties that should be propagated to the document.

This is configured as below:

You have to specify the "program" attribute and "get-method" attribute to match your JPO program / method. The "get-method" property represents the method within your JPO that returns the properties.

The method being executed must return a java.util.Map containing string keys representing the names of the property being transferred. The value can be of any type in the following list:

When the JPO argument is unpacked, you will get a java.util.Map, containing information about the document / file being handled. This map contains following:

By default, the built-in triggers will only provide properties if the document that is being downloaded is a so called OLE-2 document (actually, only Microsoft Office files are treated as OLE-2 documents).

As of TVC 2011.3.0, a new feature is added that make it possible to write properties for other files than OLE2 documents.

This behavior is enabled by defining a trigger that is run on other files than "doc, docx, xls, xlsx, etc."

The difference in that case is how the properties are managed. In OLE2 documents, the properties are part of the actual file itself, while in other cases the properties are stored in a separate file in the same folder as the file is being checked-out into.

The properties file will have the same name as the file being checked out + an additional suffix consisting of ".tvcprops.xml". For example, if the user is checking out a file called "Test Document.pdf" and his download folder is set to "c:\ENOVIA Files", then an additional file called "Test Document.pdf.tvcprops.xml" is created within the "c:\ENOVIA Files" folder (in case when the server has been configured to propagate properties to .PDF files).

The format of the properties file is XML, and follows this syntax:

The type attribute is an integer, whose values can be:

This can also be disabled by specifying either an "init-parameter" or through the TVCFileManager.xml file:

Or

The built-in triggers are used for the purposes listed below:

There are some additional "init-parameters" that can be used to configure the behaviour of the built-in triggers.

Property write is by default enabled (if there is a trigger that defines so).

Property read is by default disabled (this can be used to transfer properties back to the server when checking in a document).

Configure this through an init parameter:

Configure this via the "TVCFileManager.xml" configuration file:

The interval (in seconds) with which the client will send keep-alive requests. Default is 600s (10 minutes).

Configure this through an init parameter:

Configure this via the "TVCFileManager.xml" configuration file:

Defines if the client periodically should check for new versions of files that the user has downloaded. Default is true.

Configure this through an init parameter:

Configure this via the "TVCFileManager.xml" configuration file:

Defines if the client should save properties using Word automation (for Microsoft Word files). Default is true.

Using Word to save the properties can in some cases take some time, especially if the document is large. Disabling this will result in that the property values needs to be updated manually in Word (Typically using F9), but will result in a faster time to open the document.

Configure this through an init parameter:

Configure this via the "TVCFileManager.xml" configuration file:

Disable running executables. E.g. defines if to open an executable file downloaded from ENOVIA automatically. Default is true.

Configure this through an init parameter:

Configure this via the "TVCFileManager.xml" configuration file:

Define the default download folder for the clients.

Configure this via the "TVCFileManager.xml" configuration file:

If the path value starts with "~/", this will be expanded to the user’s home directory. The user’s home directory is obtained from the Java system property called "user.home".

If the path doesn’t start with "~/", it can contain macros that are replaced with their corresponding environment variable from the client. For example:

The above example will replace the macro ${TEMP} with the environment variable named "TEMP". Note that you should use forward slashes to separate directory names.

Enable temp directory when viewing files as default

Configured through init parameter:

Configure through "TVCFileManager.xml":

You can configure File Manager to delete local files when removing the entry from the File Manager entry list.

Configured through init parameter:

Configure through "TVCFileManager.xml":

You can configure File Manager to remove entries from the list after successfully completing an upload.

Configured through init parameter:

Configure through "TVCFileManager.xml":

You can configure the File Manager window to be hidden after completing a file transfer.

Configured through init parameter:

Configure through "TVCFileManager.xml":

You can control the default behaviour of the File Manager window on start up (login).

Possible values

Configured through init parameter:

Configure through "TVCFileManager.xml":

You can control the default behaviour when there is a filename conflict when downloading a file.

Possible values

Configured through init parameter:

Configure through "TVCFileManager.xml":

When the user has downloaded a document for edit, there are some situations when the user manually uses the "update" function to upload the edited file manually (e.g. not using the "check-in" feature in the file manager client).

This means that even if the file has been uploaded and a new version has been created, the user can still upload the file that originally was opened for edit, once again from the File Manager client.

In order to prevent this to happen, a mechanism has been added that verifies that there isn’t a new version created, which is validated upon check-in. When the user clicks "check-in", and a newer version exists, the following dialog will appear if a newer version exists, which allows the user to decide what to do.

Configure this through an init parameter:

Configure this via the "TVCFileManager.xml" configuration file:

When the user tries to upload a file with a different name, using the upload button in the web-ui, a warning message appears (default behaviour) in order to confirm the file rename, see screenshot below.

This behaviour can be configured. E.g. it is possible to disable the possibility to rename a file, enable it without the warning message or enable it but show the warning message. The latter is the default. To configure this, use one of the two options below:

Configure this through an init parameter:

Configure this via the "TVCFileManager.xml" configuration file:

By default, the user can select multiple files when checking in new files into a document object. This can however be changed.

Configure this through an init parameter:

Configure via the "TVCFileManager.xml" configuration file:

You can prevent files containing bad characters from being uploaded to the server. It will first check the Enovia OOTB setting in emxSystem.properties:

If the above property is not set it will use the TVC init parameter:

Or configured via the "TVCFileManager.xml" configuration file:

The file manager client invokes http requests to the server. By default the JSESSION id automatically added to the request cookie. In some cases, for example when using SSO, it is useful to include the complete cookie value. This is done by using the option "all".

If the above property is not set it will use the TVC init parameter:

Or configured via the "TVCFileManager.xml" configuration file:

It is possible to enable debugging from the File Manager client. This information can be useful for troubleshooting purposes.

The debugging is enabled by:

Configure this through an init parameter:

Configure this via the "TVCFileManager.xml" configuration file:

For improving readability in TVC File Manager client extension, section headers can be made bold by using below init parameter.

Configure through an init parameter:

Configure via the "TVCFileManager.xml" configuration file:

It is possible to change the font size of the text on the preferences dialog of TVC File Manager client.

Configure through an init parameter:

Configure via the "TVCFileManager.xml" configuration file:

Below is an example configuration showing how to configure client settings.

Init parameters are defined within the deployment descriptor ("web.xml" file) for your application. In that file, you should have a section for the TVC Servlet (if not, please advice the Installation Guide for TVC).

Within that section, init-parameters are added as the example below:

This section describes how to create a Command to launch the File Package Download function from a TVC Structure Browser page or a business object’s details page.

Commands can be created and modified with the Business Administrator and MQL thick clients; however, it is recommended that you use the Business Administrator if you are not familiar with MQL (Matrix Query Language).

The most important parameter when creating a Command to launch the File Package Download is the "Href" parameter, whose value must be the following URL.

The reason for this is that when the toolbar is displayed in the Value Chain Portfolio application it fails to append the objectId parameter to the URL unless it ends with .jsp. This is not necessary if the command is to be added to the toolbar that is displayed on a TVC Structure Browser page.

The following table describes the settings and values that should be set on a Command that is used to launch the File Package Functionality.

In addition the following settings can be used when adding the command to the toolbar of a TVC Structure Browser page. Adding these settings will force the user to select a row in the table that will be the root business object when creating the File Package.

Normally, when launching the command specified above, a dialog will appear with the possible configurations to be used (if any) where the user needs to select one of the configurations to be used in the particular use-case.

However, if desired, the file package functionality can be started directly with a defined configuration. You will need to add a parameter called configuration to the HREF, whose value is the id of a configuration (see the following chapters how to define a configuration and associate id’s to them).

It is possible to grant access for a specific user by adding the user name to a list of user names. All users added to this list will have access to the configuration, no matter if they are or aren’t assigned to any roles or groups defined in the role list and group list respectively (See Role Based Access Control and Group Based Access Control).

Users are granted access by enclosing their user name within a User element. The User element is then added to the UserList element, which is a child of the Access element:

When controlling access based on roles it is important to know that all users that are assigned to that role, and all its child roles, will have access to the configuration.

Grant access for all users assigned to a specific role by enclosing the role name within a Role element. The Role element is then added to the RoleList element, which is a child of the Access element:

When controlling access to a configuration based on groups, it is important to know that all users that are assigned to that group, or its child groups, will have access to the configuration.

Grant access for all users assigned to a specific group by enclosing the group name within a Group element. The Group element is then added to the GroupList element, which is a child of the Access element:

Note that when combining different types of access control, all users that are either explicitly added to the UserList element, OR are assigned to any of the roles added to the RoleList element, OR are assigned to any of the groups added to the GroupList element, will have access

As mentioned before, the perform method does the work and defines the package content. The argument to the perform method, is an instance of a class named "HandlerCtx". The HandlerCtx class provides a large set of different functions that is used to add content to the package. See the specification below:

Many of the methods above returns either an instance of "PackageEntry", "TableExportEntry" or "PackageDependency", for each of these return values, you have some common functions that operate on the returned object:

Additionally, the "TableExportEntry" instance has the following methods:

Additionally, the "PackageDependency" instance has the following methods:

All the instructions support the following attributes:

Executes the command and the output from the command is stored in the specified file.

Additional attributes supported by this instruction:

When the parseMacros attribute is true, the MQL command can contain macros that are parsed. The following macros can be used:

Example:

This instruction can be used to include the content of an URL into the package.

The URL is assumed to be relative to the application context-root if it doesn’t start with http: or https:.

Executes a method in a JPO, and stores the output in the specified file. The JPO must return some value.

Additional attributes supported by this instruction:

It is also possible to provide additional arguments to the JPO, see the example below:

When the JPO is invoked, and the string array is unpacked using JPO.unpackArgs, you will get a Map with following key/values:

The File instruction is used to download a file that is checked in to a business object in Matrix.

The example below illustrates how to use this instruction.

Additional attributes supported by the File element are

The TableData instruction can be used to evaluate a table over a list of objects, and include the data, either in CSV (comma separated) or in XML format, in the package.

The list of objects can either be retrieved through evaluating an inquiry or by executing a JPO.

Below are some examples that illustrate how to use this instruction:

Also, it is possible to provide arguments to either the inquiry or to the JPO method:

The StructureData instruction is similar to the TableData instruction, but it can be used to extract a structure in either CSV or XML format.

The structure is expanded according to filters that are stored inside the workspace of a role.

Below is an example how to use this element:

The filters are created through MQL, and must be created for the role as specified. An example MQL command to create a filter from MQL is shown below: