05 April 2016

© Copyright 2003-2019 by TECHNIA AB

All rights reserved.

PROPRIETARY RIGHTS NOTICE: This documentation is proprietary property of TECHNIA AB. In accordance with the terms and conditions of the Software License Agreement between the Customer and TECHNIA AB, the Customer is allowed to print as many copies as necessary of documentation copyrighted by TECHNIA relating to the software being used. This documentation shall be treated as confidential information and should be used only by employees or contractors with the Customer in accordance with the Agreement.

This product includes software developed by the Apache Software Foundation. (http://www.apache.org/).

2. Personal Browser

In today’s mobile environment, Internet or corporate networks are not always available when needed. To be able to bring selected product information out in the field, TECHNIA has developed the Personal Browser component. The Personal browser lets you locally download up-to-the-minute product data structure (along with all of its attached files), to a laptop or PDA. You are then able to navigate the downloaded structure, and view or print its contents at any time, without being connected to the network.

The main features of the Personal Browser component are:

  • Download and browse Matrix structures in an intuitive way

  • Supports checkout for files associated with objects in the structure

  • Filter which objects, attributes and files to include

  • Define separate configurations for different use cases

2.1. Definitions

Definition Description

XML

Extensible Markup Language, abbreviated XML, describes a class of data objects called XML documents (http://www.w3.org/XML/).

HTML

Hypertext Markup Language is a language to publish information on the World Wide Web (http://www.w3.org/TR/html4/).

CSS

Cascading Style Sheets is a simple mechanism for adding style (e.g., fonts, colors, spacing) to Web documents (http://www.w3.org/TR/CSS1).

2.2. Usage Scenarios

The Personal Browser is primarily used for navigating ENOVIA/Matrix object structures offline. It does this by allowing the user to download the structure for a specific object. This is done by selecting the root object in the structure, initiate a Personal Browser download, select which configuration to use, and wait while the Personal Browser is created. Once the Personal Browser is complete it can be downloaded as a compressed ZIP archive.

image
Figure 1. Downloading a Personal Browser

The downloaded ZIP archive contains an HTML view of the downloaded structure that can be browsed for information and files.

image
Figure 2. The downloaded Personal Browser

2.2.1. Viewing Files

The files included in the Personal Browser can be opened by clicking on the file icons displayed to the right of an object in the structure.

image
Figure 3. Click the file icon to open the file in a new window

2.2.2. Localization Support

The Personal Browser supports localized names of type, relationships, attributes, vaults, policies, states, etc.

image
Figure 4. Support for multiple languages

This support relies on the "emxFrameworkStringResource.properties" files installed with the AEF (Application Exchange Framework) that contains the localized names of administrative objects.

2.3. Synchronizing Changes

As of 2011.3.0 a new feature has been added that allows synchronizing changes made to the files within a downloaded Personal Browser package.

To use this feature, you need to add a command in the user interface allowing so. This command can be launched from any place since there is no need for the command to get the object-id in the request since this information is collected from the uploaded Personal Browser package. The command should have the following configurations:

add command "UploadPersonalBrowser"
    label "Upload Personal Browser Package"
    href "${ROOT_DIR}/tvc-action/pbUpload"
    setting "Target Location" popup
    setting "Window Height" 600
    setting "Window Width" 800

Once launched, the user will be asked for the Personal Browser package file to be uploaded.

Processing the file can take some time depending on how large it is.

The files are compared for changes, and if there are changes those will be presented in a table from where the user can select what files to be synchronized.

3. Launching the Personal Browser

This section describes how to create Commands that launch the Personal Browser from within the Value Chain Portfolio Applications.

3.1. Commands

This section describes how to create a Command to launch the Personal Browser 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 Personal Browser is the "Href" parameter, whose value must be the following URL.

${ROOT_DIR}/tvc-action/personalbrowser

Note that when adding the command to a toolbar displayed in the standard Value Chain Portfolio applications it is sometimes necessary to append a bogus JSP page to the URL, e.g.:

${ROOT_DIR}/tvc-action/personalbrowser/foo.jsp
                                      ^^^^^^^^

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.

image
Figure 5. Creating a command
image
Figure 6. Launching the Personal Browser from the Part details page

3.1.1. Settings

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

Setting Description Required Value

Target Location

This setting defines the target frame when executing the command. The value should be set to "popup" to ensure that the Personal Browser is loaded in a new popup window.

Popup

Window Width

The width of the popup window. Recommended width is 400.

400

Window Height

The height of the popup window. Recommended height is 400.

400

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 Personal Browser.

Setting Description Required Value

Row Select

Defines the required row selection on the TVC Structure Browser page when launching the Personal Browser.

single

Submit

Defines whether to submit the row selections or not when clicking on the Command.

true

image
Figure 7. Adding setting to the Command

4. Configurations

In this section we describe how to create configurations for the Personal Browser. A configuration specifies which information should be included in the downloaded Personal Browser archive. In order to successfully configure the Personal Browser you will need to know what XML is, and how to create well-formed XML documents. More information on XML can be found at http://www.w3.org/XML/.

The configurations are defined in an XML document that is stored in a Page object within the Matrix database. This Page object and another Page object containing sample configurations are installed with the database schema for the Personal Browser component. The names of these Page objects are: "TVC Personal Browser Config" and "TVC Personal Browser Config Sample" respectively. Upon upgrading the Personal Browser component to a newer version the sample Page object might be updated and thereby shed light on new features. However, the Page object containing the actual configurations will not be updated.

image
Figure 8. The Page objects installed with the Personal Browser component
image
Figure 9. The Page object
Edit the configuration Page object in an XML editor or a text editor with XML support. This way it is easier to detect and avoid syntactical errors.

4.1. Defining Configurations

This section describes how to create a configuration, assign a name, display name and a description.

First of all, the element used to define a configuration is called Configuration, which is nested inside the document element (i.e., PersonalBrowserConfiguration) in the configuration file. There can be any number of Configuration elements nested inside the document element; the only restriction is that all configurations must have a unique name.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <DisplayName>EBOM with Specifications</DisplayName>
        <Description>
            Extracts the EBOM structure for the specified Part.
            Associated Part Specifications will be included.
        </Description>
        <Access>
            <!--
                This element contains information about which users will have access
                to download a Personal Browser using this configuration.
            -->
        </Access>
        <ValidFor>
            <!--
                This element contains information about which objects that this
                configuration should be available for.
            -->
        </ValidFor>
        <View>
            <!--
                This element contains information about how to display the objects
                and relationships on the downloaded HTML page.
            -->
        </View>
        <TypeConfiguration name="Part">
            <!--
                This element contains information about how to expand the structure
                from objects with the named type. It also contains information about
                which data that should be included or which that should be filtered.
                Note that there might be more than one TypeConfiguration element,
                each setting up different behavior for different object types. If a
                TypeConfiguration element doesn't include a name attribute, then it
                will be the default configuration for objects whose type doesn't have
                an explicit TypeConfiguration.
            -->
        </TypeConfiguration>
    </Configuration>
    <!--
        Possibly more configurations here...
    -->
</PersonalBrowserConfiguration>

4.1.1. Naming a Configuration

The name of a configuration is defined in the name attribute on the Configuration element. There are some restrictions that govern the names of configurations:

  • The name of a configuration must be unique

  • The name should not contain spaces or characters other than alphanumeric ASCII characters.

Note that the name of the configuration is only used within the system to identify a specific configuration (This is why it is so important for the name to be unique); it is never displayed to the end user.

The name of a configuration is set with the name attribute:

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.1.2. Display Name and Description

The display name and description of a configuration is what is displayed to the user in a Personal Browser Download window. The values of these settings can be virtually any text; you ,can for instance, have more than one configuration with the same display name, even though that might be confusing for the end user.

The display name and description are set with the DisplayName and Description elements respectively:

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <DisplayName>EBOM with Specifications</DisplayName>
        <Description>
            Extracts the EBOM structure for the specified Part.
            Associated Part Specifications will be included.
        </Description>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

It is also possible to have localized display names and descriptions. This is accomplished by defining multiple DisplayName and Description elements each with a different locale. However, it is recommended to always define a default display name and description without an explicit locale

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <DisplayName>EBOM with Specifications</DisplayName>
        <DisplayName locale="fr">
            <!-- French display name -->
        </DisplayName>
        <Description>
            Extracts the EBOM structure for the specified Part.
            Associated Part Specifications will be included.
        </Description>
        <Description locale="fr">
            <!-- French description -->
        </Description>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>
image
Figure 10. Display name and description of a specific configuration

4.2. Controlling User Access

User access can be controlled for every defined configuration. Only configurations that a user has access to will show up in the drop-down list in the Personal Browser dialog.

User access is defined within the Access element:

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <Access>
            <RoleList>
                <Role>role_GlobalUser</Role>
            </RoleList>
        </Access>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

Note that if no access has been specified (e.g., if no Access element has been added to the configuration or if the element is empty), all users will have access to that configuration. Moreover, if no configuration was valid for the specified root business object or if the current user isn’t allowed access to the valid configurations, a message will be displayed informing the user. Consider assigning access to the Command that launches the Personal Browser from within the Value Chain Portfolio applications whenever possible.

image
Figure 11. Message displayed when no suitable configuration was found

4.2.1. User Based Access Control

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:

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <Access>
            <UserList>
                <User>person_TestEverything</User>
                <User>Test ManufacturingEngineer</User>
            </UserList>
        </Access>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.2.2. Role Based Access Control

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:

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <Access>
            <RoleList>
                <Role>role_GlobalUser</Role>
            </RoleList>
        </Access>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.2.3. Group Based Access Control

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:

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <Access>
            <GroupList>
                <Group>Company Name</Group>
            </GroupList>
        </Access>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.2.4. Combining Access Control

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.

4.3. Defining Valid Root Object Types

When setting up a configuration it is possible to define for which object type (or types) a configuration should be available. For instance, if you are defining a configuration that extracts the "EBOM" structure for objects of type "Part", it is necessary to be able to define that that configuration should only be available when a "Part" has been selected as the root object for a Personal Browser download.

Define valid root object type by enclosing the name of the type within a Type element. The Type element is added to the TypeList element, which is added to the ValidFor element. It is possible to add more than one valid root object type by adding another Type element to the TypeList element. If no valid root object type(s) has been defined, the configuration is considered to be valid for all object types.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <ValidFor>
            <TypeList>
                <Type>type_Part</Type>
            </TypeList>
        </ValidFor>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.4. Logging

The personal browser can be configured to log creations of individual personal browser packages. Such logs are created as business objects in the database, containing information about whom that created the personal browser, which object it were created from and optionally a reason for creation message provided by the user.

If the "reason for download" is required, the user will be prompted for that in the dialog where the configurations are shown.

image

To enable logging for a particular configuration, simply add the Log element to the configuration as shown below.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <Log>
            <Enabled>true</Enabled>
            <ReasonRequired>true</ReasonRequired>
        </Log>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

The log objects being created are of type "TVC PB Log" and created in the vault "TVC Administration".

If you have the "TVC Structure Browser" component, these logs can easily be reviewed in a flat table list by using a command called "TVC Personal Browser Logs", which is installed as a part of the Personal Browser data model.

4.5. Configuring Delivery

By configuring the delivery mechanism of the personal browser you can enable automatic FTP upload. I.e., when the personal browser zip file has been created it will be automatically uploaded to the configured FTP server. The delivery of a personal browser is configured within the Delivery element (which is inside the Configuration element). Here is an example:

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <Delivery>
            <Online/>
            <FTP passive="true">
                <DisplayName>Company File Server</DisplayName>
                <Host>files.acme.com</Host>
                <User>foo</User>
                <Password encrypted="true">=q8YE</Password>
                <Directory>
                    <Text>personalbrowsers/</Text>
                    <CurrentUser/>
                    <Text>/</Text>
                    <Date/>
                </Directory>
            </FTP>
        </Delivery>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.5.1. Online Delivery

Online delivery refers to the user being able to download the personal browser when is has been created. This is the default behavior and if this is what you want to happen and nothing else you are not required to configure the delivery mechanism at all.

However, when you enable FTP delivery the online delivery function will be disabled. You are then required to explicitly enable the online delivery mechanism by adding the element Online inside the Delivery element.

4.5.2. FTP Delivery

To enable FTP delivery you add the FTP element inside the Delivery element. Note that if you enable FTP delivery the online delivery will be disabled and you are required to explicitly enable it if you still want it.

Passive Mode

By default, the personal browser component will connect to the FTP server in active mode. I.e., it will open a socket to which the FTP server then connects to retrieve the zip file. Due to network configurations (e.g., firewalls) this is not always possible. The alternative is to let the FTP server opens a socket to which the personal browser can connect to send the file, i.e., passive mode. To enable passive mode you add an attribute called passive with the value true on the FTP element.

Display Name

When a user starts creating a personal browser zip file through the web interface a message will notify the user that the file will be uploaded to an FTP server. The display name allows you to configure a human readable display name of the FTP server to which the file will be uploaded. E.g., ACME File Server. To configure a display name you simple add a DisplayName element inside the FTP element. As with display names of configurations you can add many display names each with a different locale.

Host, User and Password

It is necessary to configure the host of the FTP server (IP address or DNS name) as well as the name and password of the user that the personal browser will use when connecting to the FTP server. For this purpose there are three elements that you should add to the FTP element. These elements are Host, User and Password.

By default, you enter the password in clear text. I.e., anyone who has access to the configuration file will be able to read the password. Alternatively, you can encrypt the password with an MQL command and store the encrypted version in the configuration file. If you encrypt the password you will have to tell the personal browser that the password is encrypted. You do this by adding an attribute called encrypted with the value true on the Password element.

image
Figure 12. Encrypting passwords with MQL
Directory

You can also configure below which directory on the FTP server that the personal browser zip file will be uploaded. You do this by adding the Directory element inside the FTP element. To define the directory you are required to add the Text, Basic, Attribute, CurrentUser and/or Date elements inside the Directory element.

  • The Text element should be used to define static text that will be included in the title as is

  • The Basic element defines the name of a basic property whose value will be included

  • The Attribute element defines the name of an attribute whose value will be included.

  • The CurrentUser element will be replaced by the name of the user that creates the personal browser.

  • The Date element will be replaced by the current date (when the personal browser was created).

Please note that the Basic and Attribute elements will take the values from the root business object.

4.6. Password Protection

It is possible to configure the Personal Browser to let the user apply a password to the generated ZIP file and also apply the password to all PDF documents being a part of the package.

To configure this, look at the example below:

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <Password>
            <Required>true | false</Required>
            <ProtectPDF>true | false</ProtectPDF>
            <ProtectZIP>true | false</ProtectZIP>
            <MinLength>6</MinLength>
            <MaxLength>20</MaxLength>
        </Password>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

The Password element defines the password settings, such as if we should protect the ZIP package and/or each PDF document that is part of the package. Note that only PDF documents can be password protected; files of other formats within the package will not have this support.

The min and max length can be omitted or set to a negative value to remove the length restrictions.

4.7. Configuring View

View configurations include all kind of configurations that affects the look and feel of the Personal Browser. You can configure how the title should be formatted, the name of the zip file, the name of the root directory within the zip file (if a root directory is included), a logotype that is displayed in the top left corner, whether or not to include a Microsoft Excel workbook (in addition to the HTML document). You can also configure what table columns that will be displayed in the HTML document (and Microsoft Excel workbook) and how the values in these columns should be styled.

First, all view related configurations are kept within a View element that is located directly beneath the Configuration element.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <View>
            <!-- View configuration here -->
        </View>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.7.1. Configuring Microsoft Excel Workbook

A Microsoft Excel workbook will be included in every Personal Browser by default. However, you can choose to not include this file. To not include a workbook file in the Personal Browser you simply add the include attribute on the Workbook element with the value false.

When the Excel workbook will is included the spreadsheet will contain an outline that conforms to the business object structure. This outline enables users to expand and collapse the structure within Excel. If this outline is not wanted you can turn it off by adding the createOutline attribute to the Workbook element and set the value to false.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <View>
            <Workbook include="true" createOutline="true" />
        </View>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>
image
Figure 13. Microsoft Excel workbook example with outline

4.7.2. Configuring Logotype

It is possible to include an image that will be displayed in the top-left corner into every Personal Browser. This is accomplished by adding a Logotype element inside the View element. To specify the path to the image and its height you edit the src and height attributes (Note that the path to the image should be relative from the web applications root directory. The height of the image is specified in pixels).

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <View>
            <Logotype src="images/logotype.gif" height="50"/>
        </View>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.7.3. Configuring Document Styles

You can configure how a few parts of the HTML document will look and feel using the DocumentStyle element.

  • The headerBackgroundColor attribute defines the background color on the header.

  • The headerColor attribute defines the text color on the header.

  • The detailsBackgroundColor attribute defines the background color on the details pane.

  • The showToggleButtons attribute defines whether the buttons that allow the user to toggle between a structure view and a flat table view of the data will be shown or not (default is true).

  • The showHideButton attribute defines whether the button on the details pane that hides the same when clicked will be shown (default is true). Note that users can still hide the details pane by pressing the Backspace key on their keyboard.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <View>
            <DocumentStyle headerBackgroundColor="green"
                           headerColor="blue"
                           detailsBackgroundColor="purple"
                           showToggleButtons="false"
                           showHideButton="false" />
        </View>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.7.4. Configuring Document Title

You can configure the title of the HTML document. The title can exist of static text combined with placeholders for business objects basic properties or attribute values. The title is configured within the Title element, which you add to the View element. Within the Title element you can add five different elements that build up the title of the document.

  • The Text element should be used to define static text that will be included in the title as is

  • The Basic element defines the name of a basic property whose value will be included

  • The Attribute element defines the name of an attribute whose value will be included.

  • The CurrentUser element will be replaced by the name of the user that creates the personal browser.

  • The Date element will be replaced by the current date (when the personal browser was created).

Here is an example on how you can configure the document title. Please note that the title can only contain basic property values and attribute values from the root object that the Personal Browser is created from.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <View>
            <Title>
                <Basic>type</Basic>
                <Text>, </Text>
                <Basic>name</Basic>
                <Text> rev. </Text>
                <Basic>revision</Basic>
            </Title>
        </View>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.7.5. Configuring ZIP Archive

It is possible to configure the name of the ZIP archive that the complete Personal Browser is stored inside. You can also configure the name of a common root directory that will be included within the ZIP archive (If you configure the name of such a directory all files included within the ZIP archive will now be within this directory). The last thing you can configure about the ZIP archive is the file directory, i.e., where to place all the files that are checked out of the business objects (By default all files are placed inside data/files/OID/FORMAT).

The name of the ZIP archive and the name of the root directory are configured inside a common Zip element that is added beneath the View element. The archive name is configured inside an element called FileName, while the root directory and files directory names are configured inside the elements called RootDir and FilesDir respectively. Each of these elements may contain Text, Basic, Attribute, CurrentUser and Date elements to build the desired result. For information on how to use these elements please see 3.2.7.4.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <View>
            <Zip>
                <FileName>
                    <Basic>name</Basic>
                    <Text> rev. </Text>
                    <Basic>revision</Basic>
                </FileName>
                <RootDir>
                    <Basic>name</Basic>
                    <Text> (</Text>
                    <Attribute>Title</Attribute>
                    <Text>)</Text>
                </RootDir>
                <FilesDir>
                    <Text>docs</Text>
                </FilesDir>
            </Zip>
        </View>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

Please note that it is possible to configure the name of the ZIP archive without configuring the name of the root directory and/or the files directory, and vice versa.

4.7.6. Configuring Table Columns

This section describes how to define table columns on the downloaded HTML page and Excel spreadsheet.

image
Figure 14. Table with configured columns

The table columns are defined as child elements of the Table element, which is the immediate child of the View element. It is also possible to define the initial width in pixels of the indent column – this is the column that contains the expand/collapse buttons.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <View>
            <Table indentColumnWidth="100">
                <!-- Column definitions here -->
            </Table>
        </View>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

Add a Column element to the Table element to define a table column. The Column element supports the following attributes:

  • width – Configures the initial width (in pixels) of the column when displayed on the HTML page (columns can be resized by users).

  • typeIcon – Configures whether or not to display a type icon in the column (true/false).

  • appliesTo – Configures whether or not the data displayed in the column will come from the businessobject (default) or the relationship.

  • dataType – Configures the data type of the column. The data type will only have to be configured if the default data type (i.e., the data type of the actual attribute or basic property values displayed in the column) has to be overridden. Possible values are:

    • integer

    • real

    • timestamp

    • string

    • boolean

4.7.7. Column Expression

To define what data should be displayed in a column you insert the Expr element as a child to the Column element. The Expr element should contain one of the following elements:

  • Basic – Configures that a basic property of the business object or relationship should be displayed in the column. The name of the property is enclosed within the body of the element.

  • Attribute – Configures that an attribute of the business object or relationship should be displayed in the column. The name of the attribute is enclosed within the body of the element (Symbolical attribute names supported).

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <View>
            <Table indentColumnWidth="100">
                <Column width="80" typeIcon="true">
                    <Expr><Basic>type</Basic></Expr>
                </Column>
                <Column width="40" appliesTo="relationship" dataType="integer">
                    <Expr><Attribute>attribute_FindNumber</Attribute></Expr>
                </Column>
            </Table>
        </View>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.7.8. Column Label

The default label of the column will be the localized name of the attribute or basic property displayed in the column. The localized name will be fetched from the property files installed with the AEF.

However, if needed you can define your own column labels. This is accomplished by adding a Label element within the Column element. The body text of the Label element will be the column label displayed on the HTML page.

Moreover, you can define additional labels for other languages by adding another Label element per language. Which language the label is for is defined by the locale attribute on the additional Label elements. Note that this feature is similar to the one explained in this section.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <View>
            <Table indentColumnWidth="100">
                <Column width="80" typeIcon="true">
                    <Expr><Basic>name</Basic></Expr>
                    <Label>Name</Label>
                    <Label locale="fr">Nom</Label>
                </Column>
            </Table>
        </View>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.7.9. Column Style

Simple styling can be applied to column values displayed in the HTML page.

Define the style of a table column value by adding a Style element to the Column element. The Style element supports the following attributes:

  • underline – Configures whether or not the value should be underlined (true/false).

  • bold – Configures whether or not the value should be rendered with a bold font (true/false).

  • italic – Configures whether or not the value should be displayed in italics (true/false).

  • color – Configures the color of the displayed value. The value of this attribute can be either a hexadecimal or a decimal RGB representation, similar to that in CSS (Cascading Style Sheets). For example #FFFFFF is white in hexadecimal notation, while #FF0000 is red. The same colors when using decimal notation looks like rgb(255,255,255) for white and rgb(255,0,0) for red.

  • ifEqual – This attribute can be added to the Style element to indicate that the Style should only be applied on column that are equal to the value of this attribute.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <View>
            <Table indentColumnWidth="100">
                <Column width="80">
                    <Expr><Attribute>attribute_UnitofMeasure</Attribute></Expr>
                    <Label>U of M</Label>
                    <Style underline="true"/>
                </Column>
                <Column width="80">
                    <Expr><Basic>current</Basic></Expr>
                    <Style bold="true" underline="true" color="#f00" ifEqual="Obsolete"/>
                    <Style color="#080" ifEqual="Release"/>
                    <Style italic="true" color="#05e" ifEqual="Preliminary"/>
                    <Style italic="true" color="#0ee" ifEqual="Create"/>
                </Column>
            </Table>
        </View>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.7.10. Sorted Column

It is possible to configure which column the table will be sorted by. If the configuration doesn’t explicitly define any column to sort by the business objects will be sorted by their name. To define which column to sort the table by you add a Sorted element inside the Column element.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <View>
            <Table indentColumnWidth="100">
                <Column width=[[OLE_LINK1]]"80">
                <Sorted />
                    <Expr><Attribute>attribute_UnitofMeasure</Attribute></Expr>
                    <Label>U of M</Label>
                </Column>
            </Table>
        </View>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

When you’ve added the Sorted element like this the column will be sorted ascending. To change the direction of the sort you can add an attribute called type with the value descending.

Note that the table can only be sorted by one column.

4.7.11. JPO-generated column information

If you need to show more complex information in the table in the Personal Browser view than what an MQL select expressions can provide, then you are able to use a Java Program Object (JPO) to gather table cell content.

To configure a JPO for extracting column information, look at the following example.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <View>
            <Table indentColumnWidth="100">
                <Column width="80">
                    <JPOValueProvider program="MyProgram" method="getValue"/>
                </Column>
            </Table>
        </View>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

4.7.12. Column Access

A column can be evaluated to be hidden or not at runtime by assigning a Java Program Object (JPO) that will validate if the user currently creating the personal browser has access to the column or not.

A column is assigned a access program as in the example below:

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <View>
            <Table indentColumnWidth="100">
                <Column width="80">
                    <Access>
                        <AccessProgram>MyAccessProgram</AccessProgram>
                        <AccessFunction>checkAccess</AccessFunction>
                    </Access>
                </Column>
            </Table>
        </View>
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

The program should return an object of type "java.lang.Boolean", and if this value equals to FALSE, then the column is hidden for the created personal browser.

An example of an access program is shown below:

import matrix.db.*;
import java.util.*;

public class ${CLASSNAME} {
    public ${CLASSNAME}(Context ctx, String[] args) throws Exception {}

    public Boolean checkAccess(Context ctx, String[] args) throws Exception {
        HashMap paramMap = (HashMap) JPO.unpackArgs(args);
        Boolean hasAccess = new Boolean(true);

        /* Perform access checks here and
           possibly change the return value
           to reject access */

        return hasAccess;
    }
}

4.7.13. Defining Extraction Behavior

This section describes how to filter which data is shown for specific object and relationship types, which files to checkout, and most important which objects to include when extracting a structure.

First of all, this behavior is defined per object type (i.e., it is possible to define different behavior for different object types). You can, however, include a default configuration that is to be used for object types that don’t have an explicit configuration.

This behavior is defined inside one or more TypeConfiguration elements, one for each object type with different behavior and possibly a default. What object type a specific TypeConfiguration belongs to is defined with the name attribute on that element.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <TypeConfiguration name="type_Part">
            <!--
                This type configuration is used for all
                objects of type Part, or any type derived
                from Part unless a specific type configuration
                has been defined for the derived type.
            -->
        </TypeConfiguration>
        <TypeConfiguration>
            <!-- This type configuration is the default -->
        </TypeConfiguration>
        <!-- Possibly more configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

Note that when defining a type configuration for a specific type, that type configuration is also valid for types that are derived from that type, unless a specific type configuration has been defined for the derived type.

4.7.14. Filtering Data and Files

It is possible to define which data that should be shown on an object of a specific type, which data that should be shown on relationships connected with that object, and which files should be checked out and available in the Personal Browser.

When defining a filter, it is possible to explicitly include or exclude data and files (Data refers to basics and attributes on an object or a relationship). If no data has been explicitly included, it is assumed that all data is included. Otherwise, when the filter has been defined to include specific data, no data other than the included will be shown in the Personal Browser. For instance, if a filter has been defined to include an attribute named "Target Cost" on a specific object type, then no other attributes on objects of that type are included.

The filter is defined within the ExportFilter element inside the TypeConfiguration element.

Include

The data and files that are to be included are defined within an Include element. To define which attributes to include on a specific object type, enclose the name of the attribute inside an Attribute element and add that element to an AttributeList element inside the Include element. The syntax for including a specific basic property on an object is the same as for attributes; just replace the Attribute and AttributeList elements with Basic and BasicList respectively. The following example shows a filter, which includes the "Part Classification" and "Target Cost" attributes on objects of type "Part".

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <TypeConfiguration name="type_Part">
            <ExportFilter>
                <Include>
                    <BasicList>
                        <Basic>type</Basic>
                        <Basic>name</Basic>
                        <Basic>revision</Basic>
                        <Basic>description</Basic>
                        <Basic>current</Basic>
                        <Basic>owner</Basic>
                    </BasicList>
                    <AttributeList>
                        <Attribute>attribute_Classification</Attribute>
                        <Attribute>attribute_TargetCost</Attribute>
                    </AttributeList>
                </Include>
            </ExportFilter>
        </TypeConfiguration>
        <!-- Possibly more configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

It is also possible to define which attributes should be included for a specific relationship type. This is done by enclosing the attribute name inside an Attribute element, which is added to a RelationshipAttributeList element inside the Include element. By defining a name attribute on the RelationshipAttributeList element, it is possible to define different filter behavior for different relationship types. For instance, the following example shows a filter that will include the "Find Number" and "Quantity" attributes on relationships of type "EBOM"; in addition it will include the "Quantity" attribute on all relationships for which a specific filter hasn’t been defined.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <TypeConfiguration name="type_Part">
            <ExportFilter>
                <Include>
                    <RelationshipAttributeList name="relationship_EBOM">
                        <Attribute>attribute_FindNumber</Attribute>
                        <Attribute>attribute_Quantity</Attribute>
                    </RelationshipAttributeList>
                    <RelationshipAttributeList>
                        <Attribute>attribute_Quantity</Attribute>
                    </RelationshipAttributeList>
                </Include>
            </ExportFilter>
        </TypeConfiguration>
        <!-- Possibly more configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

To define which files to include when extracting a Personal Browser, enclose the name of the file within a File element, which is added to a FileList element. It is also possible to define that only files of a specific format should be included. Do this by enclosing the name of the format inside a Format element, which is added to a FormatList element. Note that it is possible to use the character ("*") as a wild card for file names. For instance, the following example shows a filter that will include all files whose format are "generic" and whose name ends with ".dwg".

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <TypeConfiguration name="type_CADDrawing">
            <ExportFilter>
                <Include>
                    <FormatList>
                        <Format>generic</Format>
                    </FormatList>
                    <FileList>
                        <File>*.dwg</File>
                    </FileList>
                </Include>
            </ExportFilter>
        </TypeConfiguration>
        <!-- Possibly more configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>
Exclude

Sometimes it might be more convenient to define which data or files to exclude, rather which data to include (i.e., include all data except…). For instance, if the filter doesn’t define which data to include (thereby including all data) but has been defined to exclude specific data, then all data will be included except the data that has been explicitly excluded.

To define which data or files to exclude, use the same syntax described for including data, except that you replace the Include element with an Exclude element. Note that it is possible to combine the Include and Exclude elements. If, however, any data has been defined to be included within the Include element, and the same data has been defined excluded within the Exclude element, the Exclude element will override the Include element, thus excluding the data.

The following example shows two type configurations, one for objects of type "Part", and another for objects of type "CAD Drawing". For objects of type "Part", the attributes "Part Classification" and "Target Cost" will be included. In addition, the attributes "Find Number" and "Quantity" will be included on relationships of type "EBOM", and the attribute "Quantity" will be included on all relationships other than "EBOM" that originate from objects of type "Part". For objects of type "CAD Drawing", the attribute "Model Type" will be included while all files whose name ends with either ".jt" or ".dwg" will be excluded.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <TypeConfiguration name="type_Part">
            <ExportFilter>
                <Include>
                    <AttributeList>
                        <Attribute>attribute_PartClassification</Attribute>
                        <Attribute>attribute_TargetCost</Attribute>
                    </AttributeList>
                    <RelationshipAttributeList name="EBOM">
                        <Attribute>attribute_FindNumber</Attribute>
                        <Attribute>attribute_Quantity</Attribute>
                    </RelationshipAttributeList>
                    <RelationshipAttributeList>
                        <Attribute>attribute_Quantity</Attribute>
                    </RelationshipAttributeList>
                </Include>
            </ExportFilter>
        </TypeConfiguration>
        <TypeConfiguration name="type_CADDrawing">
            <ExportFilter>
                <Include>
                    <AttributeList>
                        <Attribute>attribute_ModelType</Attribute>
                    </AttributeList>
                </Include>
                <Exclude>
                    <FileList>
                        <File>*.jt</File>
                        <File>*.dwg</File>
                    </FileList>
                </Exclude>
            </ExportFilter>
        </TypeConfiguration>
        <!-- Possibly more configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>
Locking Files

It is possible to configure that the object, which files being exported, should be locked when a personal browser is created. This is configured by adding the attribute "lockFiles" on the "ExportFilter" element. See example below:

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
    <!-- More configuration data here... -->
        <TypeConfiguration name="type_Part">
            <ExportFilter lockFiles ="true"> (1)
                ...
            </ExportFilter>
        </TypeConfiguration>
    </Configuration>
    <!-- Possibly more configuration data here... -->
</PersonalBrowserConfiguration>
1 lockFiles attribute

4.7.15. Filtering Objects and Relationships

When defining a configuration, you must define how to expand the structure from object to object, thus defining which objects are to be considered when downloading a Personal Browser.

This behavior is defined within an ExpandConfigurationList element that contains one or more ExpandConfiguration elements. Within an ExpandConfiguration element it is possible to define a variety of properties used when expanding from one object to another, these are:

  • To – Boolean value (i.e., true or false) defining whether to consider connections on the "TO" side of the object. Default value is false.

  • From – Boolean value defining whether to consider connections on the "FROM" side of the object. Default value is false.

  • TypePattern – A pattern defining which object types to consider on the "other" side of a relationship. Default value is *.

  • RelationshipPattern – A pattern defining which relationship types to consider when expanding. Default value is *.

  • ObjectWhereClause – A where clause that must be valid for connected objects. Default value is an empty string.

  • RelationshipWhereClause – A where clause that must be valid for relationships when expanding. Default value is an empty string.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <TypeConfiguration name="type_Part">
            <ExpandConfigurationList>
                <ExpandConfiguration>
                    <From>true</From>
                    <RelationshipPattern>EBOM,Part Specification</RelationshipPattern>
                </ExpandConfiguration>
            </ExpandConfigurationList>
        </TypeConfiguration>
        <!-- Possibly more configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

The example given above will expand from each object of type "Part" to other objects connected on the "FROM" side with a relationship type of either "EBOM" or "Part Specification".

Filtering Using Java Program Objects

The standard way to perform the filtering is made by defining expansion criteria as defined in this chapter. Such a definition ends up in a MQL expand business-object call. In some cases, for example when the data model is too complex, this kind of expansion is not able to be applied on all structures.

By letting a JPO perform the expansion, you can gain better control of what data you will include in the generated Personal Browser.

To configure a JPO that should perform the expansion, see the following configuration example:

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <TypeConfiguration name="type_Part">
            <ExpandConfigurationList>
                <ExpandConfiguration>
                    <JPOExpander program="MyProgram" method="myExpandMethod"/>
                </ExpandConfiguration>
            </ExpandConfigurationList>
        </TypeConfiguration>
        <!-- Possibly more configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>

When the expanded program is invoked, the arguments will contain the object id and if defined, the parameters specified inside the "ExpandConfiguration" element, such as: direction, object-where-clause, relationship-where-clause, type pattern and/or relationship pattern.

The expected return value from the expand method is a MapList, which contains a list of HashMap instances where each HashMap corresponds to a row in the table. Each HashMap should contain a business object ID and/or a relationship ID, these are stored using the id and id[connection] keys respectively.

import matrix.db.*;
import matrix.util.*;
import java.util.*;
import com.matrixone.apps.domain.util.*;

public class ${CLASSNAME} {
    public ${CLASSNAME}(Context ctx, String[] args) throws Exception {}

    public MapList getEBOM(Context ctx, String[] args) throws Exception {
        HashMap paramMap = (HashMap)JPO.unpackArgs(args);
        MapList mapList = new MapList();
        String objectId = (String) paramMap.get("objectId");
        String rel = PropertyUtil. getSchemaProperty(ctx, "relationship_EBOM");
        SelectList sl = new SelectList();
        sl.addId();
        BusinessObject bo = new BusinessObject(objectId);
        ExpansionWithSelect ews = bo.expandSelect(ctx, rel, "*", sl, sl, false,
            true, (short) 1, "", "", false);
        RelationshipWithSelectList rwsl = ews.getRelationships();
        RelationshipWithSelect rws;
        HashMap map;
        for (int i = 0; i < rwsl.size(); i++) {
            rws = (RelationshipWithSelect) rwsl.get(i);
            map = new HashMap();
            map.put("id", rws.getTargetSelectData("id"));
            map.put("id[connection]", rws.getSelectData("id"));
            mapList.add(map);
        }
        return mapList;
    }
}
Loading objects from Structure Browser (TableBean object)

You can configure that Personal Browser should load objects from a TableBean object (Structure Browser uses TableBean objects to represent a flat table or a structure) by adding the LoadFromTableBean element to the configuration. Note that if you choose to load objects with this approach the expansion mechanism described above will not apply.

If you add this element, you may optionally add the fullExpand attribute on the element to instruct Personal Browser to expand the structure fully if it isn’t already (normally Personal Browser will only include the objects that are currently visible in Structure Browser across all pages). The value of this attribute should be true.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!-- More configuration data here... -->
        <LoadFromTableBean /> (1)
        <!-- More configuration data here... -->
    </Configuration>
</PersonalBrowserConfiguration>
1 Special element

4.7.16. Include all versions of files

If you want to include all versions of files, you need to set "tvc.personalbrowser.allFileVersions" to true. This is a tvc init parameter which is by default false.

4.7.17. Rules

This section describes how to define, use and implement rules that can be used to dynamically decide which data, files or objects should be included or excluded in a configuration based on business logic implemented inside a JPO.

Note that although the concept of rules is a very powerful tool to create complex configurations, they could also cause the creation of a Personal Browser to slow down dramatically. For example, if the JPO contains huge amounts of business logic that needs to be executed for every included business object.

4.7.18. Defining a Rule

First of all, a rule is defined as a Rule element inside a Configuration element between the ValidFor and TypeConfiguration elements. Each rule has a name, a type, and an evaluation type. These are defined using attributes on the Rule element:

Attribute Description

name

Defines the name of a rule. Each rule defined inside a single configuration must have a unique name. The name of the rule is then used inside the configuration to reference the result of executing the rule.

type

Defines the type of the rule. Currently there only exist one rule type and that is "jpo". However, other rule types might be included in the future if applicable. Note that the type attribute value should also contain the name of the JPO and the name of the method that should be executed. The method on the JPO will return a boolean primitive that we can use in the configuration to decide whether to include or exclude certain information. The syntax for defining a JPO rule is:

jpo:<jpo-name>:<method-name>

eval

Defines the evaluation type of the rule, which can be either "local" or "global".

A "local" rule is executed once for every business object included by the configuration using the rule, hence it can be used to implement business logic that is dependant on the context of a certain business object.

A "global" rule will only be executed once per Personal Browser download.

The default value is "local". This attribute is optional but it is recommended to include it for readability.

The following example defines a rule with the name "myRule" that refers to the method "checkRule" on the JPO "MyJpo". The rule is executed once per business object.

<?xml version="1.0" encoding="UTF-8"?>
<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <DisplayName>EBOM with Specifications</DisplayName>
        <Description>
            Extracts the EBOM structure for the specified Part.
            Associated Part Specifications will be included.
        </Description>
        <Access>
            <!--
                This element contains information about which users will have access
                to download a Personal Browser using this configuration.
            -->
        </Access>
        <ValidFor>
            <!--
                This element contains information about which objects that this
                configuration should be available for.
            -->
        </ValidFor>
        <Rule name="myRule" type="jpo:MyJpo:checkRule" eval="local"/>
        <TypeConfiguration name="Part">
            <!--
                This element contains information about how to expand the structure
                from objects with the named type. It also contains information about
                which data that should be included or which that should be filtered.
                Note that there might be more than one TypeConfiguration element,
                each setting up different behavior for different object types. If a
                TypeConfiguration element doesn't include a name attribute, then it
                will be the default configuration for objects whose type doesn't have
                an explicit TypeConfiguration.
            -->
        </TypeConfiguration>
    </Configuration>
    <!--
        Possibly more configurations here...
    -->
</PersonalBrowserConfiguration>

4.7.19. Using a Rule

Once a rule has been defined you can use it in a configuration to include or exclude certain information based on the outcome of business logic implemented in a JPO.

Use a rule by adding an if or an unless attribute to the Basic, Attribute, Format, File or ExpandConfiguration element of your choice. The value of the attribute should be the name of the rule within curly brackets prefixed with a dollar sign (e.g., ${myRule}). Note that you cannot have both an if and an unless attribute on the same element.

Adding an if attribute to one of these elements means that the element will only apply when the rule returns true, unless means that the element will only apply when the rule returns false. For example, you can define that a certain attribute will only be included when a rule returns true, or that a certain object should not expand in a certain way when another rule returns false.

<?xml version="1.0" encoding="UTF-8"?>

<PersonalBrowserConfiguration>
    <Configuration name="defPartConf">
        <!--
            More configuration data here...
        -->
        <Rule name="myRule" type="jpo:MyJpo:checkRule" eval="local"/>
        <TypeConfiguration name="type_Part">
            <ExportFilter>
                <Include>
                    <BasicList>
                        <Basic>type</Basic>
                        <Basic>name</Basic>
                        <Basic>revision</Basic>
                        <Basic>description</Basic>
                        <Basic if="${myRule}">current</Basic>
                        <Basic if="${myRule}">owner</Basic>
                        <Basic if="${myRule}">originated</Basic>
                        <Basic if="${myRule}">modified</Basic>
                        <Basic if="${myRule}">modified</Basic>
                    </BasicList>
                    <AttributeList>
                        <Attribute>attribute_UnitofMeasure</Attribute>
                        <Attribute unless="${myRule}">attribute_TargetCost</Attribute>
                        <Attribute unless="${myRule}">attribute_EstimatedCost</Attribute>
                    </AttributeList>
                    <RelationshipAttributeList name="relationship_EBOM">
                        <Attribute>attribute_FindNumber</Attribute>
                        <Attribute>attribute_Quantity</Attribute>
                    </RelationshipAttributeList>
                </Include>
            </ExportFilter>
            <ExpandConfigurationList>
                <ExpandConfiguration if="${myRule}">
                    <From>true</From>
                    <RelationshipPattern>EBOM,Part Specification</RelationshipPattern>
                </ExpandConfiguration>
                <ExpandConfiguration unless="${myRule}">
                    <From>true</From>
                    <RelationshipPattern>EBOM</RelationshipPattern>
                </ExpandConfiguration>
            </ExpandConfigurationList>
        </TypeConfiguration>
    </Configuration>
</PersonalBrowserConfiguration>

4.7.20. Implementing a Rule

This section describes how the Personal Browser expects the JPO executing a rule to be implemented, and what arguments the JPO can expect to receive upon execution.

Arguments

The unpacked arguments sent to the JPO are an instance of java.util.Map. If the evaluation type of the rule is "global" the Map will be empty. However, if the evaluation type is "local" the Map contains the values of a few basic properties on the current business object.

Parameters to a JPO whose evaluation type is "local":

Key Name Data Type Description

OID

java.lang.String

The ID of the current business object.

TYPE

java.lang.String

The type of the current business object.

NAME

java.lang.String

The name of the current business object.

REVISION

java.lang.String

The revision of the current business object.

CURRENT

java.lang.String

The current state of the current business object.

VAULT

java.lang.String

The vault of the current business object.

POLICY

java.lang.String

The policy of the current business object.

Return Value

The Personal Browser expects the JPO to return a boolean primitive indicating whether the rule was met or not.

Template

This is a template that can be used when implementing a JPO that executes business logic on the behalf of a rule used in a Personal Browser configuration.

import java.util.Map;
import matrix.db.JPO;
import matrix.db.Context;

/**
 * This is a template that can be used when
 * implementing a JPO that executes business
 * logic on the behalf of a rule used in a
 * Personal Browser configuration.
 */

public class ${CLASSNAME} {

    /**
     * This contains the business logic that
     * should be executed for a rule. Note that
     * the name of the method is defined in the
     * configuration XML, "executeRule" is just
     * an example.
     */
    public boolean executeRule(Context ctx,
                               String[] args)
                        throws Exception {

        // These parameters are only available to
        // rules whose evaluation type is "local"
        // since global rules are executed outside
        // the context of a business object
        Map params = (Map) JPO.unpackArgs(args);
        String objectId = (String) params.get("OID");
        String type     = (String) params.get("TYPE");
        String name     = (String) params.get("NAME");
        String revision = (String) params.get("REVISION");
        String current  = (String) params.get("CURRENT");
        String vault    = (String) params.get("VAULT");
        String policy   = (String) params.get("POLICY");
        boolean success = false;

        // TODO: Implement rule and return whether
        //       the rule was successful or not

        return success;
    }

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