Product: Livelink ECM Enterprise Server

Version: 9.5.0.1, 9.6, 9.7.0, 9.7.1

Task/Topic: Upgrade
Audience: Administrator
Platform: All
Document ID: 500050
Updated: January 26, 2009

Best Practices

Upgrading Enterprise Server Categories

Gordon Maxwell

Document Title

Upgrading Enterprise Server Categories

Best Practices

Contents
Upgrading Enterprise Server Categories ................................................................. 1
Best Practices for Category Upgrading .................................................................. 2
Performance..................................................................................................... 2
Successful Completion .................................................................................... 2
Reporting and Verification ................................................................................ 2
Related Considerations.................................................................................... 3
Best Practices for Upgrading Categories in Detail.................................................. 4
Performance..................................................................................................... 4
Set the Categories Upgrade Batch Processing Refresh Rate .................. 4
Use a Dedicated Enterprise Server Instance for the Category
Upgrade .............................................................................................. 5
Set SingleSelectCall=TRUE in the [Attributes] Section
of the opentext.ini File............................................................... 5
Apply the Category Upgrade First at the Folder Level, then
throughout Enterprise Server .............................................................. 6
Set UpgradeSkipRefCounting=TRUE in the [Attributes]
Section of the opentext.ini File .................................................... 7
Successful Completion .................................................................................... 7
Perform the Category Upgrade as a User That Has Permissions
to All of the Items Being Upgraded ..................................................... 7
Provide a Default Choice for Required Attributes of a Category
Being Upgraded .................................................................................. 8
Keep the Browser Window Open Throughout the Entire Category
Upgrade .............................................................................................. 8
Reporting and Verification ................................................................................ 8
Obtain Information on the Categories and Attributes in your
Enterprise Server Deployment Using attributes.dump ....................... 8
Create a LiveReport to Tell You Which Items Were Skipped
During the Category Upgrade. ............................................................ 9
Related Considerations.................................................................................. 10
Set Modified Date Triggers So the Category Upgrade Does Not
Change Modified Dates. ................................................................... 10

Champion Toolkit Document

www.opentext.com

Document Title

Upgrading Enterprise Server Categories

Best Practices

Upgrading Enterprise Server Categories

In Livelink ECM Enterprise Server, A category is a collection of attributes that
enables you to classify, group, or search for items defined by that set of attributes.
You define a category by choosing the types of attributes it contains, their sequence
and layout, and default and valid values for each one. Any time you modify a
category, Enterprise Server creates a new version of the category. Existing items
continue to use older versions of the category, but when you apply the category to
new items, they receive the most recent version. This means you can change the
attributes in a category at any time without invalidating the attribute data of existing
items.
On occasion, however, you may want to apply a new category version to items that
already have the category, so that existing items reflect the new or modified
attributes. Applying the new version of a category to existing items that already have
the category is called upgrading the items, or performing a category upgrade.
Upgrading an item configures the item to use the latest version of a category, but
does not change any attribute values it already has.
In a large deployment of Enterprise Server, thousands or even millions of items may
have a category applied to them. Upgrading such a large number of items is a
resource-intensive, time-consuming activity that requires planning and testing.
The best practices described in this document can help your category upgrade
perform optimally and complete without error. It is not necessary to use every one of
these practices. Review this document and choose the ones that are suitable for you
and your Enterprise Server environment.
What if what you want to do is update attribute values?
Although a category upgrade can apply a default value to an
attribute added to a category, a category upgrade is not ordinarily
the best way to:

Change attribute values already applied to existing items

Apply a number of different values to a newly added

category attribute

If your requirement is one of the above, you should explore other

methods, such as Object Importer, custom programming, or an
Open Text Global Services engagement.

Champion Toolkit Document

www.opentext.com

Document Title

Upgrading Enterprise Server Categories

Best Practices

Best Practices for Category Upgrading

The best practices described in this document are grouped under four headings:
1. Performance
2. Successful Completion
3. Reporting and Verification
4. Related Considerations
Each practice listed is described in detail later in this document.

Performance
Instituting some or all of the following best practices can help your category upgrade
complete as quickly as possible:

Set the Categories Upgrade Batch Processing Refresh Rate to a number of

items higher than the default of five.

Perform the category upgrade on a dedicated Enterprise Server instance.

Set SingleSelectCall=TRUE in the [Attributes] section of the

opentext.ini file.

Set UpgradeSkipRefCounting=TRUE in the [Attributes] section of the

opentext.ini file.

Apply the category upgrade first at the folder level, then throughout Enterprise
Server.

Successful Completion
These practices prevent errors that may be encountered during a category upgrade.

Perform the category upgrade as a user that has permissions to all of the items.

Provide a default choice for any required attributes added to a category.

Keep the browser window open throughout the entire category upgrade.

Reporting and Verification

These practices can help you plan your category upgrade, and verify that it
completes as expected:

Use the func=attributes.dump URL extension to obtain information on the

categories and attributes in use in your Enterprise Server deployment.

Create a LiveReport on items skipped during the upgrade.

Champion Toolkit Document

www.opentext.com

Document Title

Upgrading Enterprise Server Categories

Best Practices

Related Considerations
Other considerations:

Set Modified Date Triggers so Enterprise Server does not change the modified
date of upgraded items.

Champion Toolkit Document

www.opentext.com

Document Title

Upgrading Enterprise Server Categories

Best Practices

Best Practices for Upgrading Categories in

Detail
Performance
Set the Categories Upgrade Batch Processing Refresh Rate
The Categories Upgrade Batch Processing Refresh Rate determines the number of
items that are upgraded at one time. After the set number of items is upgraded, the
browser window is updated, the new totals appear, and the category proceeds to
process the next batch of items. Configuring this setting optimally can greatly improve
category upgrade performance.
By default, this parameter is set to five. Raising it to 25, 50 or even 100 has resulted
in much faster upgrade times in actual Enterprise Server deployments, but you
should be careful not to set the number so high that Web server timeouts occur. If the
category upgrade does time out, you will have to restart it. You should also be aware
that this setting is equal to the number of rows in the database that are locked by
successive upgrade transactions. This may not be a concern if you are confident that
you can accomplish your category upgrade during off hours, such as over a long
weekend. Otherwise, be mindful that the higher the number is set, the greater the
chances are of database contention and deadlock situations.
It is wise to test various values for this setting in a test environment, but since test
environments are rarely accurate reflections of the demand conditions in a production
environment, be prepared to scale down whatever value is successful in your test
environment.
To set the Categories Upgrade Batch Processing Refresh Rate in Enterprise Server
9.6 and later, perform the following steps:
1. Log on as an administrator, and open the Enterprise Server Administration page
using the ?func=admin.index URL extension.
2. In the Server Configuration section, click Administer Server Parameters.
3. Under Categories Upgrade Batch Processing, enter a positive integer in the
Refresh Rate box.
In Enterprise Server 9.6 and 9.7.0, the Categories Upgrade Batch
Processing setting is stored in the opentext.ini file. Restart the
Livelink services after editing this setting.
In Enterprise Server 9.7.1 and later, this setting is stored in the
database. A restart is not required.

To set the Categories Upgrade Batch Processing Refresh Rate in Enterprise Server
9.5 SP1, perform the following steps:
1. Stop the Livelink services.

Champion Toolkit Document

www.opentext.com

Document Title

Upgrading Enterprise Server Categories

Best Practices

2. Modify your opentext.ini file:

a. Open your opentext.ini file in a text editor.
b. In the [options] section, add the parameter
categoryNumToUpgrade=X. Replace X with a positive integer.
c.

Save and close the opentext.ini file.

3. Restart the Livelink services.

Use a Dedicated Enterprise Server Instance for the Category Upgrade
A category upgrade can be a long-running operation. Category upgrades that last
days or even weeks are not unheard of. The category upgrade consumes an
Enterprise Server thread until it is finished. Under ideal circumstances, it should
continue uninterrupted until it completes. For all of these reasons, you should
consider running it on a computer or Enterprise Server instance temporarily
dedicated to the task.
In a clustered Enterprise Server installation, consider running the category upgrade
on a front-end instance of Enterprise Server that is not accessible through your load
balancer. If you already have such an Enterprise Server instance that is dedicated to
a specific task (for example, a Workflow Agent server), this may be a suitable
computer, provided of course it is not already running at a high degree of CPU
utilization.
Set SingleSelectCall=TRUE in the [Attributes] Section of the
opentext.ini File
If a category upgrade fails to complete because of a network failure, power failure or
simply because the category upgrade browser window was closed, it can be
restarted. But when you restart it, it does not simply pick up where it left off. When
restarted, the category upgrade browser window shows the same number of items
remaining to be upgraded (as when the category upgrade stopped), but a significant
amount of time may elapse before you see this number start to decrease again.
During this time, the category upgrade process iterates through the entire list of
upgradeable items beginning from the start, including the items that have already
been converted, and evaluates whether they need to be upgraded.
Setting SingleSelectCall=TRUE in the [Attributes] section of the
opentext.ini file can improve this situation by directing Enterprise Server to select
only those items that have not already been upgraded, before it starts iterating
through the list. It can be particularly valuable in the following situations:
1. You are restarting a category upgrade that previously failed to complete.
In this case, Enterprise Server selects the items that require upgrading prior to
starting the upgrade, rather than finding all the items that have the category
applied, and evaluating whether the item requires upgrading.
2. You are selecting Upgrade Items from the modified categorys Functions menu
after first performing a category upgrade at the folder level.
As in the first situation, this means that a number of items have already been
upgraded, so using SingleSelectCall=TRUE may make for more efficient
processing.

Champion Toolkit Document

www.opentext.com

Document Title

Upgrading Enterprise Server Categories

Best Practices

To set SingleSelectCall=TRUE in Enterprise Server 9.5 SP1, 9.6, 9.7, and 9.7.1,
perform the following steps:
3. Stop the Livelink services.
4. Modify your opentext.ini file
a. Open your opentext.ini file in a text editor.
b. In the [Attributes] section, add the parameter
SingleSelectCall=TRUE.
c.

Save and close the opentext.ini file.

3. Restart the Livelink services.

Apply the Category Upgrade First at the Folder Level, then throughout Enterprise
Server
In many Enterprise Server deployments, categories are applied principally to items
stored in specific folders. Often the category is applied at the folder level, which
causes items added to the folder to receive the category and any preset attribute
values by default. (If there are required attributes without default values, users are
prompted to specify them.) As an administrator, you can take advantage of this to
upgrade
items
more
efficiently,
especially
if
you
enable
the
SingleSelectCall=TRUE parameter in your opentext.ini file.
To upgrade items in folders that have a category applied, perform the following steps:
1. From the Functions menu of the folder, click Properties, and then click
Categories.
2. On the Folder Categories Properties page, the modified category appears with an
Upgradable icon , indicating that a newer version of the category is available.
When the upgradeable icon is present, an Upgrade button appears alongside the
other buttons that are typically available on the Categories Properties page. Click
Upgrade.
4. Click Apply.
5. Click the Apply to Sub-Items icon
opens.

. The Apply Categories to Sub-Items page

6. From this page, you may Add, Upgrade, Add/Upgrade, and Remove categories
from folder subitems. (You also have the options to Add Version and Remove
Categories. Refer to the Enterprise Server Help for the meanings of each of these
operations.) Click Upgrade to perform the operation that is equivalent to selecting
Upgrade Items from a categorys Functions menu. (Selecting Add Version enables
you to easily undo changes, if necessary.)
Repeat steps 1 to 6 for as many folders as you wish.
7. To upgrade any items not located in the folders upgraded in steps 1 to 6, browse
to the category and, from its Functions menu, click Upgrade Items.

Champion Toolkit Document

www.opentext.com

Document Title

Upgrading Enterprise Server Categories

Best Practices

Set UpgradeSkipRefCounting=TRUE in the [Attributes] Section of the

opentext.ini File
After you click Upgrade Items on a categorys Functions menu, Enterprise Server
opens the Upgrade Items for: [CategoryName] Category page. This page shows the
Number of Items to be upgraded, and has an Add Version check box. Clicking
Submit on this page causes an additional window to open, which displays the status
of your category upgrade.
If you add the UpgradeSkipRefCounting=TRUE parameter to the [Attributes]
section of your opentext.ini file:

The Upgrade Items for: [CategoryName] Category page does not contain a
Number of Items field at all.

The status page does not display the actual number of items to be updated.
(instead -1 appears as the Number of Items), and the Upgraded field displays
0 (0%) throughout the category upgrade.

Figure 1
Omitting the count of the
number of items upgraded.

In versions of Enterprise Server earlier than Enterprise Server 9.5, this parameter
was occasionally enabled to speed processing, but in Enterprise Server 9.5 and later,
the use of this parameter does not deliver significant performance benefits. Open
Text does not recommend its use.

Successful Completion
Perform the Category Upgrade as a User That Has Permissions to All of the Items
Being Upgraded
In most Enterprise Server environments, only users with the system administration
privilege can create and edit categories. However, in some environments, regular
users are given the Category object privilege and are able to create categories. To
upgrade an Enterprise Server item, a regular user requires at least the Edit Attributes
permission. If a user with the Category object privilege selects Upgrade Items from

Champion Toolkit Document

www.opentext.com

Document Title

Upgrading Enterprise Server Categories

Best Practices

the categorys Functions menu, only those items to which that user has sufficient
permissions are upgraded.
To ensure that all applicable items are upgraded, the upgrade should be performed
by a user with the System Administration privilege. If an incomplete upgrade has
occurred because it was initiated by a user with insufficient permissions, you can
upgrade the remaining items by restarting the upgrade logged on as a user with
System Administration privileges.
Provide a Default Choice for Required Attributes of a Category Being Upgraded
When you add a required attribute to a category, you need to specify a default
attribute value, or your category upgrade will not complete as expected. In such
cases, no error message appears, but at the conclusion of the operation, the number
of items that is skipped by the category upgrade is close to or equal to the total
number of items to be upgraded.
If this happens in your environment, you can remedy the situation by editing the
category another time to provide a default value for the required item, and performing
the upgrade a second time.
Keep the Browser Window Open Throughout the Entire Category Upgrade
Unlike many administrative procedures performed in Enterprise Server, a category
upgrade will not complete if the browser window does not remain open for the
duration of the operation. If the browser window is closed inadvertently, or by some
external event like a power outage on the client computer, you can restart the
category upgrade.
If you need to restart an incomplete category upgrade, setting the
SingleSelectCall=TRUE parameter in your opentext.ini file can make the
process more efficient.

Reporting and Verification

Obtain Information on the Categories and Attributes in your Enterprise Server
Deployment Using attributes.dump
An Enterprise Server administrator can obtain useful information in convenient
tabular form using the ?func=attributes.dump URL extension. This information
can be useful for creating LiveReports and Search templates that use Enterprise
Server attributes. For an example of a LiveReport that uses such information see the
following section Create a LiveReport on Items Skipped During the Category
Upgrade
Information generated using attributes.dump has the following appearance:

Champion Toolkit Document

www.opentext.com

Document Title

Upgrading Enterprise Server Categories

Best Practices

Figure 2
attributes.dump output

Create a LiveReport to Tell You Which Items Were Skipped During the Category
Upgrade.
The following LiveReport queries the Livelink database for items with a category
version number that is lower than the current category version. After a category
upgrade, the number of items returned by this query should be close to or equal to
the number of items skipped during the category upgrade.
Replace [DefID of the modified category] with the DefID of the category in question,
or create a user prompt that requests the categorys DefID.
SELECT DISTINCT Name, DataID, DefID, DefVerN FROM LLAttrData,
DTree
WHERE LLAttrData.DefID=[DefID of the modified category]
AND llAttrdata.DefVerN<(SELECT VersionNum FROM DTree WHERE
DataID=[DefID of the modified category])
AND DTree.VersionNum= LLAttrData.VerNum
AND DTree.DataID= LLAttrData.ID
ORDER BY NAME

Champion Toolkit Document

www.opentext.com

Document Title

Upgrading Enterprise Server Categories

Best Practices

NOTE: As with any Online Transaction Processing application,

using Enterprise Server to generate reports containing large
amounts of data adversely affects performance. Reports such as
the one above should be run in a test environment or generated
from a copy of the Livelink database.
For more information on this subject, see Application Note Livelink ECM Enterprise Server LiveReports and Customer
Support Explained.

Related Considerations
Set Modified Date Triggers So the Category Upgrade Does Not Change Modified
Dates.
Many Enterprise Server administrators prefer that only modifications of item content
(not metadata) result in an items Modified Date being updated. As an administrator,
you can prevent metadata updates, including category upgrades, from changing an
items Modified Date by administering Enterprise Servers Modified Date triggers.
Bear in mind, however, that enabling or disabling this setting affects items throughout
Enterprise Server. Typically, the decision to set these triggers one way or the other is
made on the basis of general policy, and not for a specific event, such as a category
upgrade.
By default, the Modified Date Triggers are set so that category values and attribute
modification events do not update an items modified date.
To administer Modified Date triggers, click Administer Modified Date Triggers in the
System Administration section of the Livelink Administration page.

Champion Toolkit Document

www.opentext.com

10

Document Title

Upgrading Enterprise Server Categories

Best Practices

Sales

Americas

www.opentext.com

United States

Germany

United Kingdom

Australia

info@opentext.com

100 Tri-State Intl Parkway

Lincolnshire, IL
USA 60069
Phone: 847-267-9330
Fax: 847-267-9332

Technopark 2
Werner-von-Siemens-Ring 20
D-85630 Grasbrunn
Germany
Phone: +49 89 4629 0
Fax: +49 89 4629 1199

Grosvenor House
Horseshoe Crescent
Beaconsfield, Buckinghamshire
United Kingdom HP9 1LJ
Phone: +44 1494 679700
Fax: +44 1494 679707

Level 23
100 Miller St.
North Sydney
NSW 2060
Australia
Phone: +61-2-9026-3400
Fax: +61-2-9026-3455

North America Sales

1-800-499-6544

International Sales
+800-4996-5440

Europe

Asia/Pacific

If you are an Open Text partner or customer, visit online.opentext.com for more information about this and other Open Text
solutions.
Open Text is a publicly traded company on the NASDAQ (OTEX) and the TSX (OTC).
Copyright 2008 by Open Text Corporation. Open Text, Livelink, Livelink ECM, and Great Minds Working Together are trademarks or registered trademarks of Open Text Corporation. All other trademarks or
registered trademarks are the property of their respective owners. All rights reserved.

www.opentext.com

11