Core - Administration Guide

The following is a list of the requirements for the installation of this TVC. If your system is different, consult Technia before installing. For best performance it is recommended to use the latest version of browsers and application servers.

Disclaimer: This feature uses a framework called Atmosphere for sending notifications from the server to the clients. This framework supports a wide range of browser and app servers. We will not be able to add support for browsers and/or app servers that is outside of this frameworks support. Also we might not be able to fix issues that could appear in the usage of this framework. See following pages for a list of this frameworks supported platforms and known issues:

Many environments are scaled horizontally to support a larger amount of users. When having > 1 application server you need to use a load balancer that can divide the users across these application servers somehow.

The Collaboration component uses the web socket technology for setting up persistent connections between clients and servers and this technology has a completely different analogy than the traditional request/response paradigm used in HTTP/HTTPS communication. This will have some impact on your infrastructure since your load-balancer must be able to deal with web sockets correctly.

Since users in fact are connected to different application servers, but still should be able to receive notifications from other users – there is a need for the application servers to be able to speak with each other.

There are currently two different implementations available that solves this, one of the implementation uses HTTP communication between the servers and the second implementation uses the Open Source library named Ehcache. The latter is the default communication strategy.

The choice of strategy is defined with a TVC init-parameter. The name of the parameter and the possible values are shown below:

Technia have during the development of the Collaboration component tested on a setup using an Apache HTTPD server acting as a load-balancer and behind having a couple of app servers running Apache Tomcat. All on a Windows 7 host.

The Apache HTTPD server has lately improved their support for web-socket tunneling, and we were using the version 2.4.10.VC11 (64 bit).

The Apache Tomcat versions were 7.0.56 (64 bit).

Below are the configurations we made. Note that we only provide these as examples and you should and might need to adjust them to your needs.

The first task is needed in order to include some functionality within the "emxNavigator.jsp" page (resides in the common folder in your application directory). The only change needed in this file, is to add a single line of code.

Just after the "body" element tag, add the line below (shown in bold):

The second task is needed in order to include some functionality within the "emxNavigatorDialog.jsp" page (resides in the common folder in your application directory). The only change needed in this file, is to add a single line of code.

Just after the "body" element tag, add the line below (shown in bold):

The third task needed is the registration of the Atmosphere servlet that is used for sending notifications from the server to the client (https://github.com/Atmosphere/atmosphere). The following lines should be added to web.xml

In order to use any of the features that requires Exalead you need to install Exalead and set it up for collaboration. To enable Exalead for Collaboration there is a TVC Init parameter that needs to be set.

or using the below short format (preffered).

In order for Exalead to know what data to index for Collaboration the following needs to be added to your Exalead index configuration file.

The panel that contains the discussion functionality is located in the right side of the application. It is injected on the side of the page content so It will stay visible even when navigating around the different pages of an object. The panel is collapsed by default and will be expanded on click.

After clicking on the panel it will be expanded towards the left side and show the discussions for the object that you are currently in context of.

If you disabled the discussion functionality for some object types by configuration the panel will be grayed out and the user will not be able to expand it.

When the user is standing in context of an object that has support enabled for discussions it will be possible to expand the discussion panel in order to view and/or create discussions. The default view of the panel will show a toolbar in the top and below that a list of all the discussions that has been started around the context object.

Each discussion in the list is clickable. The entire discussion will be loaded when a user clicks on it. See next chapter for more details on that.

When a discussion in the list has been clicked it will load the entire discussion in the panel. In this view the user will be able to see all the messages in the discussion and also have the ability to reply to it.

In order to create a new discussion you use the action in the top toolbar (plus sign). That will launch a form that allows you enter the data needed to create a new discussion.

The following data can be entered:

A user can reply to a discussion using the reply button located at the top or bottom of the discussion. The reply form is the same as the one you use when you create a new discussion but you are not able to set a subject (see chapter above on creating a new discussion)

Using tvc.properties create/reply discussion form fields can be configured to be hidden except Subject and Message fields.

The ability to discuss around objects can be configured on the server. This is done in a file called TVCDiscussionConfig.xml that is placed in /WEB-INF/classes/TVCDiscussionConfig.xml. If you skip to have this configuration file the users will be able to discuss around ANY object in Enovia with default settings.

Below is an example configuration file that shows the supported elements and their location.

Messages are often created in context of an object. It can later on be found when navigating to that particular object and then opening the discussion panel. The cloud concept allows labeling of messages with other entities. It can be other objects or fictive clouds.

Example: Let’s presume we are in the apparel industry. We are working with seasons and each season we launch a number of products which in turn consists of parts. When a message is created on a product it should be labeled with the season cloud. Messages created on a part should be included in both the product and season cloud. Once users navigate to the product or season they can see discussions related to the product/season cloud.

When a discussion is created and sent to some users all of them are automatically subscribed (started watching) to the thread. Any reply to the thread is notified to all the subscribers/watchers of the thread.

Any time user can unsubscribe or stop watching the thread clicking the stop watching. Any time use can start watching the thread by clicking start watching.

Start watching / Stop watching action can be performed in inbox as well.

When a thread is replied number of watchers to the thread is shown. Clicking the watcher count will show all users watching the thread.

By default the reply form is opened in "popups". This is good for visibility since the form gets all focus. However this prevents the users from reading the previous replies while doing a new reply. So if it is more important to be able to see the entire discussion while replying we have added a new rendering mode called "single page mode". This will do the following two changes to the UI:

This mode is enabled by setting the following parameter to true.

At some events that occur in the discussion functionality there are "notifications" sent out to users that are involved in a discussion in one or more ways. If someone starts a discussion around an object then the owner of that object will get a notification. Users will also get notifications when another user is replying to a discussion or message that user started.

These notifications are sent to the user instantly when an event is occurring. We have two ways of notifying the users, one called "Inline notifications" and one called "Web notifications". These work in the same way but are displayed in different ways.

The inbox is a functionality used for displaying all notifications that a user has received. It has a layout that is similar to a mail application.

Figure: Inbox displaying notifications

"ToMeAction" is a predefined custom Inbox Actions which depends on Exalead that can used in "My Space". This action shows the inbox items sent to the context user as Recipient.

"UnreadAction" is a predefined custom Inbox Actions which depends on Exalead that can used in "My Space". This action shows the inbox items which are not read by the context user.

"SystemNotificationAction" is a predefined custom Inbox Actions which depends on Exalead that can used in "My Space". This action shows the inbox items which are system generated. System generated Inbox items are identified using System Tags. Refer the consecutive chapters for configuration.

"FollowupAction" is a predefined custom Inbox Actions which depends on Exalead that can used in "My Space". This action shows the inbox items which are followed by the context user.

Following Inbox items using Context Menu:

Followup showing followed item by the context user:

The profile page has functionality for doing various types of actions related to the user. It is used for uploading an avatar image that will be displayed in discussions and for controlling user preferences.

Figure: Profile Page

"ExternalAction" is a predefined custom Inbox Actions which can used in "My Space". This action can be used to host External web application inside iframe of Collaboration component.

Bing.com as MySpace Action:

Inbox will have following context actions

Category’s label can be changed using "All Categories…​" context action.

From a table page, you can add a column that will show an icon when a discussion exists for the object. Clicking on the icon brings up the discussion panel.

To enable this column in your table, add a column like shown below:

If the table is defined as a system table, use the setting "Column Type" to achieve the same.

Below is a screenshot illustrating how the icon will appear in case there are discussions available.

Web App should reference following TVC endpoint in Script tag

TVC Collaboration Integration URL:

Attribute data-collaboration="path/integration.js" points to hosting web application’s integration scripts.

Web App invokes Collaboration script with configuration details.

Web App registers for collaboration ready event which is passed with collaborator interface.

Thread actions can be configured globally and is done using the following elements (placed directly under the <DiscussionConfigs> element). This will then be used for ALL discussion configurations.

The first one will change the thread actions in the inbox and the second one for the side panel. See more details later in this document.

Thread actions and top toolbar actions can also be configured for different discussion configurations. This means you can have different actions depending on what configuration is used. You can also configure actions for the different My Space inboxes.

The top toolbar for the side panel is configured like this (placed inside a <DiscussionConfig> element).

Thread actions for side panel are configured like this: (placed inside a <DiscussionConfig> element)

Thread actions for an inbox are configured like this: (placed inside a <InboxAction> or something that is derived from that)

All the different configuration elements share the same abilities of configuration. You can ADD commands using a TVC XML menu configuration AND/OR add or remove commands using Java code.

By adding a reference to a TVC XML menu configuration it is possible to add one or more actions. This uses the same menu configuration as other TVC (not everything supported though). Below is an example configuration:

Use either the <Image> or <FontIcon> element to control the action icon. Action commands are by default opened as a popup but it is also possible to specify a JavaScript to be executed on click. Use the <Label> element for adding a text to the action (not used for top toolbar).

If more complex logic is needed to control what actions to show it is possible to use JAVA code to achieve this. It is done by adding an attribute called className that points to a custom JAVA class that extends one of the following classes:

In the custom Java class it is possible to override the following method:

That method will allow you to return the menu to use. By calling the super class method it is possible to get the default menu. The MenuContext object contains information like user, thread and context.

In order to enable a filter you can reference a filter configuration in your TVCDiscussionConfig.xml file like this.

Date formats inside collaboration user interface can be configured to display custom date format.

Collaboration component uses moment.js version 2.4.0 (http://momentjs.com/) for date/time display. So supporting formats documented here http://momentjs.com/docs/#/displaying/format/ and also a custom format "fromNow" equivalent to moment.js’s "fromNow" functionality.

Below properties can be configured to format the date used in sections of the collaboration component.

Additional property configurations for Collaboration

The wiki can be used in different contexts. You can have a "global" Wiki that is accessible from the global toolbar and you can also add the ability to get a separate "context" wiki for each ENOVIA object instance of configured types (Projects, Workspace, Parts…).

The following is a list of the minimum requirements for the installation of the Wiki. If your system is different, consult Technia before installing.

The database schema includes a Command that can be used to access the Wiki. This command is called "TVC Wiki". If this command is added to the global toolbar it will enable the Global Wiki. If it is added in context of an ENOVIA type (in type menu or as a TVC Tab) it will enable the Wiki for that type. If you want to use the "slim" version of the wiki as a context wiki you use the command called "TVC Wiki Slim".

In order to enable users to start using the Wiki functionality there are three different roles that can be assigned depending on what access level should be given.

This access is set in several xml configurations (commands) for the component so they can easily be changed by overriding these files with custom access roles or expressions.

All objects created by the Wiki component are saved in a separate vault called "TVC Wiki"

There is two ways of creating a new wiki page.

The page created must be given a unique name that is not used by another page in the current Wiki. When a page is created it will be "blank" and have no content.

A Wiki page can have any number of comments to it added by the users. These comments are shown at the bottom of each page.

From the Wiki page attachments tab you can upload attachments to the page. Image attachments can then be inserted in to the Wiki page from one of the editors. All attachments can also be downloaded from this page. If you have TVC File Manager installed you will also see the field for drag n drop upload.

On the Wiki page history tab you can see all versions of this page. A new version of the page is created each time a user makes an edit. In the table you can see all versions, when they were created and by who. The "view" columns allow you to see the content of a specific version, either as Rich Text or as markup.

If you also have the TVC Structure Browser component installed in your system you are able to use the "Reference Objects" tab. This tab gives you the ability to use a TVC Search to find any ENOVIA object in the system and connect that to the current wiki page. You can then very easily refer to these objects with links inside your page content.

If you also have the TVC Structure Browser component installed in your system you are able to use the "Administrate" tab. From this tab you can do some various administrative tasks like deleting, removing and adding pages/comments.

In the top right corner of the Wiki you have a free text search field. This allows the user to make a free text search that searches all pages in the current Wiki. The search is configured to check both page names and page content. In order to get a search result you have to enter at least three letters in the search box and you will then be presented a list of matching pages. Each time you enter another letter a new result will be shown. This search is currently using ENOVIA queries to fetch the search result.

The TVC Wiki uses the same markup language as MediaWiki (software used in Wikipedia and other wikis). The complete MediaWiki markup language is currently not supported (only the basics) and there is also some extra markup added that is unique to the TVC Wiki.

A typical configuration hierarchy:

The fields can take advantage of auto-completion. If you have a field that applies to "type" and is editable, the way to configure such field to take advantage of auto complete is slightly different. See example below:

E.g. you use the setting "Type" to specify the "root" type for the object.

If you want to enable auto completion for users, then you can enable that through the following configuration:

Both on control, section level as well as per field level, one can restrict access to the control/section/field.

The access restriction can be defined based upon following:

The example below illustrates how you can construct the access restriction:

Or use an access program:

The upload page can be launched with the following action.

This will launch a page that allows you to upload new images to the object you are in context of. Any previously uploaded images will also be displayed.

If you have the TVC File Manager installed this page will include a drop zone allowing you to drag and drop files from your computer (Note: This does not use the standard applet based drop zone from the TVC file manager so it cannot be configured with drop zone handlers etc.) Since this drop zone is html5 based it will only work in browsers that supports this, see Browser Requirements below for more information.

There is also a button allowing you to open a standard file browser to select images from your computer.

The images will be uploaded to a connected "Image Holder" object, see section 6.2 (Images and annotations data model) for more information.

The image browsing page can be launched with the following action.

This will launch a "gallery" with thumbnails of all the images currently uploaded to the object. This gallery allows you to browse/view all images in various ways.

There are a number of request parameters you can use to configure the gallery when launching this action. NOTE: All string values needs to be inside apostrophes.

The image editing page can be launched with the following action.

This will launch a page displaying all uploaded images with a menu containing some image editing commands.

The "Set as primary" command will set the selected image as "primary".

The "Delete Image" command will delete the selected image.

The "Annotate" command will launch the image annotation page for the selected image. See next chapter for more detailed information about this.

The image annotation page can be loaded directly for an image with the following action.

This action needs the following parameters when loaded

This will launch the image together with a toolbar of commands that allows you to annotate the image with text and different shapes. The annotation will be saved in the database (both annotation data and as a flattened image) so you can load an existing annotation for later editing/viewing. For detailed information on how the annotations are saved, see the chapter: Images and annotations data model.

The Image Browsing and Image Editing pages can be loaded with images from several objects at the same time. You can do this in two different ways, either by sending several object ids as request parameters or by using a related object expression to load the other objects.

The data can be loaded using a couple of different alternatives:

To use an expansion, the image flow must be launched in the context of an object, while the latter doesn’t require so.

Here is a brief description of which settings are available for tweaking your charts, per chart type.

The data provider element defines how the data that drives the chart is being loaded. Depending on how the data is being loaded, the format of the data provider value is different. The purpose of a dataloader is to provide the objects (and optionally connections) that is being a part of the chart.

The list below illustrates the different data providers that are supported, and the format:

A loader might require input, while some don’t. The loaders that requires input can either use input from a loader defined as a child element OR it can use the input as provided by the caller (typically from request parameters such as "emxTableRowIdParam" passed from selected rows in a table/structure page OR the "objectId" parameter that also is used to pass the id of one or more objects).

Below is an example how to "nest" the loaders:

Note that this example is not complete; some configuration details has been left out for readability purpose.

What this example actually does is:

This illustrates how to accomplish a quite complex data-retrieval just by using a combination of different loaders. If you would have implemented this code as for example a JPO, you would typically need to implement +100 rows of Java code.

A complete definition how to expand a structure is shown below. Note that some elements are optional.

Setting the depth to 0, you will expand as deep as possible. This can only be done in one direction.

The difference is that the first approach will execute slightly more efficient.

Executing an inquiry can be done in two different ways. Either you will reference an existing inquiry by its name, or you can define the inquiry inline. Below are two examples illustrating both ways.

Alternatively, you can also say:

Or by defining the inquiry inline:

A complete definition how to perform a query is shown below. Note that some elements are optional.

The JPO loader can be used to invoke a JPO. The example below illustrates how to configure such loader.

Alternatively, you can also say:

The JPO method must return a MapList where each Map in the list contains the "id" and optionally the "id[connection]" key.

The select loader selects id’s based upon the input to the select loader. Below is an example how to do so:

By default, the select loader assumes that you select on business objects, and the select returns other business object id’s. If you select on relationships, or your select clause returns connection id’s, see below for details.

Note 1: In this case, the select is done upon the implicit input objects as provided by the client. You can use a child-loader also; in that case, the select is based upon the objects provided by that loader.

Note 2: it is possible to have several statements. Each statement must of course return object-ids.

If you have select statements that operates on connection id’s; then you can specify so as shown below:

If your select statement would return connection id’s instead of object id’s, then you can specify so as shown below:

If you only have one select statement, this can be written as:

The flatten loader doesn’t have any configuration options. The only requirement is that the input to this loader is a structure; if not, nothing will be done by this loader.

Example:

The end items loader doesn’t have any configuration options. The only requirement is that the input to this loader is a structure; if not, nothing will be done by this loader.

Example:

The remove duplicates loader requires input, either a structure or a flat list. In case of a structure, the removal of duplicates is only made on the root-nodes in the structure.

Example:

If you need to retain occurrences of the same object if the connection id differs, specify so using the attribute "ignoreConnectId" as shown below:

The filter loader can be used to filter out objects based upon an expression. This loader requires input. The example below expands a structure, makes it flat, then applies the filter and removes all the rows not matching this filter.

Alternatively, you can also say:

NOTE 1: The expression is evaluated using the ENOVIA select statement "evaluate[${EXPRESSION}]". All rows returning TRUE will be accepted, others will be filtered out.

NOTE 2: If you need to combine criteria using AND/OR operators; you might in some cases need to use the AND or OR key words instead of using the && and || operators. This is due to a bug/behaviour of ENOVIA.

For example the expression shown below:

Might need to be rewritten as shown below:

E.g. the operators || and && could be changed to OR and AND.

To verify your expressions, you can from MQL do:

NOTE 3: If your expression should be evaluated against the connections instead of over the business objects, which is the default, then you can say so as shown below:

To use a custom loader within a data-set that is implemented in Java, this can be done through the example below:

The class specified must implement one of the interfaces below:

If your custom Java class supports load by a child loader, you need to implement the DataLoaderWithInput interface.

The source objects as provided by the client through for example request parameters will be used by the data-loaders that require input, but doesn’t have any input configured in the data-set XML file through any child loaders, implicitly.

To explicitly define that you will use the source objects, then you can define this in the Data set XML file like shown below:

The id of the person object associated with the current user can in some cases be useful to start from when for example expanding a structure. Below is an example how to use it:

This example will expand the person object and finally filter out all rows in the structure except for the "end items".

The id of the company object associated with the current user can in some cases be useful to start from when for example expanding a structure. Below is an example how to use it:

This example will expand the company object and finally filter out all rows in the structure except for the "end items".

In some cases when you have expanded a structure, you only want to remove the root nodes. This can be accomplished as shown below:

The "RemoveRoots" element doesn’t have any configuration options.

A dataset might use the outcome from another dataset. This can be accomplished as shown below:

In conjunction with the Flatten loader, which converts a structure into a flat list, you can use the Structure loader to convert a flat list into a structure.

Each row in the flat list used as input to this loader will be set as root node in the returned structure.

Note that if the input to this loader is a structure, no change is made.

You can configure this loader with some additional attributes:

Example:

To combine the result from several loaders, you can use the "Union" loader. This can be accomplished as shown below:

In this example, we combine the result from three queries and the result from a referenced data-set.

If any of the loaders contains structural data, the outcome of this loader becomes a structure.

To force flat list, you can use the attribute "forceFlat" on the <Union> element and set the value to true. E.g.

This loader will return the ID’s that are part of all child loaders. Example:

The result from the example below will contain the objects that are in both the results from the specified data-sets.

By default, this loader uses the object-id’s. However, you can configure it to use the relationship id’s instead. This is accomplished as shown below:

To exclude data from a loader, you can use the Complement-loader. It allows you to define nested loaders, which defines the maximum objects/connections to be included. From this maximum set, you can exclude objects/connections.

See the example below which queries the system for all Person objects, but excludes the one representing the current user.

Both the <Include> and <Exclude> elements accepts multiple loaders.

By default, any data loader within a data set is run with the same context (credentials) as the user who is logged in. In some cases, you might want to run a query as a super user in order to by-pass any access checks that are expensive to evaluate. To do so, you can accomplish this as shown below:

This loader is used to get only the latest revision of the object which is in the specific state. For example this can be used to only get the latest "Released" revision of a part. Example of this scenario:

The syntax of a parameter is:

Options is a comma separated list of options. An option consists of a key and value separated with the equals character. The available options are listed below:

Below are some examples of how the parameterized values can be used.

Example where the expand properties are parameterized.

Another example using an inquiry.

Most but not all configuration parameters within the DataSet XML definition allows specifying parametrization macros. The table below shows the supported places.

Since the DataSet’s now may contain special macro references using $() keywords, you may in rare situations need to escape such keywords if you don’t intend to resolve it as a macro.

Fortunately you can either disable parametrization completely on that particular DataSet or escape these sensitive characters using the backslash key.

For example:

Note that if you today are using backslashes, these are now treated as escape chars and hence you would need to escape the backslash also. So be aware of the following

Uses a dataset to define available search options. If the field is in context of an object, e.g. in a top panel, the object id will be available in the dataset. This makes it possible to do operations which requires input, e.g. expansions.

Example using dataset handler in Forms:

Displays ranges available for the field/cell.

No additional settings.

Searches for business objects using a query. Most often you enter some criteria to limit the search result, for example you will add a typePattern and whereClause to only get the first revision of parts.

The logging output from TVC could be configured. Default, only problems that are fatal are displayed within the log files.

The init-parameter that controls the log output for all TVC Components is defined as below:

This will enable DEBUG output from all components (and generate a lot of output).

Following examples illustrates how to define different log levels for different components:

Enable debug output for TVC Core:

Enable debug output for the Structure Browser:

Enable debug output for the Report Generator:

The log-level can be changed meanwhile the application server is running. This is done by entering an URL in the browser (note that you must be logged on as a user with administration possibilities).

Optionally, the parameter logDomain could be added to explicitly define a specific component (same as for the web.xml configuration).

The possible values for the log levels are:

Example:

The logging output can be extended to contain user name (the Matrix user name) and the IP address of the user. This feature is by default disabled, and can be enabled by:

Adding an init parameter to the servlet like below:

The category tree has been replaced with a toolbar menu. Commands that previously were shown in the left-hand category tree now appear in a toolbar menu.

There is a bug with the ENVOIA toolbar implementation that results in that the ID of the object is not passed correctly to all toolbar-commands. When you have commands in this menu whose HREF doesn’t contain a reference to a JSP page (like the example below), then the parameters are not added to the HREF as it should.

The work around for this bug is to add a bogus page reference to the HREF as shown below:

E.g. adding something ending with .jsp will cause the ENOVIA toolbar to add the required parameters. Note that you need an additional slash character before the actual "jsp page" name.

This doesn’t have any impact on TVC itself, since the only important token is what appears after the "tvc-action/" string up to the next slash. The added JSP page is ignored.

NOTE: Commands in the category menu calling TVC should not have the setting "Submit" set to TRUE. This will cause other irrelevant parameters to be passed into TVC possibly overloading parameters typically defined in configuration objects used by the different TVC components (for example page-configurations, grid browser configurations etc.). This setting were not used previously when the left-hand category tree were used, so all commands needs to be reviewed to ensure that they don’t have this setting applied.

As of ENOVIA 2012 and later, the user interface does not have the left hand tree containing the functions available for a particular object. Instead, these functions have been moved into a category menu.

TVC has now support for the category menu in the following places.

Below are some example screenshots showing how the category menu appears in different pages.

Top panel with category menu

Report Generator List Page with Category Menu

Structure Browser with Category Menu

The category menu will appear if the request parameter called "categoryTreeName" is available in the request (passed by default by ENOVIA). There are two options available for disabling the category menu even though it is being passed.