File Manager - Administration Guide : Structure Browser Integration

21 March 2016

1. Integrating with TVC Structure Browser

The TVC File Manager is normally invoked through links within the tables related to documents and/or files in the standard (Value Chain Portfolio) applications. However, if you do have the TVC Structure Browser component you can in a structure browser instance show the documents and / or files.

By doing so, you would get an improved user interface – with reduced number of mouse clicks to browse for documents and/or its files. The screen shots below illustrate how this could be used to for example work with Parts specifications, or referenced documents.

One can simply add a command to the category tree to a type, which will bring up related documents in the TVC Structure Browser. From there, you will have the same/similar kind of information as you would have when using the OOTB functionality, but you will have an enhanced user interface to work with. For example, showing the versions of a particular document object just requires you to click the "go-there" (the blue arrow on the left side on each row) and the versions are then shown (Figure 8). You can then simply go back, by clicking the go-back arrow (the blue arrow to the left of the table-selector) (Figure 9).

image
Figure 1. Showing the Specifications in the Structure Browser instance

If a document object would have several files checked in, you will first see the active version objects for each file checked in. By simply clicking the go-there again for a particular file, you will then see all the versions of that file.

image
Figure 2. Show the active versions of a selected document object
image
Figure 3. Show all versions of a file

The list of settings used for reducing the number of visible actions (from this page), are also supported in these views.

The page configuration objects / view objects / tables and others are all defined in XML files. You will find these XML files under the folder -INF/tvc/office within your application directory. As these files might be overridden when installing new releases of TVC, you should not do modifications within these files. Instead, copy them to a different folder and create new commands that are referring to your updated files.

Instructions how to work / define configuration objects in XML are described in a separate document, which is distributed among TVC (XMLBasedDefinitions.pdf).

The URL that you can use to load a TVC table with documents is

${ROOT_DIR}/tvc-action/getRelatedDocuments

This URL accepts a number of request parameters, described in the table below:

Parameter Required Description Example

objectId

Yes

Either one of these parameters must be present in order to resolve the id of the object, which the related documents should be retrieved for

emxTableRowId

relationship

Yes

The relationship to expand along to get the related documents

relationship=relationship_PartSpecification

direction

No

The direction to expand. Default is from.

direction=from

type

No

The type of documents to include. Default is any object.

type=type_CADDrawing

type=type_CADModel

objectWhere

No

The where expression to apply on objects when retrieving the related documents

objectWhere=current==Release

relationshipWhere

No

The where expression to apply on relationships when retrieving the related documents

relationshipWhere=attribute[ABC] == Z

1.1. Drop Zone

In TVC 2010.3.0 the drop zone feature were introduced, which allows the user to drag files from his/her local file system into the webpage in order to check-in the file to an existing document object, or in some places create a new document into which the file will be checked in.

This feature used to work on OS X but has now stopped working due to the change of the Java Plug-in that OS X uses to render Java Applets in the browser. Unfortunately this new Plug-in does not support "Drag & Drop" operations onto a Java applet running embedded in the browser.*

+ We have as a result of this in the TVC 2014.2.0 release implemented a HTML5 based drop-zone to provide Mac users with the drop zone capabilities. _This implementation do have some limitations, please see this chapter for further details.

1.1.1. Above Table

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.

image
Figure 4. Drop zone above table

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:

<Command>
    <URL action="getRelatedDocuments">
        <Param name="pageConfig" value="NAME OF PAGE CONFIG"/>
    </URL>
    <Label>Label...</Label>
    <TargetLocation>content</TargetLocation>
</Command>

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

${ROOT_DIR}/tvc-action/getRelatedDocuments?pageConfig=NAME OF PAGE CONFIG
Parameters to Control Drop Zone above Table

The table below shows and explains what parameters that you can use:

Parameter Value Notes / Description

dropzone:enabled

True

False

Defines if the drop zone should be available or not

dropzone:handler

A Java class name

Can be used if you want to customize the behaviour of the drop zone. In this case, the provided class must extend from:

"com.technia.tvc.office.ui.dropzone.table.DropZoneHandler"

dropzone:type

The type of object that will be created.

Can be a symbolic name or real name

dropzone:revision

The revision of the object.

Optional. Default is to use the first revision in the sequence defined within the policy.

dropzone:numbergenerator

The name of the number generator to be used.

Optional. Can be a TVC Number Generator or an AEF object generator. If undefined, the most suitable number generator will be used. Note that you need a number generator (either a TVC number generator or an AEF object generator) available in the database, otherwise you will get an error.

dropzone:policy

The name of the policy to be used for the object that will be created.

Can be a symbolic name or real name

dropzone:relationship

The relationship to be used

Can be a symbolic name or real name

NOTE: If this value is omitted, the "relationship" parameter is used.

dropzone:direction

From

To

Defines the direction. E.g connecting from the context object to the document or or vice versa.

NOTE: If this value is ommited, the "direction" parameter is used.

dropzone:label

A label

The label will appear in the drop zone area.

dropzone:format

The format to be used

Can be a symbolic name or real name

Note: If this value is omitted, the "generic" format is assumed.

dropzone:oneobjectperfile

True

False

Whether or not to create one document object per file that is dropped. E.g. if the user drops three files, if this setting is set to true, three document objects will be created.

Default is false.

dropzone:selectformat

True

False

Allows the user to specify what format the dropped files should be checked-in to.

dropzone:refresh

None,insert,refresh

The refresh behaviour. Default is insert.

dropzone:filechooser

True

False

Enables/Disables left mouse click on drop zone to show a file chooser.

Default is true.

dropzone:usenativefilechooser

True

False

If needed, this setting will enable a file chooser that is closer to the native file chooser in the operating system the user is running. For example, this will make it possible to see thumbnails and previews of image files.

Default is false.

NOTE: When this is enabled, it is only possible to select one file at a time.

The values are set either within the "TVC Custom Parameters" attribute of the Page Configuration business object using key/value pairs or as the example below if you are using XML definitions:

<PageConfig>
    ...
    <Parameters>
        <Parameter name="dropzone:enabled" value="true"/>
        <Parameter name="dropzone:type" value="type_MyDocument"/>
        ...
    </Parameters>
</PageConfig>
If you use a custom drop zone handler through the "dropzone:handler" value, the other parameters will not be used.

1.1.2. Table Column

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:

image
Figure 5. Drop zone in table column

Or in a table page showing folders and documents:

image
Figure 6. Drop zone in table column for folders

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.

image
Figure 7. Drop zone when files are dragged over the cell
Drop Zone Column Settings
As of TVC 2011.3.0 we made a number of enhancements to the drop zone, for example allowing the user to drop files on any kind of object. This required us to change how the configuration of the drop zone was done. The old settings are still working and will work together with the new configuration format.

The drop zone column settings are applied as the example below illustrates:

Setting Name: dropzone:<type-of-object-drop-is-valid-for>
Setting Value: <param>=<value>,(<param>=<value)*
It is possible to provide a list of object, which the drop-zone is valid for in case you will create and connect the created document in the same way for many different types. In such case, provide the types separated with a comma character.

It is also possible to define a custom "DropZoneHandler". Please look into this chapter for details.

Example for "Parts" (not complete):

Setting Name: dropzone:type_Part
Setting Value: type=type_Document,relationship=relationship_PartSpecification,...

The parameters supported are shown in the table below:

Parameter Type Required Notes / Description

relationship

String

Yes

The relationship to use when connecting the document

direction

enum (from,to)

No

The direction to connect the document

type

String

Yes

The type of document to be created

policy

String

No, but recommended to set.

The policy to be used. If none is specified, we will try to figure out a proper one to be used

vault

String

No

The vault to create the object inside. If unspecified, the same vault as the object we connect the document to will be used

numbergenerator

String

No

The name of the number generator to be used. Use prefix AEF: to force using an AEF generator; use prefix TVC: to force using a TVC number generator. If not specified, we will try to find a suitable number generator depending on type of object being created

format

String

No

The file format to be used

maxfilecount

Integer

No

Specifies the max nr of files allowed to be dropped

oneobjectperfile

Boolean

No

Whether or not to create one object for each file dropped, or put all in one.

refresh

enum (insert,refresh,none)

No

Specifies the refresh behaviour

selectformat

Boolean

No

Can be used to force loading the built-in format selector

There are some other settings that you can add on the column. These are described below:

To control the drop zone on tables that shows Document objects, you have some additional settings to configure the drop-zone on such row.

Setting Name Value Notes / Description

Allow Drop On Document

True

False

Whether or not to allow drop files on documents.

Default is true.

Max File Count

Integer value

Defines the max number of files that can be dropped on a document.

Default is -1 (unlimited)

Allow Update Existing

True

False

Defines if the user is allowed to update existing documents by dropping them in the drop zone.

This feature is new as of 2011.3.0. In earlier versions, the user could only create new documents through the drop-zone.

Show Header

True

False

Defines if the header should be shown or not. Default is true and the value will be the text specified in the label of the column.

To customize the behaviour of the drop zone in case you are displaying a Folder structure (in a Project), you have some additional settings as shown in the table below:

Setting Name Value Notes / Description

Allow Drop On Folder

True

False

Whether or not to allow drop files on folders.

Default is true.

Create One Document Per Folder

True

False

Defines if each file will be checked into a separate document object. E.g. if the user drops 3 files, either 3 documents are created or one document is created but will contain the 3 files being dropped

Default is true.

Document Type In Folder

String

The type to be used. Can be a symbolic name or real name

Document Policy In Folder

String

The policy to be used. Can be a symbolic name or real name

Document Rev In Folder

String

The revision of the object to create (optional). Default is to use the first revision in the sequence defined within the policy.

Document Number Generator In Folder
Example of a Column

Below is an example of a column with drop zone defined. The settings define that you can drop documents on Parts. The files will be checked in to new Document object of type "Document". We have also disabled the drop zone for "Document" and "Folder" objects.

<Column>
    <Name>dropzone</Name>
    <ColumnType>dropzone</ColumnType>
    <Setting name="dropzone:type_Part">
        relationship=relationship_PartSpecification,
        direction=from,
        type=type_Document,
        policy=policy_Document,
        vault=vault_eServiceProduction,
        numbergenerator=TVC:A-Size,
        format=generic,
        maxfilecount=4,
        oneobjectperfile=true,
        refresh=insert,
        selectformat=true
    </Setting>
    <Setting name="Allow Drop On Document" value="false"/>
    <Setting name="Allow Drop On Folder" value="false"/>
</Column>
Custom Drop Zone Handler

To override the behaviour of the drop zone; for example you might want to have full control of the creation of the Business Object(s) (maybe creating additional objects etc.), you need to implement a so called Drop Zone Handler.

To define such drop zone handler, you can do this as the example below illustrates:

<Column>
    <Name>dropzone</Name>
    <ColumnType>dropzone</ColumnType>
    <Setting name="dropzone:type_Part" value="java:com.acme.MyDropZoneHandler"/>
</Column>

The class you specify here must derive from the class:

com.technia.tvc.office.ui.dropzone.table.DropZoneHandler

Please refer to the developer documentation for further details around the implementation of a "Drop Zone Handler".

1.1.3. Image Drop Zone

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:

<Column>
    <Name>imagesdropzone</Name>
    <ColumnType>imagedropzone</ColumnType>
    <Alt>Image Drop</Alt>
</Column>

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

<Column>
    <Name>primaryimage</Name>
    <ColumnType>primaryimage</ColumnType>
    <Format>default</Format>
</Column>

1.1.4. HTML5 based Drop Zone – Mac Users

As mentioned above, the applet based drop zone does not work for Mac users due to technical reasons beyond the control of us. Due to this reason, we have implemented a Drop Zone for Mac users based upon Java Script and HTML5 technologies.

Since there are some limitations with this implementation, this feature is disabled default.

To enable this, you must first of all apply an init-parameter to TVC like below:

<init-param>
    <param-name>tvc.office.dropzone.js.enabled</param-name>
    <param-value>true</param-value>
</init-param>

Note that this will only enable HTML5/JS based drop-zone for users on the Mac platforms.

FCS Support

By default, support for FCS servers are disabled since they are causing cross domain requests, which is denied by modern web-browsers. There are possibilities to enable this via usage of the so called CORS (Cross Origin Resource Sharing) mechanism. This 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 to the FCS servers. This is done via an init-parameter like below:

<init-param>
    <param-name>tvc.office.dropzone.js.cors.enabled</param-name>
    <param-value>**true**</param-value>
</init-param>
Limitations

Below is a list of features that are not supported on HTML5 based drop zones.

  • Drop Zone Handlers utilizing pre-process page. Such configurations will generate an error message to the user.

  • File Managers requiring user input will be prompted so, but the appearance of the input dialog is a plain browser prompt dialog.

  • The setting "oneobjectperfile" is not supported.

  • Large files on Mac sometimes causes read-timeout on the server-side.

1.2. Command for Viewing Part Specifications

When TVC File Manager was installed, a command called TVCSpecifications was installed. By simply adding this command to the type_Part menu, you will be able to view the specifications for a Part inside the TVC Structure Browser application.

You have to disable (or rename) the label of the corresponding OOTB command since the AEF does not allow having multiple commands with same label inside the category tree.

1.3. Command for Viewing Reference Documents

When TVC File Manager was installed, a command called TVCReferenceDocuments was installed. By simply adding this command to the type_Part menu, you will be able to view the reference documents for a Part inside the TVC Structure Browser application.

You have to disable (or rename) the label of the corresponding OOTB command since the AEF does not allow having multiple commands with same label inside the category tree.

1.4. Command for Viewing other Documents

If you need to view other Document for other kind of types, please have a look at the commands mentioned earlier how to do so.

As of 6.1, a new data handler and cell renderer were added in the File Manager component allowing showing whether or not a business object has related document(s). The data handler can be configured 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.

image

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:

Setting Value Required

Column Type

File

Yes

Direction

From

No

Relationship

A comma separated list of relationship names (or symbolic names)

No

1.5.1. List page configuration

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.

tvc.properties

tvc.office.attachment.listconfig=/com/acme/ListConfig.xml

init-param
<init-param>
    <param-name>tvc.office.attachment.listconfig</param-name>
    <param-value>/com/acme/ListConfig.xml</param-value>
</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.

tvc.properties

tvc.structurebrowser.list.pagination.size=40

init-param
<init-param>
    <param-name>tvc.structurebrowser.list.pagination.size</param-name>
    <param-value>40</param-value>
</init-param>

Example configuration

<ListConfig>
    <SortOrder>
        <Value ascending="false"><![CDATA[$<modifed>]]></Value>
        <Value ascending="true"><![CDATA[$<name>]]></Value>
    </SortOrder>
    <Item>
        <Row style="bold underline"><![CDATA[$<modified>]]></Row>
        <Row style="bold"><![CDATA[$<type>, $<name>, $<revision> ($<current>)]]></Row>
    </Item>
    <PaginationSize>40</PaginationSize>
</ListConfig>
Configure the File Actions

The actions shown on each file, such as view, download, checkout, lock, unlock, tree and details are all actions that is shown depending on if the user has access to perform the actual action or not.

If you want to limit the amount of actions, for example, you only want to allow the user to be able to view or download the document; then you can on the HREF define the maximum set of visible actions.

Example:

${ROOT_DIR}/tvc-action/showAttachments?visible=view|download

The possible values for the visible parameter are:

  • download

  • view

  • checkout

  • checkin

  • lock

  • unlock

  • delete

  • details

  • tree

The values within the visible parameter should be a pipe ("|") separated list. If this parameter is omitted, then all actions are assumed to be possible.

Again, the visible parameter can never give a user more access than s/he actually has. If the user does not have lock access, the user is not able to perform a checkout even though this parameter is among the visible parameter.

1.6. Custom Table Showing Document Actions

If you want to create a complete custom table, with your own set of columns but also include the document actions column. You can create a column with following characteristics:

Setting Value

Column Type

actions

The list of settings used for reducing the number of visible actions as seen in chapter this chapter, are also supported in tables that uses this data handler.