Documentum Desktop Client Development Best Practices and Customization Migration Guide

Documentum Proprietary

Desktop Client Development Best Practices and Customization Migration Guide

TABLE OF CONTENTS

1 2

OVERVIEW ............................................................................................................................................. 4 BEST PRACTICES DURING DEVELOPMENT...................................................................................... 4 2.1 SIMPLIFYING DEVELOPMENT ................................................................................................................ 4 2.1.1 Use Desktop Client provided functionality when available....................................................... 4 2.1.2 Use DFC instead of DMCL API ............................................................................................... 5 2.2 BUILDING A STABLE PRODUCT ............................................................................................................. 5 2.2.1 Choose the Right Language for Components ......................................................................... 5 2.2.2 Use Option Explicit in Visual Basic Components..................................................................... 6 2.2.3 Make use of error handlers...................................................................................................... 6 2.2.4 Correctly handle DFC session locking..................................................................................... 7 2.2.5 Ensure that query collections are closed ................................................................................. 7 2.3 PREPARING FOR DEPLOYMENT ............................................................................................................ 8 2.3.1 Maintain binary compatibility when using Visual Basic ............................................................ 8 2.3.2 Increment the file version when releasing a new version ........................................................ 9 2.4 MAKING UPGRADING EASIER ............................................................................................................. 13 2.4.1 Dont reformat code ............................................................................................................... 13 2.4.2 Dont rename variables.......................................................................................................... 13 2.4.3 Dont rename files.................................................................................................................. 13 2.4.4 Use custom code stubs ......................................................................................................... 13 2.4.5 Comment code instead of deleting ........................................................................................ 14 2.4.6 Isolate code changes............................................................................................................. 14 2.4.7 Distinctively comment code changes..................................................................................... 14 2.5 WRITING FASTER CODE ..................................................................................................................... 15 2.5.1 Use explicit types................................................................................................................... 15 2.5.2 Use queries instead of fetches .............................................................................................. 15 2.5.3 Make use of provided caches for Data Dictionary information............................................... 16

MANAGING DESKTOP CLIENT UPGRADES ..................................................................................... 16 3.1 MIGRATE THEN UPDATE ..................................................................................................................... 16 3.2 UNDERSTAND CUSTOM CODE CHANGES .............................................................................................. 16 3.3 UNDERSTAND DESKTOP CLIENT CHANGES .......................................................................................... 16 3.3.1 COM interface changes......................................................................................................... 16 3.4 CONCENTRATE ON PERTINENT FILES ................................................................................................... 17 3.4.1 Source code control............................................................................................................... 17 3.4.2 New files within Desktop Client source.................................................................................. 17 3.4.3 Custom only files ................................................................................................................... 17 3.4.4 Variable renaming ................................................................................................................. 17 3.5 MAKE USE OF DIFF AND MERGE TOOLS ................................................................................................ 17 3.5.1 Use analogous code hierarchies ........................................................................................... 18 3.5.2 Diff then merge ...................................................................................................................... 18 3.6 REWRITE WHEN NECESSARY .............................................................................................................. 18

APPENDIX A: DIFF AND MERGE TOOLS ......................................................................................... 19 4.1 4.2 4.3 4.4 W INDIFF ......................................................................................................................................... 19 W INMERGE ..................................................................................................................................... 19 VISUAL MERGE ................................................................................................................................ 19 ARAXIS MERGE ................................................................................................................................ 19

APPENDIX B: DESKTOP CLIENT 4.3 COMPONENT SOURCE CODE CHANGE SUMMARY ........ 20

Documentum Proprietary

Desktop Client Development Best Practices and Customization Migration Guide

TABLE OF FIGURES Figure 1 Visual Basic error-handling example ......................................................................................... 6 Figure 2 Visual C++ error-handling example ........................................................................................... 6 Figure 3 DMCL trace showing Save API call made without locking the session................................ 7 Figure 4 WSServer collection object error................................................................................................ 7 Figure 5 Collection closing in try/catch example ..................................................................................... 8 Figure 6 Component tab in Visual Basic project property dialog box................................................... 9 Figure 7 Make tab in Visual Basic project property dialog box ........................................................... 10 Figure 8 File version shown in the Visual C++ Resource Editor......................................................... 11 Figure 9 VS_VERSION_INFO in text mode........................................................................................... 12 Figure 10 Custom Code Stubs................................................................................................................. 14 Figure 11 Comment code block example ............................................................................................... 14 Figure 12 Implicit versus Explicit Type Declarations ............................................................................ 15 Figure 13 Code sample with GetObject.................................................................................................. 15 Figure 14 Code fragment showing query/fetch performance problem............................................... 15

Documentum Proprietary

Desktop Client Development Best Practices and Customization Migration Guide

1 Overview
Developing software on any platform requires knowledge of the platform and becomes easier with experience. The purpose of this document is to share the knowledge and experience gained by the Desktop Client development team to allow Documentum customers to more readily, and more easily develop applications using the Desktop Client. This document takes the form of best practices for development with Desktop Client. It also covers the migration of customizations to new versions of the Desktop Client. This document assumes that the reader is already familiar with the Desktop Client development platform and does not cover any aspects of development other than in the context of specific best practices. Readers unfamiliar with the Desktop Client development platform should first review Documentum's Developer Website (http://developer.documentum.com/) before reading this document. Of particular interest is the Developing Documentum Desktop Client Components design specification. This document is best used in conjunction with the Developing Documentum Desktop Client 1 Component manual and the Customizing Documentum Desktop Client manual.

2 Best Practices During Development

Its easier to write good code from the start rather than to try and fix the code after it has been put into production. This section is intended to provide programming tips specific to the Desktop Client development environment that will help avoid errors, especially the types of errors that are difficult to reproduce or debug. This section covers best practices for the design and development stage for a custom solution.

2.1 Simplifying Development

Dont write more code than necessary is probably a good rule to follow since more code written typically means more code that needs to be debugged or maintained. This section outlines best practices that simplify development of a custom solution.

2.1.1 Use Desktop Client provided functionality when available

The Desktop Client includes a rich set of services out of the box that makes developing a desktop-based application easier. Whenever available, these services should be used rather than developing a custom service since they are developed, maintained, and supported by Documentum. By using Desktop Client services your custom functionality will integrate more seamlessly with the Desktop Client and your effort can be focused on custom application or business logic rather than duplicating existing functionality. Although specific Desktop Client services are called out in this section, the services mentioned do not constitute the entire list of services available for use in your custom solution.

2.1.1.1 Component Dispatcher

Since all components within the Desktop Client implement the IDcComponent interface, it may be tempting to call a particular component directly using the interface methods rather than making use of the Component Dispatcher (DcCmpDsp.dll). This direct use of the IDcComponent interface is strongly discouraged since in calling a specific component directly, business logic based on an objects type or document lifecycle state may be bypassed. Additionally, since it takes only one function call to invoke a component via the Component Dispatcher rather than the
1

A pre-release version of this document was used as the basis for some of the text in the Customizing Documentum Desktop Client manual.

Page 4 of 35

Desktop Client Development Best Practices and Customization Migration Guide three calls to invoke a component through the IDcComponent interface, its actually easier to use the Component Dispatcher for component invocation.

2.1.1.2 Login Manager

After a DFC session has been retrieved using the Login Manager (DcLoginMgr.dll) and the session is no longer needed by custom code, it may seem easier to directly disconnect the DFC session rather than requesting the Login Manager to disconnect the session. Directly disconnecting a DFC session is strongly discouraged since the session may be in use by other areas of the application. Using the Login Manager consistently allows DFC sessions to be managed throughout the application.

2.1.1.3 Registry Utility

Although registry manipulation functions are included in the Win32 API, Documentum provides a registry service via the IDcRegistryKey interface whose implementation resides in the Utility Manager (DcUtilMgr.dll). While there is no requirement that the registry service be used for actual registry manipulation, its important to note that the UserHiveHkey property supported by the IDcRegistryKey interface returns the correct registry hive where information about checked out and local files information can be found. Since the location varies based on OS as well as Desktop Client version, the service should be used instead of hard coding a value such as HKEY_LOCAL_MACHINE into custom code.

2.1.2 Use DFC instead of DMCL API

While the Desktop Client provides a large set of services, much of the custom application logic that is needed will be written at a lower layer. Rather that using the raw DMCL API, its suggested that eContent Server access be made through DFC. Because DFC is an objectoriented wrapper around the DMCL API, it provides all the same functionality and is easier to read and understand. Additionally, DFC provides additional functionality and logic on top of DMCL including attribute validation, virtual document operations and XML content manipulation.

2.2 Building a Stable Product

This section describes some best practices that will help ensure that customized code is stable.

2.2.1 Choose the Right Language for Components

Desktop Client components and services are implemented as COM objects. Therefore, Desktop Client custom components can be implemented in any language that supports COM. Because Visual Basic lends itself to rapid development and easily maintainable code, the Desktop Client distributable source code is implemented in Visual Basic 6.0. Many customers choose to implement custom components in Visual Basic for the same reason. Some customers choose to implement custom components in C++, often because of a higher degree of programming power and flexibility that C++ offers. Either language is fine but when implementing components in C++ programmers need to remember that they have a higher degree of responsibility for insuring stability. Developers should be aware that components running in the Explorer Integration are running in a multi-threaded environment. Thread synchronization and the use of data protection techniques such as semaphores, mutexes, and critical sections may be required in C++ components. Failure to synchronize data access by multiple threads can lead to data corruption and crashes. You should also be familiar with COM threading models and their characteristics. Using the singlethreaded apartment model eliminates the requirement for thread synchronization but introduces a potential for deadlocks. Understanding the threading model will help you avoid such problems.

Page 5 of 35

Desktop Client Development Best Practices and Customization Migration Guide Additionally, properly maintaining the lifetime of COM objects in C++ projects is required to prevent memory leaks and crashes. You should be very familiar with the rules for COM reference counting. Visual Basic hides much of the nuts and bolts of COM and multi-threaded programming. It may be a better choice if you want to concentrate on application and business logic and presentation for your custom solution.

2.2.2 Use Option Explicit in Visual Basic Components

When writing Visual Basic code, make sure to include a line at the top of each source file that says Option Explicit. This prevents coding errors in Visual Basic that are due to the accidental mistyping of variable names.

2.2.3 Make use of error handlers

Error handlers should be used in custom code. Having error handlers around custom code allows errors to be more easily isolated as well as prevent the errors from propagating. Unhandled errors can cause minor problems such as, unintelligible error messages being presented to the user, as well as more serious problems, such as Explorer windows suddenly disappearing. In your error handlers, remember to add code to unlock DFC sessions, close query collections, free allocated memory or release COM objects that you are no longer using. In Visual Basic, these error handlers should take the form of On Error statements within functions and subroutines. Option Explicit Private Sub Form_Load() On Error GoTo ErrorHandler 'Do some work here Exit Sub ErrorHandler: 'Handle the error 'Maybe clean up memory or release resources 'Maybe display an error message to the user End Sub Figure 1 Visual Basic error-handling example In Visual C++, try and catch blocks should be used. try { g_dfClientX = new CDfClientX(); if (g_dfClientX == NULL) return; // something went terribly wrong (very rare) // do some work here } catch (CDfCOMException *exception) { exception->Delete(); // Clean up memory used by the exception } Figure 2 Visual C++ error-handling example

Page 6 of 35

Desktop Client Development Best Practices and Customization Migration Guide

2.2.4 Correctly handle DFC session locking

Since the Documentum Desktop Client runs in a multithreaded environment, it is important to correctly handle DFC session locking. Whenever access to the eContent Server is made, regardless of whether a query is being executed or an object is being accessed or modified, the associated DFC session should be locked. The session should be unlocked once eContent Server access is completed. A failure to lock DFC sessions when accessing the eContent Server, can result in hangs or crashes in the Desktop Client. These hangs or crashes are difficult to track down since they can occur at some point after the eContent Server has been accessed and are not easily reproducible since they are often timing dependent. Additionally, the symptoms of a missing DFC session lock can vary. You may see RPC error messages, crashes, hangs, or simply failed functionality. You can sometimes diagnose a missing session lock by looking at the DMCL trace.
API> save,s0,09148e8b800089d1 Save call was not locked allowing Fetch # Network Requests: 952 call to be made before Save completed. API> fetch,s0,09148e8b800089d1 # Network Requests: 953 # Time: 0.020 sec 'ApplyForBool: connection lost, valid=0, retry=1' # Time: 0.080 sec ' ' API> getmessage,s0,3 # Network Requests: 971 # Time: 0.000 sec '[DM_SESSION_E_TRANSACTION_ABORTED]error: "Transaction aborted by server due to client session timeout. Use abort API to re-establish connection to server."

Figure 3 DMCL trace showing Save API call made without locking the session A failure to unlock DFC sessions can cause the Desktop Client to hang, exhibit inconsistent behavior, or show Operation In Progress dialogs that must be dismissed by the user. The Desktop Client provides smart session locking classes for both Visual Basic and Visual C++ developers that can be used in custom code. The class is contained in DcSessionLock.cls for Visual Basic developers. Visual C++ users can include DcSessionLock.h and DcSessionLock.cpp in their projects to make use of the smart session lock class.

2.2.5 Ensure that query collections are closed

Another source of potentially hard to find and debug errors is due to using up all available collections. By default, there are ten collections available for use. Note, however, that this value can be changed by adding or modifying the 'max_collection_count' entry in DMCL.ini. If all available collections are in use then no more queries can be run. The errors seen by the end user will vary. If a user is in the middle of invoking a WSServer based component when the available query collections are used up, they may see an error message indicating that no more collection objects are available.

Figure 4 WSServer collection object error

Page 7 of 35

Desktop Client Development Best Practices and Customization Migration Guide

Other behavior a user may see is an inability to continue navigation within the Windows Explorer integration, messages about components not being available, or random crashes within the product. These problems can be avoided by ensuring that collection objects are always closed once processing on the collection is complete. It is especially important to include code for closing collection objects within error handling code since that case can be easily overlooked. If you are using the Visual C++ MFC wrappers to access DFC, Documentum recommends that a try catch block be placed around usage of the collection object.
try { // Some DFC code here CDfCollection dfCollection = query.execute(dfSession, CDfQuery ::READ_QUERY) ; try { BOOL moreElements; moreElements = dfCollection.next(); // Some code for accessing the values returned from the collection } catch (...) { // Ensure collection is closed if one was opened if (NULL != dfCollection.GetDispatch() && dfCollection.getState() != DF_CLOSED_STATE) { dfCollection.close(); } throw; } // Some more DFC code here } catch (CDfCOMException * dfCOMException) { // Exception handling code here dfCOMException->Delete(); }

Figure 5 Collection closing in try/catch example

2.3 Preparing for Deployment

During the software development phase, there are some steps you can take to help insure successful deployment of your custom components. This section covers some of the best practices relating to preparing your custom software for deployment.

2.3.1 Maintain binary compatibility when using Visual Basic

When modifying a Visual Basic component, it is important to maintain binary compatibility for the component. Maintaining binary compatibility for a component ensures that its CLSID is constant and does not change. Since the CLSID is the key into the DocApp that allows the component to be invoked, its important to maintain binary compatibility. A failure to maintain binary compatibility may mean that the system will be unable to invoke the custom component when an end user selects the specified functionality from a menu item or toolbar button.

Page 8 of 35

Desktop Client Development Best Practices and Customization Migration Guide The version compatibility for a project is set on the Component tab of the properties dialog box for the project.

Figure 6 Component tab in Visual Basic project property dialog box

2.3.2 Increment the file version when releasing a new version

When making changes to a component, it is important to increment the file version of the component. This allows different versions of a component to be easily identified. Additionally, incremented file revisions are required to make use of Desktop Clients Dynamic Component Delivery functionality for component deployment.

Page 9 of 35

Desktop Client Development Best Practices and Customization Migration Guide In Visual Basic, the file version can be modified on the Make tab of the properties dialog box for the project. The Auto Increment checkbox can be checked to have Visual Basic automatically increment the file version.

Figure 7 Make tab in Visual Basic project property dialog box

Page 10 of 35

Desktop Client Development Best Practices and Customization Migration Guide In Visual C++, the file version is modified by changing the resource for the project. The version information for the project is located in the VS_VERSION_INFO resource and can be changed using the Visual C++ resource editor.

Figure 8 File version shown in the Visual C++ Resource Editor While the Visual C++ resource editor can be used to modify the file version, it is recommended that the file version changes be made to the .rc file in text mode since use of the Visual C++ resource editor to modify the VS_VERSION_INFO structure can cause the OLESelfRegister flag to be wiped out. If the OLESelfRegister flag is missing, then the component will not be able to register and will not be found when a user attempts to use the functionality. To open the .rc file as text, select the Open menu item the File menu in Visual C++. In the open dialog box, select the .rc file, change the selection in the Open as combo box to Text, and then click the Open button. Once the file has been opened as text, the changes to the file version can be made and saved.

Page 11 of 35

Desktop Client Development Best Practices and Customization Migration Guide

Figure 9 VS_VERSION_INFO in text mode

Page 12 of 35

Desktop Client Development Best Practices and Customization Migration Guide

2.4 Making Upgrading Easier

The Desktop Client development platform includes the Visual Basic source code for customizable components. While this model for customization allows for complete flexibility, it can also present a maintenance effort when you upgrade to a new version of Desktop Client. You can minimize the upgrade effort by following some best practices for modifying DTC component source code. This section covers some best practices that when followed during development will make handling Desktop Client upgrades easier later on.

2.4.1 Dont reformat code

When modifying the source code for Desktop Client components, dont reformat the code. Reformatting the code makes it more difficult to distinguish between actual logic or behavior changes and those changes caused by formatting when upgrading to a new version of the Desktop Client. One thing to be careful of is the tendency of Visual Basic to reformat the code. If, for example, the first occurrence of item is changed to Item, all of the subsequent references to item will be changed to Item by Visual Basic.

2.4.2 Dont rename variables

When modifying the source code for Desktop Client components, dont rename variables within the code. It may be tempting to rename variables to names that are more meaningful to you or follow your coding standard but renaming variables makes it more difficult to distinguish between actual logic or behavior changes and those changes caused by renamed variables when upgrading to a new version of the Desktop Client.

2.4.3 Dont rename files

When modifying the source code for Desktop Client components, dont rename the source files. Renaming the source files makes it more difficult to locate those files that have changed in the new version of the Desktop Client and make it more difficult to merge any fixes or functionality. Whether you are manually comparing files or use a diff and merge tool, if you modify file names, it will be difficult to later correlate the files in your custom source with the new source code files.

2.4.4 Use custom code stubs

Most of the changes made to the source for Desktop Client components are executed when the form is loaded or unloaded or the data for the form is saved. The Desktop Client components contain code stubs that are called by the base Desktop Client code. These code stubs should be used whenever available for custom code. Using these code stubs eases migration since the code in these stubs can be copied directly from one version of the Desktop Client to another.
'---------- Customization code (private) ---------'DcCustomOnLoadingCode will be called last in the Form_Load 'event handler. Add your additional initialization logic here 'and/or modify what's provided by the standard component. Private Sub DcCustomOnLoadingCode() 'TODO: Add your logic here. End Sub 'DcCustomOnSavingCode should be called whenever form data is 'being saved. Add code here to save the data you've added to 'this form.

Page 13 of 35

Desktop Client Development Best Practices and Customization Migration Guide

Private Sub DcCustomOnSavingCode() 'TODO: Add your logic here. End Sub 'DcCustomOnUnloadingCode will be called first in the Form_Unload 'event handler. Add your additional termination logic here 'and/or modify what's provided by the standard component. Private Sub DcCustomOnUnloadingCode(Cancel As Integer) 'TODO: Add your logic here. End Sub

Figure 10 Custom Code Stubs

2.4.5 Comment code instead of deleting

When logic in the source for Desktop Client components is to be removed, it is recommended that the code be commented out instead of simply deleted. Commenting the code out removes the functionality from the component yet retains the code so that it can be used as an example. Additionally, when migrating the code, it makes it easier to find custom code in the flow of base Desktop Client source.

2.4.6 Isolate code changes

When changes need to be made to the source for Desktop Client components, it is recommended that the source changes be isolated. Whenever possible, group custom code into functions and place the code in a few places rather than interspersing the custom code with the base component source. Having the custom code in fewer places makes merges easier when upgrading to a new version of the Desktop Client.

2.4.7 Distinctively comment code changes

Another method that helps in making custom code migration easier is to distinctively comment code changes. Having distinctive code comments makes the custom code easier to find. An easy way to do this is by enclosing the custom code in a comment block. Additionally, it is recommended that the code changes be well documented so that it is understood why the changes are being made for the custom solution.
'================================================ ' BEGIN CUSTOM CODE BLOCK ' Workaround for bug 31696 '================================================ If renditionItem.Format = msw8" Then

M_OPENWITHWORD = TRUE
End If '================================================ ' END CUSTOM CODE BLOCK ' Workaround for bug 31696 '================================================

Figure 11 Comment code block example

Page 14 of 35

Desktop Client Development Best Practices and Customization Migration Guide

2.5 Writing faster code

This section outlines some best practices that relate to speeding up custom code to provide better response times within the Desktop Client. It is strongly recommended that you read the Documentum Application Performance and Tuning white paper for a complete guide to these and other performance optimization tips available to Documentum application developers.

2.5.1 Use explicit types

When coding in Visual Basic, variables should be given explicit types. When a variable isnt explicitly typed, it is given the Object type. This slows the code down since Visual Basic needs to figure out the type of the variable whenever it is manipulated. Implicitly Typed (Bad!) Dim count; Dim form; Dim loginMgr; Explicitly Typed Equivalent (Good!) Dim count as Integer; Dim form as frmDcCancelCheckout; Dim loginMgr as DCLOGINMGRLib.DcLoginManager;

Figure 12 Implicit versus Explicit Type Declarations

2.5.2 Use queries instead of fetches

Fetching objects can be more expensive than running queries to get information about an eContent Server object. If only a few attribute values are needed, it is recommended that queries be used instead of fetches to retrieve the values since fetches cause many attribute values to be retrieved unnecessarily. Fetches occur when the DMCL fetch API is used and when the getObject() or getObjectByQualification() methods are called on the IDfSession interface in DFC.
object = (IDfSysObject) session.getObject(objectID); objectName = object.getObjectName(); contentType = object.getContentType();

Figure 13 Code sample with GetObject A common performance mistake is to mix using queries and fetches to get information about an object. When retrieving a few attribute values, a query should be used. If a large number of attribute values are needed or an object needs to be modified, then a fetch should be used.
DfQuery q0 = new DfQuery(); q0.setDQL("select r_object_id, object_name, a_content_type .from where.); IDfCollection c0 = q0.execute( session, q0.READ_QUERY ); while ( c0.next() ) { objId = c0.getId( "r_object_id" ); obj = (IDfSysObject ) session.getObject( objId ); objName = obj.getObjectName( ); contentType = obj.getContentType ();

Figure 14 Code fragment showing query/fetch performance problem

Page 15 of 35

Desktop Client Development Best Practices and Customization Migration Guide

2.5.3 Make use of provided caches for Data Dictionary information

Retrieving information from the data dictionary can be expensive. The Desktop Client provides a cache for Data Dictionary information through the IDcDataDictionaryUtils and IDcDataDictionaryUtils2 interfaces that are part of the Utilities Manager (DcUtilMgr.dll). The cached information includes friendly display names for attributes, content formats, and object types as well as information indicating whether specific formats can be full-text indexed and which object types are searchable.

3 Managing Desktop Client Upgrades

At some point in time, it will be necessary to pick up a new version of the Desktop Client. This may be necessary to take advantage of additional new end-user or developer features, bug fixes, or simply because the existing Desktop Client version is no longer be supported by Documentum. This section covers some best practices that relate to migrating customizations from one version of the Desktop Client to a newer version.

3.1 Migrate then update

While it may be tempting to migrate custom code and implement enhancements and bug fixes to your customization at the same time, it is strongly recommended that the migration and update of custom code take place in two distinct steps. When both migration and code update takes place at the same time, it is more difficult to debug any problems that arise. By migrating the custom code first, any migration related issues that result can be debugged first. This ensures that equivalent functionality is available to the end user. Once the migration is completed, the custom code can be updated to make use of new developer features.

3.2 Understand custom code changes

One of the first things to understand are the code changes made to support a custom solution. For each customized component, know what changes were made and why. One way to examine the custom changes is to compare the original base source code for the component against the customized source. A visual inspection of the user interface differences between the original base Desktop Client and the customized Desktop Client can also help in understanding the change.

3.3 Understand Desktop Client changes

By comparing the provided source for the two versions of the Desktop Client, you can understand the changes made to specific components. Knowing what the changes are can allow the changes to be selectively picked up for the new version of the custom component. It may be the case that a particular bug fix should be migrated, but a new feature should not. Changes to the Desktop Client component may also render a customization obsolete if the new version of the component encapsulates the functionality of the customization.

3.3.1 COM interface changes

If the COM interfaces supported by the Desktop Client have changed, it is important to determine if the modified interfaces are used by custom code. If a modified interface is not used, then the COM interface changes are irrelevant. Typically, COM interface changes within the Desktop Client take the form of additional interfaces. One example, when looking at the differences between the 4.1e and 4.1i releases, is the addition of the IDcDataProtectionUtils3 interface, which extends IDcDataProtectionUtils2. Since the new interface provides all the functionality of an existing interface, the custom code could be easily modified to make use of the new interface instead of an older interface. However, since the older interface is still supported, it is not necessary to make the change.

Page 16 of 35

Desktop Client Development Best Practices and Customization Migration Guide

Once the migration of the component is finished, an analysis can be made to determine if a new interface should be used. The initial release of the Desktop Client included support for the IDcComponentDispatcher interface that allows components to be invoked programmatically via the RunComponent() method. A subsequent release of the Desktop Client included support for the IDcComponentDispatcher2 interface which extended the IDcComponentDispatcher interface and additionally supported the RunComponentEx() method for invoking components. Since the RunComponentEx() method allows for faster dispatching of components that the RunComponent() method, it makes sense to update any custom components which make use of the IDcComponentDispatcher interface to take advantage of the speed improvements offered by the IDcComponentDispatcher2 interface.

3.4 Concentrate on pertinent files

When it comes to handling the component migration, it makes sense to concentrate on pertinent files only. For the most part, only those files that are used in the Desktop Client source for the component and in the custom component source need to be migrated. By concentrating on the relevant files, your time is spent more efficiently evaluating the files that need to be changed in the process of migrating your customization.

3.4.1 Source code control

If a source code control system is used to maintain the code used in a custom component, then files used for source code control maintenance can be ignored. If, for example, Visual SourceSafe is used as the source code control system, then all .scc files can be ignored. Additionally, if source code control related differences are the only differences in a file, then the file can also be ignored during the code migration process.

3.4.2 New files within Desktop Client source

If there are source files included in the new version of the Desktop Client that did not exist in the previous version, then the migration of these new files is straightforward. In most cases, these new source files can be migrated to the new version of the customized code without modification.

3.4.3 Custom only files

If a set of files only exists in the custom source and do not make use of modified COM interfaces, then these custom source files can be migrated as is.

3.4.4 Variable renaming

If the only changes to a file are due to variable renaming, then very little time, if any, should be spent migrating the file. If necessary, the renamed variables can be handled through the use of the search and replace feature available in most development environments. If the variable renaming occurred as a side effect of using Visual Basic, then no change needs to be made to the file.

3.5 Make use of diff and merge tools

Migration can be a daunting task if one looks at the number of source files included with the Desktop Client. To make migrating to a new version of the Desktop Client easier, it is recommended that a diff and merge tool be used. You can use a diff and merge tool to determine the files that have been modified and the differences between them as well as easily merge the changes. It is recommended that the diff and merge tool used allow for the differencing of directories and not just individual files.

Page 17 of 35

Desktop Client Development Best Practices and Customization Migration Guide

3.5.1 Use analogous code hierarchies

When using a diff and merge tool, it is recommended that analogous code hierarchies be used and compared. Since diff and merge tools work by comparing the directory structure and files within a directory, the same code hierarchy should be used for both sets of code that are being compared. If the directory hierarchy is different, it is recommended that the directory hierarchy of one set of code be mapped to the hierarchy used by the other code set prior to using any diff and merge tools to do the comparison.

3.5.2 Diff then merge

It is recommended that the diff and merge tools first be used to examine the differences between the source files prior to actually doing the merge. By doing the diff before the merge, youll have a better understanding of how the changes fit together. Having this knowledge will make merging easier since you wont be picking individual changes in isolation but will understand the context behind the changes.

3.6 Rewrite when necessary

Sometimes, the differences between the two versions of Desktop Client are so dramatic that a simple diff and merge approach to migrating your customization may be extremely difficult. While the use of a diff and merge tool will allow you to understand the changes made to the code between the two versions of the product, it may be easier to simply rewrite all or parts of your customization rather than using the diff and merge tool to handle the migration.

Page 18 of 35

Desktop Client Development Best Practices and Customization Migration Guide

4 APPENDIX A: Diff and merge tools

While Documentum does not endorse the use of any particular diff and merge tool, a couple of diff and merge tools are listed in this appendix for convenience. The reader is under no obligation to use any of the products described herein.

4.1 WinDiff
While not a diff and merge tool, WinDiff is included with the Microsoft Visual Studio product and can be used to evaluate differences within directories or files. Once the changes have been identified, the changes can be manually merged into the new source.

4.2 WinMerge
Readers accustomed to the GNU diff tool may be interested in WinMerge. WinMerge is a port of the GNU diff tool and is available in multiple languages. For more information about WinMerge, please see http://winmerge.sourceforge.net/.

4.3 Visual Merge

Visual Merge is a shareware diff and merge tool that allows for the merging of files or directories. It can be downloaded from http://members.tripod.com/olgac/products.html.

4.4 Araxis Merge

Araxis Merge is a commercial diff and merge tool that allows for in-place editing as well as visual two- and three-way file and folder comparison and merging. A fully functional evaluation version can be downloaded from the Araxis website at http://www.araxis.com/.

Page 19 of 35

Desktop Client Development Best Practices and Customization Migration Guide

5 APPENDIX B: Desktop Client 4.3 Component Source Code Change Summary

This section covers the changes made to the Desktop Client component source code that is distributed with Documentum Developer Studio. This change log covers changes made from the 4.2.1 timeframe up until the 4.3 release.

Bug Descriptions:
25731, 33762: 30172: If the attributes created in DDS are hidden, Property dialog will not show these attributes. If the document object is immutable and it has attributes that has ignore_immutable flag set to true, the properties dialog does not provide Apply or OK buttons to save changes to these attributes. Request to change the error message box title of the Paste As Rendition component to standard DTC caption name Not able to register for notifications unless having WRITE permission on a document. If you have an activity in a workflow that refers to an alias set for the performer, when you start the workflow you are prompted to enter a value for all of the alias sets in your DocApp even though you did not specify those alias sets in you activities. Checkin/Checkout in Task Manager dialog does not versioning properly. Performance improvement. Try to send mail using Outlook automation before using MAPI. Error when try to copy a component in a VDM and use the Paste Special option to create a copy of the component rather than a link to the original Attempting to move an object twice without the proper permissions results in erroneous errors Cannot deliver component functionality on an object which is a shortcut (reference) to an object in a second Docbase. Empty entry in "To" list box after delete a user in the Send to Distribution List's address book dialog. JavaNullLangPointer exception occur when saving date type attributes. Docbase Browser Control is unable to accurately display all of an objects versions Docbase Browser Control doesnt control display of hidden objects Ugly VB error message displayed in Docbase Browser Control when connecting to a down Docbase Docbase Browser Control doesnt follow Do not show screened cabinets option Docbase Browser Control: Document Context Menus Refresh command does nothing Tab key does not work when navigating through the custom attributes inside the custom tab. Docbase Browser Control is missing Properties commands on Docbase, Cabinets and Folders If user has READ permission and Change Owner extended permission on an object, OK and APPLY buttons are not visible thus can not change the owner. If the WarnOpenNonCurrent registry key does not exist, you will get different behavior doing either a check out or open of a non-current version. When importing an Microsoft office document that has an OLE link to another

30174: 31239: 31758:

32383: 32788: 33359: 33491: 35742: 36125: 36311: 36511: 36527: 36548: 36574: 36595: 36750: 36941: 37291:

37399: 37651:

Page 20 of 35

Desktop Client Development Best Practices and Customization Migration Guide Microsoft office file, as a custom type with mandatory attributes, Desktop Client only checks if the master document's attribute field is not empty. Clicked X button on the top right corner of the Property Dialog, causes validation to happen but will not allow user to come back and made changes if there are some invalid attributes. Can not view property dialog on a copied assembly document. Error message pops up at the end of the import when importing multiple documents and opening one properties dialog for the set of files. If a user attempts to create a document in a folder for which they do not have the correct permissions. Customer would like us to display this error message detailing so before the dcnew dialog is displayed. Checking out a non-CURRENT version of virtual node in VDM Editor shouldn't prompt for "check out selected/current version". If the documents with same file name are actually imported into different folders, you should not get these warning dialogs If the r_frozen_flag and r_immutable_flags are set on a document to TRUE you will be able to delete a rendition of that document, but you will not be able to add a new rendition If you edit and check in a document from a workflow inbox task, if you subsequently try to open the document again from the same inbox task, you will be prompted to open either the selected or current version. There is no migration path for post processing in DcCheckinComp. Object ID is not available on checked in object for customer to use. Copying and pasting an object whose name contains an apostrophe generates a syntax error. For 4.2 server or above, object types stored in data dictionary will reflect changes in life_cycle by user, For import and New component, there is not need to check for Life_cycle information anymore. Cannot find the working copy of a document when user edits the document from the target Docbase and the document has been checked out from the source Docbase. The Format Preferences Server degrades Office Integration startup time to severely Changes saved in DcCustomOnSavingCode() arent saved to the Docbase If no document lifecycles are available to be applied, a message should be displayed indicating this rather than having all buttons and controls other than the cancel & help buttons on the apply document lifecycle dialog be disabled. Workflow task manager & explorer integration exhibit inconsistent behavior for no content objects with respect to the open command. While importing more than one CDM, 'Scan for OLE links' check box gets disabled if you try to select all of them in Import dialog Checking out a replicated document that is checked out on the source docbase and has not been refreshed in the target docbase generates an error indicating that the object has been checked out. User should be warned early instead of getting the error. Added a feature to Property component so that for any custom types created in DDS, the user can now add any attributes inherited from a super type into Property Dialog. Note: Checking for duplicate attributes is not implemented in Property component. The Send To Distribution list component will display an error message and exit if the user clicks on the selection list several times. The Address Book dialog for choosing users in the Send To > Distribution List dialog permits the renaming of the users in the list. In the Address Book dialog when starting a Send To > Distribution List

37752:

37873: 37891: 37928:

37942: 37957: 38124:

38175:

38246: 38363: 38318:

38543:

38576: 38650: 38965:

38997: 39111: 39174:

39216:

39285: 39287: 39291:

Page 21 of 35

Desktop Client Development Best Practices and Customization Migration Guide workflow, you can add the same user several times to the list of users to send it to. In the Address Book dialog when selecting peformers for a Send To > Distribution List, the first displayed name in the "To:" field will sometimes disappear. Modify a process/activities created in WFM so that dm_activity.performer_type = 8; dm_activity.performer_name = dm_world; dm_process.act_choose_by = dm_wf_start and 'Start Workflow' dialog chokes, failing to resolve dm_world. Iff an error occurs selecting a performer in 'Start Workflow' dialog, then when Report Manager opens, it is not possible to click on 'Ok' button to dismiss Report Manager. 'Select Performer' child dialog to 'Start Workflow' dialog cannot be dismissed via <esc> key. In DTC4.3 build 133, unable to create a new cabinet in a docbase. Following error message is given: An error occurred while executing the New Cabinet command. Extended highlighting invalid attributes in red to other types of object that support adding custom attributes. The values for repeating attributes are not saved for all documents when importing multiple documents at the same time You can copy multiple documents with the same name into the same folder even with your preferences set to "Warn on duplicate names When attempting to set a performer using an alias set to determine the group to choose from, I receive an error message informing me that I have insufficient permissions to perform the operation. When a user tries to define a performer using an alias set that has not yet been defined the receive an inaccurate error message. Changes made to the custom attribute with an input mask in the Properties dialog does not enable Apply button as a result, save changes can not be saved In Send To Distribution List, if user deletes one of the document to send then add another document and repeat this multiple times, Send To Distribution List shows the wrong icons and send multiple copies of the same document. Docbase Browser Control drag/drop clears CF_TEXT clipboard data Non Administrator Users can't check out Word documents in desktop client with Build 139. The Properties component does not enforce Warn on duplicate names When checking in the document with 30 Japanese characters to description field will cause [DM_OBJ_MGR_E_SAVE_FAIL] ORA-01756:quoted string not properly terminated error. When importing an XML file whose root "chunk" is not supposed to be imported, the DTC validation fails with a message saying "bad object id 000000000000000" DTC allow a user check out a dm_process object but not allow check in the object This bug is logged against DTC 4.1.6jpn version. If message from Desktop Client and object_name including in the message is long, all message is not displayed properly. In SendToDistribution component, message should be limited to 128 char until DFC send to distribution is changed to use the new implementation that allows unlimited length of message. Options appears twice in the 'Open one properties dialog' drop-down list in Import dialog Change the permissions on a dm_router object causes an error

39293:

39347:

39348:

39355: 39384

39456: 39576: 39862: 39943:

39945: 39954:

40083:

40091: 40169: 40254: 40276:

40307:

40368: 40449:

40721:

40752: 41020:

Page 22 of 35

Desktop Client Development Best Practices and Customization Migration Guide "DcPropertiesComp Subscript out of range". Copy content from local file doesnt behave correctly. Last two types created will not be displayed in the New document dialog of DTC. Unable to view custom attributes in Properties Dialog which has lifecycle applied to the object. When a user creates a workflow template that will have a method perform a particular task, and they choose not to have the the execution results saved and the method fails when they click on the print button in the finish dialog they will receive a run time error. The open component will fail when a user connects to a Unix Docbase using one password and then tries to open a DRL referencing a document from an NT Docbase where the user has a different password. Super users cant create a new folder which has custom attribute on the folder type. Objects are imported as dm_document even when dm_document is obsolete because trying to use custom type. Log_entry carried over from one version to the next when check in a document If a user opens the properties dialog of a document and changes the name of the document then clicks the apply button, and without closing the properties dialog changes other properties of the document (like the title) and clicks the apply button again, they receive a warning message informing them that a document by that name already exists The DTC checkout component is sending out checkout events for the application support documents in the XML application folder.

41060: 41138: 41332: 41341:

41353:

41373: 41491: 41596: 41824:

41866:

New Feature Index:

F1: Component dispatcher / dynamic component delivery tracing exposed via Properties dialog F2: Dynamic Performer in Workflow

Others:
A1: A2: A3: A4: A5: Cleaned up full-text indexing code in Properties component. Workaround for bug 37752, validate all attributes instead of only modified attributes. Windows XP: Version label on Checkin dialog changes the background color to white. Memory leak and clean up source code In Send To Distribution List, the instruction should be limited to 128 chars, instead of 42.

Page 23 of 35

Desktop Client Development Best Practices and Customization Migration Guide

Files Changed:
Filename Feature/ Bug # Description of Change

Desktop Client\Component\Cancel Checkout

DcCancelCheckoutComp.cls 41060 1. Added a private function ShouldKeepLocalFile() to look up the KeepWorkingCopy and KeepLocalFile registry keys. It will return True if any of the two key is set to True; return False otherwise. 2. In PreCancelCheckout(), added code to setKeepLocalFile on each cancelCheckoutNode to True or False depends on the return of ShouldKeepLocalFile(). After checkout succeed, check to see if the node is really checked out before sending out the checkout notification even

DcCheckoutComp.cls

41866

Desktop Client\Component\Check In
DcCheckinComp.vbp DcCheckIn.frm 38543 A3 38026 Add Documentum Event Server to the project Change the background color of the Version label to &H8000000F&. If the application is Power Point, enable and check the scan for links checkbox Since Power Point OLE link detection will determine if the file has links Disable format combo box, full text index checkbox and show all format checkbox when the format is not found in the format list. Get the max characters that allowed in description field depends on server version and language regional setting If the object is a replica, then we refresh the replica and send out event notification after checkin is completed. Also added new method RefreshReplica and SendEventNotification for this purpose In IdcComponent_Run, resolve the replica and pass the object id of the source object to the Check In form. Do not carry over the previous version of log entry when check in

frmDccheckin.frm

40368

40276

38543

DcCheckinComp.cls

38543

DcCheckin.frm

41596

Desktop Client\Components\Check Out

DcCheckOutComp.cls 39174 1. In DetermineObjectsToCheckout() for replica type, check if the lock owner name and current user name are the same. If so, warn the user that the document has been check out on the source Docbase by the current user and that we will only refresh the replica to pick up the changes. 2. Added a new method, sendEventNotification(), which sends out event notification. In DetermineObjectsToCheckout(),if the version is not CURRENT, also check if the item container is VDM Editor. If the container is VDM Editor, then we dont show the Selected, Current, Cancel dialog to user. Instead, we will check out the selected version 1. Added new constant for the string ID 2. Change the implementation of checking out replica to resolve the replica before passing the object to

37942

38543

Page 24 of 35

Desktop Client Development Best Practices and Customization Migration Guide Filename Feature/ Bug # Description of Change
DFC. This way the working copy registry will always have the object id of the source object 3. Added helper functions that refreshes replica and send event notifications as appropriate so events get propagated correctly. Change the error message to reflect what happens here Added new string for error message After get the checkout directory from the registry, create the checkout directory if it does not exist Still proceed check out operation if the checkcheckoutdirectory fails.

DcCheckOutComp.res

39174 38543 39869 40169

DcCheckoutCompl.cls

Desktop Client\Components\Copy Link Move

DcCheckoutComp.cls DcCopyLogic.cls 37399 33359 set the default to TRUE when "warnonnoncurrent" registry key does not exist. 1. Changed to accept TargetItemContainer instead of TargetVirtualDocItemContainer and hooked up all broken pieces. 2. Changed to call getRootNode instead of getNodes from the copy operation when called from VDM to avoid adding the copied children along with the parent node. 3. Hid the copy option dialog if it's called from VDM to avoid the additional UI selection 1. Implement Move2() in order to pass information needed to display an Report Manager dialog. 2. Move(): Properly handle and recover from errors. Move(): check the files with duplicated name when performing move operation. IDcComponent_Run(): Call Move2() for move operation. getObjNameListAsString(): Put a quote before any quote in the object name. GetWarnDuplicateNamesOption(): Set Default value of WarnOnDuplicateName to be true, set it to be false only if user specified in the registry. Check the duplicated name in move case If the registry key is not available, set the value to T not F.

DcMoveLogic.cls

33491

39862 DcLinkCopyMove.cls DcWarnOnDuplicateNames.bas 33491 38363 39862

DcMoveLogic.cls DcWarnOnDuplicatednames.bas

39862

Desktop Client\Components\Docbase Browser

browserControl.ctl 36548 36527 connectToDocbase(): Resume on next statement during an error. Implement ShowHiddenObjects property. In fillFolderNode(), add a_is_hidden to the select clause and remove a_is_hidden = 0 from the where clause fillDocbaseNode(): Implement ShowScreenedCabinets option. browseTree_MouseDown(): Hide Refresh menu item and its separator if the node is a plain document. Add Properties command form Docbases, Cabinets and Folders. 1. Implement the List View Pane, which shows all the versions of the object selected in the Tree control. The pane is initially not visible (by making its height 0), but can be made visible via the public property

36574 36595 36941 36511

Page 25 of 35

Desktop Client Development Best Practices and Customization Migration Guide Filename Feature/ Bug # Description of Change
ShowListView(). UpdateListView() is used to query and display the versions of the item selected in the Tree control. The list view is resized along with the enclosing control or frame. A Timer control is employed to delay the update for 750 msec in case the user is rapidly clicking or scrolling using the arrow keys. 2. InvokeCmd(): Dont display an error if reporter.GetEntryCount returns 0. SetClipboard(): Save and restore CF_TEXT clipboard data. Add IDS_THOUSANDS_SEPARATOR

40091 browser.res globalModule.bas 36511

Desktop Client\Components\Document Lifecycle

DcApplyDocLifecycle.frm DcApplyDocLifecycleAll.frm DcDocLifecycleComp.rc Resource.bas DcDocLifecycleComp.cls 38965 38965 Show informative message that no lifecycles can be applied to the selected document. Add new strings and constants for new error messages. Check if reportMgr is nothing before adding entry.

Desktop Client\Components\Import
DcCreatableTypeUtil.cls 38318 For server 4.2 or above, get the creatable type from datadictionary directly; for server 4.1, still use apply method. In InitCreatableTypeListUseDataDict(), removed code which caused the creatable type collection to be incorrectly truncated. Get the virtual document's children object id, and validating them In clearFormatList(), do not need to disable scanforolelinks checkbox since it is independent from format setting. Modify copyProperty(), UpdateModifiedAttr(), RecordOrigAttr() function to get the list for repeating attribute Only add the filename or foldername that is at root level. Check the object_Id before validate it. Compare the duplicated file name with the ones after it in ShowPropertyGroupInfo(), only add the items to cboPropertyGroup when chkOpenPropertyDialog.value = 1 because set chkOpenPropertyDialog.value = 1 will call ShowPropertyGroupInfo() function. In Form_load, if it fails to find dm_document or dm_folder in the type list, use the first type and call Import Tree Control to update the default document type and default folder type.

41138

DcImport.frm

37651 39111

39576

37957 40307 37957 40752

DcWarnOnduplicatedName.bas DcImport.frm

DcImport.frm

41491

Desktop Client\Components\New
DcCreatableTypeUtil.cls 38318 For server 4.2 or above, get the creatable type from datadictionary directly; for server 4.1, still use apply method. In InitCreatableTypeListUseDataDict(), removed code which caused the creatable type collection to be incorrectly truncated.

41138

Page 26 of 35

Desktop Client Development Best Practices and Customization Migration Guide Filename
DcNewDocument.frm

Feature/ Bug #
31880

Description of Change
In the CreateDocument method(), moved the hiding of the new document dialog to before the start of the check in/edit operations. This prevents the Explorer integration windows from recapturing the input focus after an application like MS Word has been launched to edit the newly created document. Dont perform the permission check if GetLinkLocationID is returning an empty string which is returned when creating a cabinet Check the permission before brings up the form Pass an empty string in the second parameter for DcCheckForDuplicateNames() since object ID is null.

DcNewObjectComp.cls

39384

DcNewObjectComp.cls DcNewDocument.frm

37928 41824

Desktop Client\Components\Open
DcOpenDocumentComp.cls 38543 Memory leak fix: Added call to newly added Term() method on to the Document manager service 1. In GetObjectInfo, check if an object is a replica. If so, then set m_sourceObjectID to the object id of the source object. 2. In GetObjectContent, use m_sourceObjectID as the objectID for getting working file path and opening the document thru ODMA interface if the object is a replica. 1. Added On Error Resume Next to fall over to the recovery code in case of a DFC exception 2. Set the user name in LoginInfo regardless of whether the password is empty or not so that a valid session ID can be gotten by calling getSharedSession 3. Only call getSharedSession when the password is not empty because a DFC exception will be thrown if the password is empty Resize the message label on the dialog so that it can shows the message completely. Added a new member variable, m_sourceObjectID

41353

NotCurrentDialog11.frm DcObjectInfo.cls

40449 38543

Desktop Client\Components\Paste As Rendition

frmDcPasteAsRend.frm DcPasteAsRendComp.res DcPasteAsRenditionComp.vbp 30174 Added standard DTC caption to all message boxes. Added German, French, Japanese and Korean string tables. 1.Updated the version label. 2. Added localized template forms to the project. 3. Copyright/version update . 4. Update copyright year. Display the error message more friendly when addRenditionEx() fails.

frmDcPasteAsRend.frm

38124

Desktop Client\Components\Properties\Abstractions
DcAbstractPropsComp.vbp DcDocumentum.frm DcDocumentum.frx DcSpecificDocbase.frm DcSpecificDocbase.frx Resource\DcAbstractPropsComp.rc Resource.bas 38576 F1 F1 38576 Add reference to DCFMTPREFSRVLib Added support for Component Dispatcher / dynamic component delivery tracing Added support for Component Dispatcher / dynamic component delivery tracing 1. Add Formats tab. 2. Implement cmdUpdateFmtPreferences_Click(). Add IDS_LOCAL_FMT_PREFS_UPDATED,

38576

Page 27 of 35

Desktop Client Development Best Practices and Customization Migration Guide Filename Feature/ Bug # Description of Change
IDS_FORMATS.

Desktop Client\Components\Properties\Docbase Objects

DcCabinetFolder.frm DcDocument.frm DcDocumentLifecycle.frm DcOnlineLocalDocument.frm DcProcedure.frm DcQuery.frm DcRouter.frm DcSysObject.frm DcSmartList.frm DcDocument.frm 25731 33762 Need To DisplayCustomAttributes(): If the custom attributes are hidden, do not add them to custom attributes array.

30172

DcDocument.frm DcDocument.frm DcDocument.frm DcCabinetFolder.frm DcDocumentLifecycle.frm DcOnlineLocalDocument.frm DcProcedure.frm DcQuery.frm DcRouter.frm DcSmartList.frm DcSysObject.frm DcDocument.frm DcPropertiesSecurity.cls

31239 36311 36750

Handle save changes to document that is immutable and has attributes that has ignore_immutable flag to true. UpdateAttrUIWhenReadOnly(): Do not check permission for enabling notification radio buttons SavePropertyChanges(): Check if need to revert and revert if necessary before doing any save changes InitCustomAttributeUI(): Assigned tab index to individual custom attributes

37291

41373

DcCabinetFolder.frm DcDocument.frm DcDocumentLifecycle.frm DcOnlineLocalDocument.frm DcProcedure.frm DcQuery.frm DcRouter.frm DcSmartList.frm DcSysObject.frm DcDocument.frm DcActivity.frm DcAnnotation.frm DcCabinetFolder.frm DcDocumentLifecycle.frm DcOnlineLocalDocument.frm DcPermissionSets.frm DcProcedure.frm DcProcessDefinition.frm DcQuery.frm DcRouter.frm DcSmartList.frm

37752

Check whether user has Change Owner extended permission Added a new CanChangeOwner function in this class to see if the user has Change Owner permission. In the process of creating a new object, if property component get called due to invalid attribue constraint, owner_name of Sysobject will be still null. Servers require owner_name of new object to be set, use username who currently is logging in as the owner_name Form_QueryUnload(): set variable Cancel = True if there is an invalid attribte, so VB will not call Form_Unload.

37873 38650

InitFullTextIndexable(): Added On Error Resume Next at the beginning of the function. DcOnSavingCode(): Call DcCustomOnSavingCode() before calling SavePropertyChanges()

Page 28 of 35

Desktop Client Development Best Practices and Customization Migration Guide Filename
DcSysObject.frm

Feature/ Bug #

Description of Change

DcDocument.frm

39216

DcCabinetFolder.frm DcDocumentLifecycle.frm DcOnlineLocalDocument.frm DcProcedure.frm DcPropertiesComp.cls DcQuery.frm DcRouter.frm DcSmartList.frm DcSysObject.frm DcAutoChangeControl.cls DcDocument.frm

39456

Changed some variables to have m_ prefix to indicate member variable. Added three new functions CheckIgnoreImmutable(), CheckIgnoreImmutableFor41Server(), NeedToDisplayCustom AttributesFor41Server(). In CheckIgnoreImmutable() and NeedToDisplayCustomAttributes(), use DQL query to retrieve Data Dictionary information of the object. Highlight invalid attributes in red. Added a lot of functions e.g. SetLabelHighlighting(), HighlightInvalidLabel(), etc.Do not call to ValidateOnlLostFocus, and only validate if the object is not checkout or not new object.

39954 38650 40254

DcPropertiesComp.cls

40254

DcPropertiesComp.vbp DcWarnOnDuplicateNames.bas Resource.bas DcRouter.frm DcDocument.frm

40254 40254 40254 41020 41332

DcDocument.frm DcWarnOnDuplicateNames.bas

41824 41824

DcDocument.frm DcOnlineLocalDocument.frm DcProcedure.frm PropertiesFunctions.bas DcDocument.frm DcCabinetFolder.frm DcDocumentLifecycle.frm DcOnlineLocalDocument.frm DcProcedure.frm DcPropertiesComp.cls DcQuery.frm DcRouter.frm DcSmartList.frm

A1

Added KeyDown event to dfwcombobox attribute DcOnSavingCode(): Call DcCustomOnSavingCode() before calling SavePropertyChanges (). SavePropertyChanges(): Check for duplicate names immediately after validating the modified attributes 1. IDcComponent_Init(): Set m_itemContainerObjectID 2. IDcComponent_Run(): Pass item container object ID to docPropsForm 3. Call RegCloseKey in WarnOnNonCurrent() to prevent resource leak Add DcWarnOnDuplicateNames.bas Shared from the New component Add IDS_DUPLICATE_NAME_WARNING, IDS_MY_CABINET Form_Activate(), call to setFocus on txtObjName once when the form got loaded the first time NeedToDisplayCustomAttributes():Updated DQL queries to retrieve data dictionary information correctly if the object has a lifecycle attached to it Pass in an object id to DcCheckForDuplicateNames(). DcObjectWithNameExists(), when issuing a query to retrieve duplicate names, exclude its own object_id i.e. the document that user is modifying Added InitFullTextIndexable() Added ServerVersionAtLeast() and removed ServerVersion42Greater(). SavePropertyChanges(): Validate all attributes, not only modified attributes e.g. call validator.validateAll Nothing, False

A2

Page 29 of 35

Desktop Client Development Best Practices and Customization Migration Guide Filename
DcSysObject.frm Workitem.frm DcReference.frm

Feature/ Bug #
35742

Description of Change

Change the control to multiline Change cmdTargetProperties_Click to get the target Docbase name and use the target Docbase name as the Docbase name parameter for RunComponent method

Desktop Client\Components\Properties\Docbase Objects\Resource

DcProperties.rc 40254 Add IDS_DUPLICATE_NAME_WARNING, IDS_MY_CABINET entries for all languages. (Japanese and Korean are just placeholders, though.)

Desktop Client\Components\Send Mail

DcSendMailComp.cls 1. Added check if the URL is valid and present a message box in case it is not. Added check if there is right site image, web server location and web server port. 2. replaced getFile with getFileEx to be able to pass the rendition format 3. Added check for the collection type and call getFile or getFileEx based on the type 4. Added code to send mail using Outlook automation before trying to use the mapi32.dll 5. Updated Copyright info 6. Updated version, removed author and log info. 1. Updated the version label to 4.2. 2. Added references to msoutl85.olb and scripting type library 3. Corrected the reference for dmmailatl 4. Updated copyright info 5. Updated version, removed author, log info 6. Updated copyright year 1. Added constant definitions 2. Updated copyright info 3. Updater version, removed author and log info

32788

DcSendMailComp.vbp 32788

Resource.bas

Desktop Client\Components\Workflow\Start
DcStartWfLib.vbp F2 Added new files to the project for dynamic performer changes. Added WorkflowUtil.bas to the project. Change the path not to point to the RefCopy. Add dynamic performer support to the dialog. 1. In Form_Load, call assignIconsToItems only when the AttachmentsView has items. 2. In StartBtn_Click, before saving the alias value, check if the alias name is used by the activity. 3. In PopulatePerformerView, add the alias name only if the alias name is used by the workflow. 4. Add new methods: isAliasNameUsed, which checks if an alias name is used, and PopulateUsedAliasNames, which strores alias names used by the workflow in a global array of strings. Add mnemonics key to the buttons. In DynamicPerformersView_DblClick method, add session locking mechanism since we are accessing the Docbase using the established session. Also, create a new instance of report manager and use that

StartWorkflow1.frm

F2 31758

39359 39348

Page 30 of 35

Desktop Client Development Best Practices and Customization Migration Guide Filename Feature/ Bug # Description of Change
report manager instead of the one global one, since the global one seems to cause problems. Note: using new instance of report manager doesnt make any difference since we always display the dialog after we add error message. So we wont loose previous error message by using new instance of report manager. In SetStartState(), move the check if all alias values are set to the bottom. Basically, check this at the end before we exit the function. This way, it will set the Start button correctly. Add check to see if the report manager instance passed in by IDcComponent_Init method is not nothing before saving the reference. If it is nothing, then create a new instance of report manager New form for dynamic performer selection dialog. This file is shared between Start and Task Manager components. 1. Add missing comment. 2. Delete commented code. 3. Reallign and resize controls 39347 Check the case that performer_type = 8 and performer_name = dm_world then set up the Select Dynamic Performer Dialog accordingly. Set the cancel button as the escape button New template forms for Select Dynamic Performer form. Used only in localized product

39945

DcStartWorkflowComp.cls

SelectDynamicPerf.frm

F2

SelectDynamicPerf.frx SelectDynamicPerf07.frm SelectDynamicPerf0c.frm SelectDynamicPerf11.frm SelectDynamicPerf12.frm SelectPerformer.frm WorkflowUtils.bas

39355 F2

F2 F2

39943 DcClipboardDataParser.cls

Resource.bas DcStartWFComp.rc

F2 F2

Change the dialog name to Assign Performer. New file for common functions used among DTC WF components. This file is shared among Start, Status and Task Manager components. 1. Add missing comment. 2. Delete commented code. 3. Reallign and resize controls. Added a new method SetWorkitemPerfomers which call IdfWorkitem::SetPerformers. Fix the ExtractData method to takes into account isNew and the itemContainerType variables added to the DcItemData structure. Added new resource ids. Added the resource strings.

Desktop Client\Components\Workflow\Send To Distribution List

DcAddress.frm 39293 1. Add ToUsersList_ OLEDragOver to disable the drag/drop effect if the source of the drag/drop operation is not AllUsersList listview. 2. Add AllUsersList_ OLEDragOver to disable the drag/drop effect if the source of the drag/drop operation is not ToUsersList listview. 3. In ToUsersList_ OLEDragDrop and AllUsersList_ OLEDragDrop, check if the selected item is nothing before using the item. 4. Add the source listview name to the data so that

39285

Page 31 of 35

Desktop Client Development Best Practices and Customization Migration Guide Filename Feature/ Bug #
39287

Description of Change
we can check later what the source of the drag/drop operation. 5. Change the LabelEdit property of ToUsersList and AllUsersList to manual to prevent user from modifying the user names on the listviews. 1. Add a function isUserInToList that checks if a user is in the recipient list. 2. In AddCommand_Click, disable the AddCommand button after a user is added to the recipient list. 3. Implements AllUsersList_Click, which enables or disables the AddCommand button depending on whether the selected user in the AllUsersList has been added to the ToUsersList. 4. In AllUsersList_DblClick, add a check to see if a user is in the recipient list before adding the user into the recipient list. Then also disable the AddCommand button. 5. In ToUsersList_OLEDragOver, check to see if the selected user is in the recipient list before setting the effect of the drag/drop. 6. In ToUsersList_OLEDragDrop, disable the AddCommand button after the selected user is added to the recipient list. 1. Add new array to store the unique tag for each attachment. This tag will be used later to identify a specific attachment when the attachment will be deleted. 2. In AttachmentsView_KeyUp that handles the delete key, call RemoveItemFromItemList, which removes the selected item from the array, remove an image from the image list and reassign the icons. 3. Implement RemoveItemFromItemList which marks the item whose tag matches the selected items tag as deleted by setting the object ID and object name to . 4. In SendCommand_Click, loop thru our arrays of attachments and send only those whose object Ids are not . 1. Added a new function, isServer42OrLater, which returns True if the server we are running against is 4.2 or later. 2. In SendCommand_click method, check if the length of the string exceeds 128 bytes. If so, prompt the user that the message they enter is longer than 128 bytes and tell them what the max number of chars they can enter for the message depending on which locale DTC is running on. Change the check for IDS_FORM_ID to 11 for Japanese. Added new constants and new strings for the error message. Also added form ID. Fix the ExtractData method to takes into account isNew and the itemContainerType variables added to the DcItemData structure.

Address.frm 36125 39291

DcSend.frm DcSend.frx

40083

40721

A5 Resource.bas DcSendToDistComp.rc DcClipboardDataParser.cls 40721

Desktop Client\Components\Workflow\Status
DcWFStatusComp.vbp F2 Added WorkflowUtil.bas to the project. And new resource.bas file.

Page 32 of 35

Desktop Client Development Best Practices and Customization Migration Guide Filename
DcWFStatus.frm

Feature/ Bug #
F2

Description of Change
Added dynamic performer support for displaying performers name and choose from activity information. Added resource strings. New file for resource ids. New file for common functions used among the DTC WF components. This file is shared between Start, Status and Task Manager components 1. Add missing comment. 2. Delete commented code. 3. Realign and resize controls. Added a new method SetWorkitemPerfomers which call IdfWorkitem::SetPerformers.

DcWFStatusLib.res Resource.bas WorkflowUtil.bas

F2 F2 F2

39943

Desktop Client\Components\Workflow\Task Manager

DcTaskMgrComp.vbp Workitem.frm F2 F2 38175 Added new files to the project for dynamic performer changes. Added WorkflowUtil.bas to the project Add the Dynamic Performer Support to the dialog. In Form_Load(), while getting the packages, check if the packages label is CURRENT. If so, check if the attachment label is CURRENT. If not, then get the CURRENT version of the attachment. 1. Added UpdateDataAfterCheckin method, which gets the new object id of the document which may change as a result of Checkin operation. 2. After checkin operation is done, call UpdateDataAfterCheckin method which updates the package infos doc ID with the new object ID. 3. Break the method RefreshForm to a new RefreshForm that takes event code and object, and another method call UpdateIcons, which basically updates the icons as necessary. This new implementation of RefreshForm calls UpdateIcons. In Form_Load, initialize package infos contentType to a_content_type of the attachment. In PackageSelected, disable the Open button when the attachment has no content unless the attachment is a virtual document. In InsertAttachment, set the package infos contentType to a_content_type of the attachment Set variable back to nothing after using the variable. Cleanup unused variable. Also, delete the images in the ImageList while cleaning up the form. 1. In IdcEventSink_HandleEvent, for DC_EVT_TYPE_NOTIFICATION, change the line that calls RefreshForm to pass in two parameters. 2. In IdcEventSink_HandleEvent, also initialize the return value of this method for some of the cases. Change RefreshForm method to take event code and an object. This is to allow the method to decide which method to call depending on the event code. Added dynamic performer support for displaying performers name. Set variable back to nothing after using the variable. Cleanup unused variable 1. Add missing comment. 2. Delete commented code.

32383

38997

A4

DcEvent.cls

32383

Global.bas

32383

AboutTask.frm

F2 A4

Page 33 of 35

Desktop Client Development Best Practices and Customization Migration Guide Filename Feature/ Bug #
F2 F2 A4

Description of Change
3. Realign and resize controls. Add the Dynamic Performer Support to the dialog. Add the Dynamic Performer portion to the dialog. Make Select Repeater into a new form. Set variable back to nothing after using the variable. Cleanup unused variable 1. Add missing comment. 2. Delete commented code. 3. Realign and resize controls. When completing a task, instead of calling SetPerfomers method which uses IdfWorkflow::SetPerformers, call SetWorkitemPerformers which uses IdfWorkitem::SetPerformers. New form for dynamic performer selection dialog. This file is shared between Start and Task Manager components 1. Add missing comment. 2. Delete commented code. 3. Realign and resize controls. Check the case that performer_type = 8 and performer_name = dm_world then set up the Select Dynamic Performer Dialog accordingly Set the cancel button as the escape button New template forms for Select Dynamic Performer form. Used only in localized product.

ConfirmForm.frm Done.frm Done.frx

39943

SelectDynamicPerf.frm SelectDynamicPerf.frx

F2

39347

SelectDynamicPerf07.frm SelectDynamicPerf0c.frm SelectDynamicPerf11.frm SelectDynamicPerf12.frm SelectRepeater.frm

39355 F2

F2

SelectRepeater07.frm SelectRepeater0c.frm SelectRepeater11.frm SelectRepeater12.frm RerunForm.frm

F2

New form to Select Repeater 1. Add missing comment. 2. Delete commented code. 3. Realign and resize controls. New template forms for Select Repeater form. Used only in localized product.

F2

39355 41341

RerunForm07.frm RerunForm0c.frm RerunForm11.frm RerunForm12.frm WorkflowUtil.bas

F2

New form to rerun failed automatic task. 1. Add missing comment. 2. Delete commented code. 3. Realign and resize controls. Set Cancel button as the escape button. In PrintBtn_Click, added exception handler which prompts the user that the error description cannot be printed. New template forms for Rerun form. Used only in localized product.

F2

39943 Packageinfo.cls A4

New file for common functions used among the DTC WF components. This file is shared between Start, Status and Task Manager components. 1. Add missing comment. 2. Delete commented code. 3. Realign and resize controls. Added a new method SetWorkitemPerfomers which call IdfWorkitem::SetPerformers. Set variable back to nothing after using the variable. Cleanup unused variable

Page 34 of 35

Desktop Client Development Best Practices and Customization Migration Guide Filename Feature/ Bug #
38997

Description of Change
Add new member variable, contentType, which is initialized to empty string and set to empty string in DeleteDocument method. Fix the ExtractData method to takes into account isNew and the itemContainerType variables added to the DcItemData structure. Set variable back to nothing after using the variable. Cleanup unused variable Added resource strings. Added new message string. Added new resource IDs Added new constant for the string ID.

DcClipboardDataParser.cls

DcTaskMgrComp.cls Reassign.frm DcTaskMgrComp.rc Resource.bas

A4 F2 41341 F2 41341

Desktop Client\Utilities
DcClipboardDataParser.cls Fix the ExtractData method to take into account the isNew and itemContainerType variables added to the DcItemData structure

Page 35 of 35