The Service Station column is a series of articles about providing professional services around EMC software products. Featured guest columnists express their thoughts about a wide range of topics relating to designing, developing, and delivering solutions. In this issue, Laurence Hart talks about upgrading Documentum installatons.

Overview

With the introduction of Documentum 6 (D6), many people are starting to think about making that leap forward. Some have been through this process before with Documentum. Others have been through this multiple times over the last decade or two. Having helped a variety of organizations over the years plan and execute their upgrades and migrations, I thought I would write about some tried and true approaches to upgrading Documentum.

The Example System

This article uses an upgrade from 5.2.5 sp4 to D6 running on Windows 2000 Server using SQL Server 2000 as an example. The Web Application server is Tomcat. All components are on dedicated servers. This system is core Documentum.

Define the Target Environment

Whenever beginning down the upgrade path, it is critical to gain a clear understanding of the target environment. This begins with studying the Release Notes. There are two very important items that need to be gleaned from the notes:

1. What are the supported environments for the new version?
2. What are the components of a typical system for the new version?

When looking at the notes for D6, there are some quick things that pop out. The first is that starting with 5.3 the FAST Search Engine was added and requires its own server. The second is that none of the key third party components (operating system, database, or application server) in use is supported in D6. This means that the upgrade of the environment is going to be part of the overall process.

Learn the Target Environment

Before getting too deep into writing the plan, it is important to learn more about the target environment. This allows more accurate estimates to be made regarding the amount of effort involved at each step.

There are two ways to do this. One is to hire a consultant who has done this before. This is the quicker and decidedly less risky of the two approaches (assuming that you hire someone who is knowledgeable and experienced). The weakness with this approach is that once the upgrade is complete, the amount of retained institutional knowledge for the new platform is not as great as it would be otherwise. The consultant takes a lot of knowledge with them, though a fair amount of knowledge transfer should take place.

Acquiring the knowledge internally significantly adds to the learning phase of the upgrade process. However, it does leave the organization better prepared for life after the upgrade. Gaining this knowledge is a fairly straightforward process.

• Setup a VMWare server. It is free, easy to get, and allows an organization to tinker to their hearts’ content.
• Create the target environment in clean VMWare images. It is important to see how all of the pieces work normally and how a clean installation process transpires.
• Customize and configure the environment. The key here is to get a sense of how difficult it may be to implement existing functionality in the upgraded system. Installing any existing DocApps is a nice way to do a sanity check.

Plan the Move

There are several things to take into account. The first is determining the path of least resistance from the current to the target environment. In the example, there are several steps that need to be performed to reach the target environment. Here is one potential approach.

This should not be done all in one go, but in stages, with tests made at the completion of each upgraded component to test the validity of the upgrade. There are several factors to consider in this example.

• When to add FAST? Verity is gone in 5.3. This multi-step process can be performed over the weekend in Production. If full-text search is not a primary activity, then the upgrade process can be stretched over weeks to reduce risk.
• How big? It is important to revisit the latest Sizing Spreadsheet. This will show where hardware upgrades may also be necessary. These hardware upgrades should be timed to coincide with the upgrade of the software on the servers. This spreadsheet can usually be acquired from Powerlink or from your EMC Account Representative. At the very least, the size of the Index Server needs to be determined and the Content Server requires more resources in D6 than in previous versions.
• How many web customizations? This is a big factor here, and typically the major hurdle for most upgrades. The more that you have invested in customizing Webtop, the less likely you want to upgrade frequently. D6 makes customizing easier, but how easy requires in-depth knowledge of the new Webtop environment.
  
  Sometimes it is possible to use an older client with a newer Content Server, such as in the example being used here. This is a very useful approach that allows for focused efforts on only changing portions of the system at a time. A 5.3 client can be used against a D6 repository and the upgrade of 5.2.5 Webtop customizations to 5.3 is typically straightforward if the goal is to get them to work until they can be redone in D6.
• Custom Workflows and Lifecycles? If you wrote code automating steps and performing processes in the background, those will need to be thoroughly tested.

Upgrade Three Times

This sounds painful, but it is more than necessary. It also isn’t as bad as it sounds. The three upgrades are Development, Test, and Production. Each upgrade provides different insight into the overall process. If all three environments don’t exist, then creating them is the first step of the upgrade process.

• Development: This process is all about seeing what works and what doesn’t. Based on the complexity of the customizations, the amount of work can last anywhere from two weeks to six months. The older the customizations, the longer it takes as the institutional knowledge may not be readily accessible. Nothing speeds an upgrade along like having the original developer around to update the code.
  
  This stage is also used to refine the initial upgrade plan to handle details that need to be more clearly spelled out or that were overlooked in the creation of the plan.
• Test: This is critical as it insures that the upgrade plan is accurate and that the updated customizations and configurations can be deployed correctly. If this process does not go smoothly, roll back and try again. The goal here is to get it right in one go. Using the data collected here, the required maintenance window for Production can be readily determined.
• Production: At this point, everything should be smooth as silk. Schedule the system outage and proceed. While the initial upgrade of the Development components may have taken 2 weeks plus development time, this should take place in a single day or less.

It is important to perform complete backups before upgrading each of the three, or more, environments. It is also recommended to allow at least two weeks between each phase, regardless of how simple it may seem. This allows time for hidden issues to bubble to the surface.

Other Factors to Consider

There are several factors that further complicate the process and increase the need for planning and expertise.

• Multiple Environments: This article assumes one Documentum environment. If there are multiple environments in an organization, a coordination plan should be derived that will map how each environment will be upgraded in turn, if at all. The upgrade process can be used to consolidate some of the environments into a smaller, more manageable, number.
• Integrations: When integrated into other systems, there can be a cascade of dependencies. One common one that occurs is with the Java Runtime Environment. Each version of Documentum is certified against specific versions of Java. When writing integrations using the DFC, it is important to make sure that the Java version supported by the DFC is the same version as that supported by the third party application.
• High Availability: This was not taken into account in this article. It is important to note that during this process, the changes in the Documentum distributed architecture should be taken into account to provide the most effective, and supported, architectural design. Refer to the latest Distributed Configuration Guide to see explanations and examples of the options available for use.
• Migration versus Upgrade: In examples even less drastic than the one outlined in this article, many organizations choose to built clean machines and start over. Complete migrations are time-consuming, risky, and typically require the use of a third party tool to be cost effective. In this example, building a new Windows 2003 Server, installing Documentum 5.2.5, and migrating the existing system over would be a reasonable, and relatively simple, median. In a similar vein, database servers and application servers are easier to migrate. As a general rule with database changes, always include your resident DBA to catch those things that the vendors don’t make obvious.

About the author

Laurence Hart leads the Enterprise Content Management (ECM) Solution Group for Washington Consulting, Inc. based out of Washington, DC. He's been consulting within the ECM space for over 10 years and has worked with Documentum since 2000, including a brief run as the Product Manager for AnnoDoc

In his Word of Pie blog, Laurence ponders about Life, the Universe, and Documentum. The blog is meant to be a place to learn and share thoughts about the Documentum product line, Enterprise Content Management, and the world around them.

About the Service Station

The Service Station column looks at developing EMC based solutions from the perspective of professional services organizations. If you (and your company or department) provide such services and are interested in being a guest columnist, please send your contact information, a brief bio and topic outline to EDN_Submission AT EMC.com.

Click here for an index of all "Service Station" columns.

You can discuss "Service Station" articles on the EDN Forums by clicking here.