Structure Browser - Administration Guide : Configuring Commands

1. Commands

The Structure Browser is commonly launched from Commands (for instance, a Command can be configured to launch the Structure Browser from the tree category of a certain business type). This section describes how to launch the Structure Browser from a Command and the available configuration possibilities when doing so.

1.1. Common URL Parameters for Structure Browser

This section describes the common URL query string parameters that can be used to configure the behaviour of the Structure Browser. While most parameters are optional there is one parameter called "view" that is required unless you use a page configuration object to configure the Structure Browser. See Using Page Configuration Objects for an alternative way to configure the Structure Browser.

Query string parameters appended to a URL consist of name-value pairs separated by an ampersand (&) while the entire query string is separated from the rest of the URL using a question mark (?). The following example is a relative URL to the JSP page /url/to/some/page.jsp where the query string parameters param1 and param2 have been appended. The value of param1 and param2 is value1 and value2 respectively.

/url/to/some/page.jsp?param1=value1&param2=value2

The following table describes parameters that can be used to configure Structure Browser when launching it using one of the methods described below. Some methods require additional parameters, which are covered in the section describing a particular method.

Common URL parameters for configuring the Structure Browser:

URL Parameter Description Examples

URL Parameter	Description	Examples
pageConfig	The name of the page-configuration. A page-configuration can be used instead of the common URL parameters to configure the behaviour of the Structure Browser.	pageConfig=My Config
view	Required if pageConfig isn’t defined. The name of the view object that defines which table and filters to use. See Views for more information on how to manage views.	view=Default View
choosableViews	This parameter defines the view objects that should be selectable from the table page. Specify multiple view objects by separating them with a pipe character `\|`.	choosableViews=Default View\|Part View
selection	This parameter defines the selection mode on the table page. Accepted values are "none", "single", and "multiple". The default value is "none".	selection=multiple
counter	This parameter defines whether a row number will be displayed as the leftmost column in the table. Accepted values are "true" and "false". The default value is "true".	counter=false
toolBar	The name of the Menu admin object that contains the commands to be displayed in the toolbar. See Toolbars for more information.	toolBar=PartToolBar
contextMenu	The name of the Menu admin object that contains the commands to be displayed/used as a context menu.	contextMenu=MyContextMenu
visible	This parameter configures which items should be visible on the table page. Accepted values are listed in the next chapter. Separate multiple values with a pipe character (`\|`)	visible=view\|table\|filter\|reload\|gothere
header subHeader	These parameters define the header and sub header that will be displayed on the table page. The values of these parameters can be either plain text or a string resource file ID. Note that when using a string resource file ID it is required that the "Registered Suite" setting has been defined on the command. The values can also contain select expression macros that will be evaluated on the current business object. The current business object refers to the objectId parameter that is sent with the URL. Note that you normally don’t add the objectId parameter yourself as it will be added automatically by the system, for instance, when executing a command on a business objects tree menu.	`header=My Parts` or `header=$<name> rev. $<revision>&subHeader=EBOM Structure`
edit	This parameter configures whether the Structure Browser should be opened in edit mode by default when clicking on the command.	true – The Structure Browser will be opened in edit mode. false – The Structure Browser will opened in read mode. This is the default value.
PrinterFriendly	This parameter configures whether the printer friendly button will be available or not. This function will create a printer friendly page of the structure browser in a separate popup window.	PrinterFriendly=true
Export	This parameter configures whether the export button will be available or not. This function is similar to the export function of the emxTable.jsp page.	Export=true
addToCollection	This parameter configures whether the "add item to collection" button will be available or not.	addToCollection=true
manageCollections	This parameter configures whether the "manage collections" button will be available or not.	manageCollections=true

pageConfig

The name of the page-configuration. A page-configuration can be used instead of the common URL parameters to configure the behaviour of the Structure Browser.

pageConfig=My Config

view

Required if pageConfig isn’t defined. The name of the view object that defines which table and filters to use. See Views for more information on how to manage views.

view=Default View

choosableViews

This parameter defines the view objects that should be selectable from the table page. Specify multiple view objects by separating them with a pipe character |.

choosableViews=Default View|Part View

selection

This parameter defines the selection mode on the table page. Accepted values are "none", "single", and "multiple". The default value is "none".

selection=multiple

counter

This parameter defines whether a row number will be displayed as the leftmost column in the table. Accepted values are "true" and "false". The default value is "true".

counter=false

toolBar

The name of the Menu admin object that contains the commands to be displayed in the toolbar. See Toolbars for more information.

toolBar=PartToolBar

contextMenu

The name of the Menu admin object that contains the commands to be displayed/used as a context menu.

contextMenu=MyContextMenu

visible

This parameter configures which items should be visible on the table page. Accepted values are listed in the next chapter.

Separate multiple values with a pipe character (|)

visible=view|table|filter|reload|gothere

header

subHeader

These parameters define the header and sub header that will be displayed on the table page.

The values of these parameters can be either plain text or a string resource file ID. Note that when using a string resource file ID it is required that the "Registered Suite" setting has been defined on the command.

The values can also contain select expression macros that will be evaluated on the current business object. The current business object refers to the objectId parameter that is sent with the URL. Note that you normally don’t add the objectId parameter yourself as it will be added automatically by the system, for instance, when executing a command on a business objects tree menu.

header=My Parts

header=$<name> rev. $<revision>&subHeader=EBOM Structure

edit

This parameter configures whether the Structure Browser should be opened in edit mode by default when clicking on the command.

true – The Structure Browser will be opened in edit mode.

false – The Structure Browser will opened in read mode. This is the default value.

PrinterFriendly

This parameter configures whether the printer friendly button will be available or not. This function will create a printer friendly page of the structure browser in a separate popup window.

PrinterFriendly=true

Export

This parameter configures whether the export button will be available or not. This function is similar to the export function of the emxTable.jsp page.

Export=true

addToCollection

This parameter configures whether the "add item to collection" button will be available or not.

addToCollection=true

manageCollections

This parameter configures whether the "manage collections" button will be available or not.

manageCollections=true

1.1.1. Visible Parameter

Visible Value	Description
view	The view selector will be displayed on the page with which the user can choose among the selectable views defined with the "choosableViews" parameter.
table	The table selector will be displayed on the page with which the user can choose among the available tables as defined in the current view.
filter	The filter selector will be displayed on the page with which the user can choose among the available filters as defined in the current view.
reload	The reload button will be displayed on the page with which the user can reload the data in the table.
edit	The edit button will be displayed on the page with which the user can toggle edit mode.
sort	The sort button will be displayed on the page (but only if the current table has any sortable columns) with which the user can choose to sort on up to three columns at the same time.
expand	The expand button will be displayed on the page (but only in structure mode and when the filters allow recursive expansion) with which the user can expand the entire structure.
gothere	The gothere button will be displayed on every row in the table with which the user can choose to navigate a certain object (i.e., change the root object in the structure).
structuresearch	If either this value or "advancedfilter" is present, the search button will appear on the toolbar.
disconnect	The disconnect button will be displayed on the page with which the user may use to disconnect two objects.
advancedfilter	If either this value or "structuresearch" is present, the search button will appear on the toolbar.
chart	Whether the chart button should be visible or not. This function requires the TVC Graphical Reporting component.
preferences	Whether the user preferences function should be available or not
columnfilter	Whether the column filter function should be available or not
clipboard	Whether the clipboard functionality should be available or not.
flatten	Whether the flatten structure functionality should be available or not.
datagroup	Whether the data group functionality should be available or not.
maximize	Whether the maximize button should be visible or not. The maximize button can only be visible if the category tree is present, and the structure browser is shown in the content frame right to the category tree.
promote	Whether or not the promote button is available.
demote	Whether or not the demote button is available.
trigger	Whether the trigger validation button should be available in the toolbar or not (Only for V6R2009X or later).
compare	Whether the compare button should be available in the toolbar or not (Only for V6R2009X or later).
wrap	Whether the wrap or unwrap button should be available or not.

Visible Value

Description

view

The view selector will be displayed on the page with which the user can choose among the selectable views defined with the "choosableViews" parameter.

table

The table selector will be displayed on the page with which the user can choose among the available tables as defined in the current view.

filter

The filter selector will be displayed on the page with which the user can choose among the available filters as defined in the current view.

reload

The reload button will be displayed on the page with which the user can reload the data in the table.

edit

The edit button will be displayed on the page with which the user can toggle edit mode.

sort

The sort button will be displayed on the page (but only if the current table has any sortable columns) with which the user can choose to sort on up to three columns at the same time.

expand

The expand button will be displayed on the page (but only in structure mode and when the filters allow recursive expansion) with which the user can expand the entire structure.

gothere

The gothere button will be displayed on every row in the table with which the user can choose to navigate a certain object (i.e., change the root object in the structure).

structuresearch

If either this value or "advancedfilter" is present, the search button will appear on the toolbar.

disconnect

The disconnect button will be displayed on the page with which the user may use to disconnect two objects.

advancedfilter

If either this value or "structuresearch" is present, the search button will appear on the toolbar.

chart

Whether the chart button should be visible or not. This function requires the TVC Graphical Reporting component.

preferences

Whether the user preferences function should be available or not

columnfilter

Whether the column filter function should be available or not

clipboard

Whether the clipboard functionality should be available or not.

flatten

Whether the flatten structure functionality should be available or not.

datagroup

Whether the data group functionality should be available or not.

maximize

Whether the maximize button should be visible or not. The maximize button can only be visible if the category tree is present, and the structure browser is shown in the content frame right to the category tree.

promote

Whether or not the promote button is available.

demote

Whether or not the demote button is available.

trigger

Whether the trigger validation button should be available in the toolbar or not (Only for V6R2009X or later).

compare

Whether the compare button should be available in the toolbar or not (Only for V6R2009X or later).

wrap

Whether the wrap or unwrap button should be available or not.

If some chart depends on promote or demote user can subscribe to the chart by command name. We are auto-publishing here, so no specific publish setting is required.

1.1.2. Disable Launch button from Portal

Sometimes the user wants to disable the launch from portal button.

Example of a pageconfig:

<PageConfig>
    ...
    <Parameters>
        <Parameter name="displayLaunchFromPortalButton" value="false" />
    </Parameters>
    ...
</PageConfig>

1.2. Launching Structure Browser in Navigate Mode

This is perhaps the most common way to launch the Structure Browser. To achieve this you need to create a Command object that will be used to launch the Structure Browser and add it to the Menu object that defines a certain business type’s tree category (e.g., the tree category Menu for business objects of type "Part" is called "type_Part").

Figure 1. Structure Browser in action

When creating a command to launch the Structure Browser in navigate mode from a tree category, you will need to edit some of the configurable parameters and settings on that command in a specific way. The most important parameter is "Href", whose value must be a URL to the Structure Browser (the "Href" parameter configures which web-page to request on the server when clicking on a Command). The URL to the Structure Browser is:

${ROOT_DIR}/tvc-action/navigate

Moreover, the URL should contain query string parameters to configure the behaviour of Structure Browser (e.g., which view to use, which showInternalHelp to use, which buttons/choosers should be visible). See this chapter for more information on which parameters are available.

Figure 2. Creating a Command to launch the Structure Browser from a tree category with a view called Default View

The next step is to add some settings on the Command. They will configure how the Command behaves when clicking on it. The following table describes the required settings.

Required settings for a Command that launches the Structure Browser from a tree category

Setting	Description	Accepted Values/Examples
Registered Suite	This setting defines which application the command belongs to. The value should be the name of an application as defined in the emxSystem.properties file when removing the "eServiceSuite" prefix. For instance, if the name of the application in emxSystem.properties is "eServiceSuiteEngineeringCentral" then the value for this setting should be "EngineeringCentral". This setting will cause the system to send the "suiteKey", "emxSuiteDirectory", and "StringResourceFileId" parameters in the URL when the column’s values are displayed as hyperlinks. Note that this setting is required for the system to know which string resource file to use when the Label or Alt of a command has been specified as a string resource ID.	Framework InfoCentral EngineeringCentral ProgramCentral
Target Location	This setting defines the target frame when executing the command. The value should be set to "content" to ensure that the Structure Browser is loaded in the correct frame.	content

Setting

Description

Accepted Values/Examples

Registered Suite

This setting defines which application the command belongs to. The value should be the name of an application as defined in the emxSystem.properties file when removing the "eServiceSuite" prefix. For instance, if the name of the application in emxSystem.properties is "eServiceSuiteEngineeringCentral" then the value for this setting should be "EngineeringCentral".

This setting will cause the system to send the "suiteKey", "emxSuiteDirectory", and "StringResourceFileId" parameters in the URL when the column’s values are displayed as hyperlinks.

Note that this setting is required for the system to know which string resource file to use when the Label or Alt of a command has been specified as a string resource ID.

Framework

InfoCentral

EngineeringCentral

ProgramCentral

Target Location

This setting defines the target frame when executing the command. The value should be set to "content" to ensure that the Structure Browser is loaded in the correct frame.

content

Figure 3. Configuring required settings on a Command that launches the Structure Browser from a tree category

Once the Command has been created you only have to add it to the Menu object representing the tree category of your choice. This will make it available to the users of the application. Note that you might have to reload any UI cache used by the Value Chain Portfolio applications to make the Command appear where you added it (the Application Exchange Framework usually maintains a cache of user interface objects like Menus and Commands. Please consult documentation of the AEF if you are uncertain on how to reload the UI cache).

1.2.1. Navigating Multiple Root Nodes

Normally when you launch the Structure Browser you’ll end up with a single root node that can be expanded or collapsed. However, the Structure Browser can also be used to navigate multiple root nodes at the same time.

Figure 4. Navigating with multiple root nodes

This is the order in which the Structure Browser will try to load root nodes:

If the loader parameter is present. The value of this parameter can be one of:
1. A named data-set (see Core administration guide for details how to configure a data-set)
2. A class that implements the interface: com.technia.tvc.structurebrowser.actions.loader.TableBeanLoader
If an inquiry has been specified through the inquiry request parameter, root nodes will be loaded from the inquiry. See this chapter for more information on how to create an inquiry that loads root nodes into the Structure Browser.
If a JPO has been specified through the program request parameter and the value is formatted as: <JPOName>:<MethodName>, root nodes will be loaded from the specified JPO and method. See Retrieve Table Rows for more information on how to create a JPO that loads root nodes into the Structure Browser.
If the emxTableRowId parameter was sent with the request a root node will be inserted for each occurrence of the parameter.
If the objectId parameter was sent with the request a root node will be inserted for each occurrence of the parameter.

1.2.2. Navigating Shadow Structures

This can also be configured per view.

When a certain structure contains shadow or intermediate objects that only act as containers on behalf of their parents you sometimes don’t want these intermediates to be visible to the end user. The Structure Browser can easily be configured to skip intermediate objects of certain types. For example, when navigating a Product/Feature structure in ENOVIA™’s Product Central application you normally don’t want to display the intermediate "Feature List" objects to the end user.

Figure 5. Skip intermediate objects

To enable this functionality you create your Command to launch the Structure Browser in the same way as described in this chapter except that you replace the URL with the following:

${ROOT_DIR}/tvc-action/navigateShadowStructure

You should also add at least one occurrence of the type URL parameter that configures which object types should not be displayed. Note that you can also add this parameter to the "TVC Custom Parameters" attribute when using a "TVC Page Configuration" object. See Using Page Configuration Objects for more information on how to create page configurations.

URL Parameter

Description

Examples

type

Configures which object types should not be displayed. Multiple occurrences allowed.

type=Feature List&type=GBOM

Table 3, Additional URL parameters navigating shadow structures

Figure 6. Example command for navigating shadow structures

Figure 7. Example page configuration for navigating shadow structures

1.2.3. Expanding with a JPO

This can also be configured per view

When filters can’t be used to navigate structures you can create a JPO that will be invoked whenever a user clicks on the expand link in the Structure Browser. The JPO should then return the immediate children of the object being expanded. The following code snippet can be used as a template when creating a JPO:

/* Imports */
import java.util.Map;
import java.util.HashMap;
import java.util.List;
import matrix.db.Context;

/* Class */
public class ${CLASSNAME} {

    /* Constructor */
    public ${CLASSNAME} (Context ctx, String[] args) {}

    /* Expand a business object on behalf of the Structure Browser */
    public List expand(Context ctx, String[] args) throws Exception {
        Map params = (Map) JPO.unpackArgs(args);

        // Get the object and relationship IDs
        // from the row being expanded
        String objectId = (String) params.get("objectId");
        String relId = (String) params.get("relId");

        // The result should be returned
        // as a MapList instance
        List ret = new com.matrixone.apps.domain.util.MapList();

        // TODO:
        //
        // Add business logic here for expanding
        // the business object to the next level.
        // Add a HashMap to the MapList for each
        // child object and specify the following
        // keys:
        //
        //  * id = The business object ID.
        //  * id[connection] = The relationship ID.
        //  * from = Whether the relationship is
        //    in the from direction or not.
        //
        // Example:
        //
        // Map map = new HashMap();
        // map.put("id", <OID>);
        // map.put("id[connection]", <RELID>);
        // map.put("from", Boolean.TRUE);
        // ret.add(map);

        return ret;
    }
}

JPO Template for expanding through a JPO

To enable this functionality you create your Command to launch the Structure Browser in the same way as described in this chapter except that you replace the URL with the following:

${ROOT_DIR}/tvc-action/navigateJPO

You must also add a parameter to the URL that configures the name of the JPO and method that should be invoked to expand a certain business object.

URL Parameter

Description

Examples

expandProgram

Required. The name of the JPO and method that should be invoked. The value for this parameter should be formatted like:

<JPONAME>:<METHODNAME>

expandProgram=MyExpandJPO:expand

Table 4, URL parameters when expanding through a JPO

Figure 8. Use a JPO to expand the structure

1.3. Launching Structure Browser in Flat Table Mode

When launching Structure Browser in flat table mode you will need to provide the table rows to the Structure Browser in one of two ways. The perhaps easiest way to do this is to load the Structure Browser from an Inquiry while another way is to use a JPO (Java Program Object).

Figure 9. Structure Browser in action

To launch the Structure Browser in flat table mode you need to create a Command and add it to the Menu of your choice that is visible in your application (e.g., the example above used a Command that was added to the "My Desk" menu for Engineering Central). When creating the Command you will need to edit its "Href" parameter to one of two URLs, which one you choose depends on whether you will be using an Inquiry or a JPO to retrieve the rows of the table. The URLs are:

${ROOT_DIR}/tvc-action/execInquiryToTable
${ROOT_DIR}/tvc-action/execJPOToTable
${ROOT_DIR}/tvc-action/execCustomLoaderToTable

Moreover, the URL should contain query string parameters to configure the behaviour of Structure Browser (e.g., which view to use, which toolbar to use, which buttons/choosers should be visible). See this chapter for more information on which parameters are available.

On top of the common parameters you will also need to add a parameter describing which Inquiry, JPO or Custom Loader the Structure Browser should use to retrieve table rows. The following table describes these parameters.

URL Parameter

Description

Examples

inquiry

This parameter is required when retrieving table rows using an Inquiry. It defines the name of the inquiry that will be evaluated.

inquiry=MyParts

program

This parameter is required when retrieving table rows using a JPO. It defines the name of the JPO that will be invoked. The value for this parameter should be formatted like:

<JPONAME>:<METHODNAME>

program=TVC Utils:getPartsForUser

loader

This parameter is required when retrieving table rows using a Java class or by using data-sets (see this page for details).

It the value defines the name of the Java class, it must point to a class implementing the interface:

com.technia.tvc.structurebrowser.actions.loader.TableBeanLoader

If it is a data-set, then it will represent the name of the data-set.

loader=com.acme.loader.MyLoader

loader=tvc:dataset/MyDataSet.xml

Table 5, configurable parameters when launching Structure Browser in flat table mode

Figure 10. creating a Command to launch the Structure Browser in flat table mode using an Inquiry to retrieve table rows

Additionally you may need to configure other parameters and settings on the Command you create, for instance you may want to define the setting "Target Location" to control in which frame the Structure Browser is loaded. However, these settings depend on where you plan to use the Command (i.e., to which Menu you plan to add it). Please consult documentation of the AEF (Application Exchange Framework) and VCP (Value Chain Portfolio) applications in order to find out what and how you need to configure the Command in those cases.

1.3.1. Launching a flat table from selected objects

An alternative to using inquiries to populate a flat table is to let users select which objects should be included. If an existing table, Structure Browser or ENOVIA OOTB, has selectable rows, this can be achieved with the following URL:

${ROOT_DIR}/tvc-action/selectedItemsToTable

It is important that your command has the Submit setting specified (value set to true).

Also, the HREF needs parameters, or a page-configuration specified.

The target location should be set to popup.

1.3.2. Zoom Selected

When working within the structure browser, you might want to reduce the objects you’re interested in. This can be accomplished by the "Zoom Selected" command (which works in a similar way as go-there).

To enable this, add a command that has the following configuration:

<Command>
    <Label>Zoom Selected</Label>
    <URL action="/zoomInSelected"></URL>
    <SubmitForm>true</SubmitForm>
    <RowSelectType>multiple</RowSelectType>
    <TargetLocation>tableContentFrame</TargetLocation>
</Command>

1.3.3. Searching with an Inquiry

The Structure Browser includes a function that enables administrators to easily create simple but powerful search forms embedded on a flat table page. The search itself is powered by an Inquiry, which also defines the editable query parameters.

Figure 11. Search-form embedded on a flat table page

To use this function you create a Command and edit the "Href" parameter to the following URL:

${ROOT_DIR}/tvc-action/inlineSearch

Moreover, you’ll also have to add the inquiry URL parameter and specify the name of the Inquiry that will perform the search. For example:

Figure 12. Command to launch a search

Create the Inquiry as described in this chapter. However, you’ll also need to specify which arguments should be editable query parameters using a special syntax. Also, you can specify a label, range values, default value, and how the parameters should be ordered on the table page.

First, the value of an argument that should be editable must be edit, followed by a comma-separated list of optional configuration parameters for that argument. The optional parameters are:

Parameter

Description

Examples

label

The label that is displayed on the table page.

label=Current

default

The default value for the query parameter.

default=Create

range

A valid range value. This parameter can be specified multiple times for multiple range values.

range=Create,range=Peer Review

order

The order in which the parameter will be displayed on the table page. The value of this parameter must be a non-negative integer. The argument with the lowest order will be displayed first.

oder=1

width

The width of the input field

width=5

Table 6, Available parameters for Inquiry arguments

The following images demonstrate how to create an Inquiry for this purpose. The Inquiry produces a search form with the following characteristics:

Figure 13. Example search form

Figure 14. Example Inquiry (Basics)

Figure 15. Example Inquiry (Code)

Figure 16. Example Inquiry (Arguments)

It is also possible to avoid loading the inquiry when the page is first entered. This is accomplished by adding a parameter to the URL called "load", the default value for this parameter is true. Setting this parameter value to false, will cause the inquiry not to be invoked.