EMC Documentum ApplicationConnectorsSDK Documentum® ApplicationConnectorsSDK Version6 DevelopmentGuide P/N300005257 EMCCorporation CorporateHeadquarters: Hopkinton,MA01748‑9103

EMC® Documentum®

Application Connectors SDKVersion 6

Development GuideP/N 300005257

EMC CorporationCorporate Headquarters:

Hopkinton, MA 01748‑91031‑508‑435‑1000www.EMC.com

Copyright © 2006 ‑ 2007 EMC Corporation. All rights reserved.

Published August 2007

EMC believes the information in this publication is accurate as of its publication date. The information is subject to changewithout notice.

THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONSOR WARRANTIES OF ANY KINDWITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLYDISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.

For the most up‑to‑date listing of EMC product names, see EMC Corporation Trademarks on EMC.com.

All other trademarks used herein are the property of their respective owners.

Table of Contents

Preface ................................................................................................................................. 9

Chapter 1 Overview ..................................................................................................... 11Introduction ..................................................................................................... 11Architecture ..................................................................................................... 11For more information........................................................................................ 13

Chapter 2 Installing and Setting Up the Application Connectors SoftwareDevelopment Kit .......................................................................................... 15Installing the Application Connectors SDK......................................................... 15Installed folders and files .................................................................................. 15

Chapter 3 Quick Start .................................................................................................. 17General procedure for creating and integrating an applicationconnector with your application ........................................................................ 17Creating an application connector...................................................................... 19Initializing and cleaning up your application connector ...................................... 21Calling the application connector from your application ..................................... 23

Chapter 4 Implementing Your Application Connector Provider ................................... 25General procedure for implementing yourMyAppIntegrationProviderBase class ................................................................ 26Implementing the InitializeAppIntegration method ............................................ 26Implementing the ActiveDocumentArguments property..................................... 28Implementing the ActiveDocumentFilePath property ......................................... 29Implementing the ActiveDocumentModifiedSinceLastSave property ................... 29Implementing the ActiveDocumentObjectId property ......................................... 30Implementing the ActiveWindowHandle property ............................................. 31Implementing the Close method ........................................................................ 31Implementing the CloseActiveDocument method ............................................... 32Implementing the DefaultDocumentFormat property ......................................... 32Implementing the DoAbout method .................................................................. 33Implementing the DoOpenDocument method .................................................... 33Implementing the MenuBar property................................................................. 34Implementing the OpenedRepositoryDocumentCount property .......................... 35Implementing the RefreshMenu method ............................................................ 35Implementing the SaveActiveDocument method ................................................ 36Implementing the ShowBusyCursor method ...................................................... 37

EMC Documentum Application Connectors SDK Version 6 Development Guide 3

Table of Contents

Implementing the ShowDefaultCursor method .................................................. 38Implementing the UpdateActiveDocumentArguments method ........................... 38

Chapter 5 Handling Events .......................................................................................... 41Overview ......................................................................................................... 41AppConnectorEventServer scenarios ................................................................. 43Unanswered broadcast query event dispatch flow .......................................... 43Answered broadcast query event dispatch flow .............................................. 44Approved state transition broadcast event dispatch flow................................. 45Vetoed state transition broadcast event dispatch flow ..................................... 46

WDK events ..................................................................................................... 46

Chapter 6 Creating and Modifying the Documentum Menu ......................................... 49Introduction ..................................................................................................... 49Building the Documentum menu....................................................................... 52Implementing the BuildMenu method ........................................................... 53Implementing the BuildMenuState method .................................................... 56Implementing the DestroyMenu method........................................................ 59Implementing the DestroyMenuState method ................................................ 59Implementing the RebuildMenu method........................................................ 60Implementing the RefreshMenu method ........................................................ 61

Removing menu items from all applications ....................................................... 62Modifying menu items for all applications ......................................................... 63Adding custom menu items to all applications ................................................... 65Restricting menu items to specific applications ................................................... 65

Chapter 7 Customizing and Creating Application Connector Componentsand Actions ................................................................................................. 69Overview ......................................................................................................... 69List of Application Connectors components and actions...................................... 69Creating new application connector components and actions .............................. 70appintgcontroller component ............................................................................ 71Client environment qualifier in the WDK application.......................................... 74Sample............................................................................................................. 75Introduction ................................................................................................. 75Procedure .................................................................................................... 75

Chapter 8 Deploying Your Application Connector ....................................................... 79Overview ......................................................................................................... 79Installing with an MSI or InstallShield installer................................................... 79Installing with a non‑MSI or non‑InstallShield installer ....................................... 79

Chapter 9 Debugging Application Connector Execution ............................................. 81Setting logging options ..................................................................................... 81Assembly Requirements ................................................................................... 82

Chapter 10 Troubleshooting .......................................................................................... 83

Chapter 11 Creating Application Connectors That Integrate with C++ orVisual Basic 6 Applications ......................................................................... 85

4 EMC Documentum Application Connectors SDK Version 6 Development Guide

Table of Contents

Introduction ..................................................................................................... 85Overview ......................................................................................................... 85Creating application connectors that integrate with C++ applications ................... 87Creating your application connector .............................................................. 87Creating your MyAppConnectorEventClient.................................................. 89Modifying your main frame class .................................................................. 90

Chapter 12 Executing Documentum Foundation Class Functionality fromYour Application Connector ........................................................................ 93Introduction ..................................................................................................... 93Overview ......................................................................................................... 93Procedure ........................................................................................................ 94

Appendix A Sample Applications ................................................................................... 97Running in debug mode ................................................................................... 97


Table of Contents

List of Figures

Figure 1. Application Connectors SDK Architecture ............................................................. 12Figure 2. Application Connector, Webtop, Repository Relationship........................................ 12Figure 3. AC SDK .NET Runtime Assemblies and Runtime Service Structure ......................... 13Figure 4. Event Dispatching Interaction Diagram.................................................................. 42Figure 5. Unanswered Broadcast Query Event Dispatch Flow................................................ 44Figure 6. Answered (True) Broadcast Query Event Dispatch Flow ......................................... 44Figure 7. Approved State Transition Broadcast Event Dispatch Flow...................................... 45Figure 8. Vetoed State Transition Broadcast Event Dispatch Flow .......................................... 46Figure 9. Application Connector standard Documentum menu ............................................. 51Figure 10. MDITextEditorSampleAppConnector solution architecture ..................................... 86


Table of Contents

List of Tables

Table 1. Application Connectors menu configuration elements ............................................ 63Table 2. Appintgcontroller <dispatchitems> elements .......................................................... 72Table 3. Required pages in appintgcontroller component definition ..................................... 73


Table of Contents


Preface

This document describes how to use the Application Connectors Software Development Kit to enableWindows desktop applications to access and manipulate objects in Documentum repositories.

Intended AudienceThe audience of this manual is intended to be Windows developers who are not familiar withDocumentum.

Revision HistoryThe following changes have been made to this document.

Revision History

Revision Date Description

August 2007 Initial release for Documentum 6.


Preface


Chapter 1Overview

These topics are described:• Introduction, page 11• Architecture, page 11• For more information, page 13

IntroductionYou use the Application Connectors Software Development Kit (AC SDK) to create EMC |Documentum Application Connectors that enable Windows applications, such as rich editors, to checkin and check out files from Documentum repositories (as well as many other tasks, such as searchingrepositories) through a combination of a .NET client assemblies and runtime services, and componentsrunning on EMC | DocumentumWDK‑based application server applications (for example, Webtop).

EMC | Documentum has used the AC SDK to create its application connectors for these MicrosoftOffice applications: Word, Excel, and PowerPoint.

ArchitectureThe AC SDK is a collection of .NET assemblies and runtime services that your application usesthrough an application connector that you develop. Your application initializes your applicationconnector, which creates a Documentum menu in your application. From that point on, users canuse the Documentum menu to check in files from their local machine into Documentum repositoriesas well as many other task, including checking out files from and searching repositories. Whenusers choose menu items or your application posts events (such as when a file is opened), logic inyour application connector is called.


Overview

Figure 1, page 12 shows that your application uses the AC SDK in the same way that Excel, Word, andPowerPoint use the AC SDK. That is, the AC SDK is a generic layer of code that both your applicationconnector and each Microsoft Office application connector use.

Figure 1. Application Connectors SDK Architecture

Figure 2, page 12 shows that when your application needs to manipulate files in a repository, it callsthe application connector you created, which then calls Webtop, which then calls the repository.

Figure 2. Application Connector, Webtop, Repository Relationship

Figure 3, page 13 shows that the AC SDK depends on the .NET framework; it also shows that the ACSDK consists of runtime assemblies and runtime services:


Overview

Figure 3. AC SDK .NET Runtime Assemblies and Runtime Service Structure

For more informationFor information about configuring and customizing WDK and WDK applications, see the WebDevelopment Kit Development Guide.

For information about .NET development, see the Microsoft .NET Framework Developer Center.


http://msdn.microsoft.com/netframework/

Overview


Chapter 2Installing and Setting Up the ApplicationConnectors Software Development Kit

For hardware and software requirements, see the Application Connectors SDK Installation and ReleaseNotes.

Installing the Application Connectors SDKTo install the AC SDK:

1. Double‑click the EMC Documentum Application Connectors SDK.msi file and follow theinstructions.

Installed folders and files.NET assemblies, supporting DLLs and runtime services that are shared across all installed applicationconnectors are, by default, installed in:C:\Program Files\Documentum\AppConnector

These AC SDK runtime services are installed.• Authentication Service• Event Server• Locale ManagerThe Authentication Service and Locale Manager processes are automatically started after installationcompletes. To view these processes, open the Task Manager’s Processes tab. The Event Server isstarted when an application connector is initialized.

To support application connector development, another set of .NET assemblies and supporting DLLsare installed, by default, into:C:\Program Files\EMC Documentum Application Connectors SDK 6.0


Installing and Setting Up the Application Connectors Software Development Kit

This folder contains the sample applications’ executables, assemblies, configuration files, and manifestfiles. It also contains these subfolders:• Developer Help: contains the Application Connectors SDK Reference Guide and the Application

Connectors SDK Development Guide.• Documentum: contains private assemblies and DLLs used by the application implementing

application connectors (which, in this case, is the sample application).• Source: contains the sample applications’ Visual Studio.NET solution.

To test your installation:

1. Double‑click the sample application executable.

2. Choose Documentum > Preferences.

3. On the Preferences dialog box’s General tab, type the URL to a Webtop installation in yourcompany.

Note: TheWebtop URL is saved to the application connector’s app.config filein the <host> element.

For example:

<wdkAppLocalSettings version="1.0"><wdkAppLocalInfo... ><host>http://webtop_machine:8100/webtop</host>...

</wdkAppLocalSettings>

4. To log into a Documentum repository, choose Documentum > Login As and enter your username, password, and domain (if required).

5. To open a repository file, choose Documentum > Open.If you can successfully log in to a repository and open a file, then you have successfully installed theApplication Connectors SDK.


Chapter 3Quick Start

These topics are included:• General procedure for creating and integrating an application connector with your application,

page 17• Creating an application connector, page 19• Initializing and cleaning up your application connector, page 21• Calling the application connector from your application, page 23

General procedure for creating and integratingan application connector with your applicationTo create and integrate an application connector with your application:

1. To create your application connector, create a new .NET assembly with these classes:• MyAppIntegrationProvider derive it from the AppIntegrationProviderBase class and implement

all of the AppIntegrationProviderBase class’s abstract methods and properties.• MyMenuProvider derive it from the MenuProviderBase class and implement all of the

MenuProviderBase class’s abstract methods.• MyConnect implement logic for initialization and cleanup of the application connector.You can use your own names in place of the MyAppIntegrationProvider, MyMenuProvider,MyConnect class names.See Creating an application connector, page 19 and Initializing and cleaning up your applicationconnector, page 21.

2. In the appropriate locations in your application, call the initialization and cleanup methods inyour MyConnect class.

3. Copy the TextEditorApp.exe.config file to your application executable’s directory, changethe TextEditorApp portion of TextEditorApp.exe.config to your application’s name (for


Quick Start

example, MyApp.exe.config), and specify these values for yourMyAppIntegrationProvider andMyMenuProvider classes:<appIntegrationSettings version="1.0">1 <appIntegrationInfo name="MyCompanyAppConnectorForMyApp"

2 type="IntegrationProvider,3 MyAppIntegrationProviderNamespace,4 Version=1.0.0.0,5 Culture=neutral,6 PublicKeyToken=a289a5c6e19bab4f"clientSideEventHandlers="session,notification,component"canConnectTimerDuration="7000"contentSources="webtop" >

</appIntegrationInfo></appIntegrationSettings>

...<menuSettings version="1.0">7 <menuInfo name="MyCompanyMenuProviderForMyApp"

8 type="MenuProvider,9 MyMenuProviderNamespace,10 Version=1.0.0.0,11 Culture=neutral,12 PublicKeyToken=a289a5c6e19bab4f" >

...</menuSettings>

1 MyCompanyAppConnectorForMyApp is a string that identifies yourMyAppIntegrationProvider classand matches the application connector constant value in your application connector’s constants file.For example: Documentum Application Connector for Text Editor.2 IntegrationProvider is the fully qualified (including the namespace) class name forMyAppIntegrationProvider. For example: MyCompany.AppConnector.TextEditorAppIntg.TextEditorAppIntegrationProvider.3 MpAppIntegrationProviderNamespace is the namespace ofMyAppIntegrationProvider. For example:MyCompany.AppConnector.TextEditorAppIntg

4 Version of your assembly that contains theMyAppIntegrationProvider class.5 Default culture of your assembly that contains theMyAppIntegrationProvider class defines thedefault assembly language resources that are built into the assembly.6 Your application connector assembly’s public key token that you generated using a private key.Do not use the sample application’s .sink file or the security of your application connector willbe compromised.7 MyCompanyMenuProviderForMyApp is a string that identifies yourMyMenuProvider class andmatches the menu provider constant value in your application connector’s constants file. For example:Documentum Menu System for Text Editor.8 MenuProvider is the fully qualified (including the namespace) class name forMyMenuProvider. Forexample: MyCompany.AppConnector.TextEditorAppIntg.MenuProvider.9 MyMenuProviderNamespace is the namespace of MyMenuProvider. For example:MyCompany.AppConnector.TextEditorAppIntg

10Version of your assembly that contains theMyMenuProvider class.


Quick Start

11Default culture of your assembly that contains theMyMenuProvider class.12Your application connector assembly’s public key token that you generated using a private key.Do not use the sample application’s .sink file or the security of your application connector willbe compromised.

4. Make a copy the TextEditorApp.exe.log4net.config file in the Documentum directory, change theTextEditorApp portion of its name to your application’s name, and change the param element’sfile attribute value to an appropriate log file name for your application.

5. Copy the TextEditorApp.exe.manifest file to your application executable’s directory, change theTextEditorApp portion of its name to your application’s name, and change the <description>element value to an appropriate description of your application.

6. To enable adding and removing menu items from the Documentum menu (and other scopinguses) in your application onlyand not other application connectors create a string identifyingyour application name:

a. In your app.config file, add a string identifying your application name to the<wdkAppLocalInfo> element’s <clientenv> element.For example:<wdkAppLocalInfo>...

<clientenv>MyApp</clientenv>...</wdkAppLocalInfo>

b. In the app.xml file in the webtop\wdk directory of your Webtop installation, add the sameapplication name string you specified in Step a to the <clientenv_structure> element as a<child> element of the appintg <parent> element.For example:<clientenv_structure>

<branch><parent>appintg</parent><children>

<child>MyApp</child>...

</children></branch>

...</clientenv_structure>

Creating an application connector1. Create a new application in Visual Studio.NET 2003 or any other development tool that supports

.NET 1.1 SP1‑based development.

2. Copy the Documentum folder to your application’s directory.The Documentum folder is in the AC SDK installation directory, which is, by default:


Quick Start

C:\Program Files\EMC Documentum Application Connectors SDK 5.3

3. Add references to these AC SDK assemblies:• Documentum.AppConnector.Application• Documentum.AppConnector.Application.Interfaces• Documentum.AppConnector.Logging• Documentum.AppConnector.Provider• Documentum.AppConnector.Provider.Interfaces• Documentum.AppConnector.Utility• Documentum.Interop.AdvHosting• Documentum.Interop.EventServer• log4netExcept for the Documentum.Interop.EventServer assembly, which is located in the AppConnectorfolder, all these assemblies are located in the Documentum folder of your application’s executablefolder.

4. Implement aMyConnect class that contains the application connector initialization and cleanupmethods that your application calls.See Initializing and cleaning up your application connector, page 21.

5. Implement a MyAppIntegrationProvider class that contains the core logic of your applicationconnector.See Chapter 4, Implementing Your Application Connector Provider.As a part of the initialization process, the MyAppIntegrationProvider class expects an objectthat represents your application. This object is a bridge encapsulating your editor‑specificprogramming model. For example, the Microsoft Office programming model has an Applicationobject that allows access to other objects (for instance, menu bar, open documents) and eventsthat fire based on user actions (for instance, window activate, document open, document close,new document). For a more specific example, see the TextEditorAppClass.cs and Connect.csfiles of the TextEditorApp sample application.If your application’s programming model does not have an object that represents your applicationand it is a C++ or Visual Basic 6 application, then you can use a COM bridge. See Chapter 11,Creating Application Connectors That Integrate with C++ or Visual Basic 6 Applications.

6. Implement aMyMenuProvider class that creates and manages the Documentum menu in yourapplication.See Chapter 6, Creating and Modifying the Documentum Menu.


Quick Start

Initializing and cleaning up your applicationconnectorYou create aMyConnect class that handles initializing and cleaning up your application connector.

To create a method that initializes your application connector:

1. To configure the .NET remoting service, which is required for the credential service, use theSystem.Runtime.Remoting.RemotingConfiguration.Configure method.For example:1 string configFile = System.AppDomain.CurrentDomain.

SetupInformation.ConfigurationFile;

try

// Required to communicate with Credential Service.2 System.Runtime.Remoting.RemotingConfiguration.Configure(configFile);catch (Exception ex)

logger.Fatal(".NET Remoting could not be configured: [" +ex.Message + "] " + ex.StackTrace);

return retVal;

1 The System.AppDomain.CurrentDomain.SetupInformation.ConfigurationFile .NET methodretrieves the configuration file name.2 The System.Runtime.Remoting.RemotingConfiguration.Configure .NET method configures theremoting service, which is required for the credential service.

2. Declare a method prototype that returns a Boolean indicating whether the initialization succeeded,and creates and initializes an IAppIntegrationProvider instance.For example:1 public bool InitMyAppIntegration(object parent)2 bool retVal = false;

try3 MyAppIntegrationProvider = AppIntegrationProviderManager.

Current.Create(MyAppAppConstants.INTEGRATION_WITH_MY_APP);logger.Info("Application integration provider has been

successfully created.");catch (Exception ex)

logger.Error("Application integration provider creation failed", ex);return retVal;

if (MyAppIntegrationProvider != null)


Quick Start

try4 retVal = MyAppIntegrationProvider.InitializeAppIntegration(parent);logger.Info("Application integration provider has been

successfully initialized.");catch (Exception ex)logger.Error("Failed to initialize the application integration

provider", ex);return retVal;

return retVal;

1 InitMyAppIntegration is the name of the method that initializes your application connector providerclass. The parent object represents your application object.2 Initialize the retVal variable, which represents whether the method succeeded, to False.3 To create an IAppIntegrationProvider instance, execute the Create method on the currentAppIntegrationProviderManager factory indicated by the Current property. The Create methodtakes your application connector name as a parameter. Your application connector name is specifiedas an INTEGRATION_WITH_YOUR_APP constant in yourMyAppAppConstants class for constants.The INTEGRATION_WITH_YOUR_APP constant value must be the same as the appIntegrationInfoelement’s name attribute value in your application connector’s app.config file.For example, the TextEditorAppConstants class (in the TextEditorAppConstants.cs file) has thisconstant defined:public const string INTEGRATION_WITH_TEXT_EDITOR_APP =

"Documentum Application Connector for TextEditorApp";

This constant matches the appIntegrationInfo element’s name attribute value in theTextEditorAppConnector’s app.config file:<emc.com><documentum><appConnector><actionSettings version="1.0">....</actionSettings><appIntegrationSettings version="1.0">

...<appIntegrationInfo name="Documentum Application Connector for TextEditorApp"...></appIntegrationInfo>

</appIntegrationSettings>...

</appConnector></documentum>

</emc.com>


Quick Start

4 Execute InitializeAppIntegration on your IAppIntegrationProvider instance(MyAppIntegrationProvider) to initialize your application connector.

3. To build your menu after initializing your application, call your overridden BuildMenu method.For example:try

MyAppIntegrationProvider.MenuProvider.BuildMenu(MyAppIntegrationProvider);

catch (Exception e)

logger.Error("Failed to build custom menu", e);return false;

Create a method that closes your application connector:

1. Destroy the Documentum menu, close your MyAppIntegrationProvider instance, and set theMyAppIntegrationProvider instance’s reference to null.For example:public void CloseYourAppAppIntegration()

if (MyAppAppIntegrationProvider != null)

MyAppAppIntegrationProvider.MenuProvider.DestroyMenu(false);MyAppAppIntegrationProvider.Close();MyAppAppIntegrationProvider = null;

Calling the application connector from yourapplication1. In your application, add a reference to your application connector.

2. Create an instance of theMyConnect class.

3. Implement the code to initialize your application connector when your application starts by callingyour initialization method in theMyConnect class.


Quick Start

4. Implement the code to terminate and cleanup your application connector when your applicationterminates by calling your cleanup method in theMyConnect class.


Chapter 4Implementing Your ApplicationConnector Provider

These topics are included:• General procedure for implementing your MyAppIntegrationProviderBase class, page 26• Implementing the InitializeAppIntegration method, page 26• Implementing the ActiveDocumentArguments property, page 28• Implementing the ActiveDocumentFilePath property, page 29• Implementing the ActiveDocumentModifiedSinceLastSave property, page 29• Implementing the ActiveDocumentObjectId property, page 30• Implementing the ActiveWindowHandle property, page 31• Implementing the Close method, page 31• Implementing the CloseActiveDocument method, page 32• Implementing the DefaultDocumentFormat property, page 32• Implementing the DoAbout method, page 33• Implementing the DoOpenDocument method, page 33• Implementing the MenuBar property, page 34• Implementing the OpenedRepositoryDocumentCount property, page 35• Implementing the RefreshMenu method, page 35• Implementing the SaveActiveDocument method, page 36• Implementing the ShowBusyCursor method, page 37• Implementing the ShowDefaultCursor method, page 38• Implementing the UpdateActiveDocumentArguments method, page 38


Implementing Your Application Connector Provider

General procedure for implementing yourMyAppIntegrationProviderBase classTo instantiate your application connector and respond to events:

1. You createMyAppIntegrationProvider and derive it from the AppIntegrationProviderBase class.

2. You implement these methods and properties:• ActiveDocumentArguments see Implementing the ActiveDocumentArguments property,

page 28.• ActiveDocumentFilePath see Implementing the ActiveDocumentFilePath property, page 29.• ActiveDocumentModifiedSinceLastSave see Implementing the

ActiveDocumentModifiedSinceLastSave property, page 29.• ActiveDocumentObjectId see Implementing the ActiveDocumentObjectId property, page 30.• ActiveWindowHandle see Implementing the ActiveWindowHandle property, page 31.• Close see Implementing the Close method, page 31.• CloseActiveDocument see Implementing the CloseActiveDocument method, page 32.• DefaultDocumentFormat see Implementing the DefaultDocumentFormat property, page 32.• DoAbout see Implementing the DoAbout method, page 33.• DoOpenDocument see Implementing the DoOpenDocument method, page 33.• InitializeAppIntegration see Implementing the InitializeAppIntegration method, page 26.• MenuBar see Implementing the MenuBar property, page 34.• OpenedRepositoryDocumentCount see Implementing the OpenedRepositoryDocumentCount

property, page 35.• RefreshMenu see Implementing the RefreshMenu method, page 35.• SaveActiveDocument see Implementing the SaveActiveDocument method, page 36.• ShowBusyCursor see Implementing the ShowBusyCursor method, page 37.• ShowDefaultCursor see Implementing the ShowDefaultCursor method, page 38.• UpdateActiveDocumentArguments see Implementing the UpdateActiveDocumentArguments

method, page 38.For more information about these methods and properties, see the Application Connectors SDKReference Guide.

Implementing the InitializeAppIntegrationmethodThe InitializeAppIntegration method is used to initialize your application connector.



To implement the InitializeAppIntegration method:

1. Override the InitializeAppIntegration method.

2. Make sure that the parent object passed to this method is the right kind of object.For example:if (parent is MainForm)1 this.parent = (MainForm)parent;else

logger.Error("InitializeAppIntegration parent object is not of MainForm type");

return false;

1 Casts the parent as System.Windows.Forms.ApplicationContext.MainForm.

3. Create an instance of the IMenuProvider interface by calling the MenuProviderManager class(a factory class).try1 menuManager = MenuProviderManager.Current.Create(

MyAppConstants.MYCOMPANY_MENU_SYSTEM_MY_APP);logger.Info("Menu provider has been successfully created.");

catch (Exception e)

logger.Error("Menu provider creation failed", e);return false;

1 The Current property gets the current MenuProviderManager factory; and the Create methodreturns the IMenuProvider instance. The constant that identifies the IMenuProvider interfaceis MYCOMPANY_MENU_SYSTEM_MY_APP and MyAppConstants is your constants file.TheMYCOMPANY_MENU_SYSTEM_MY_APP constant value is the same as the value of the<appIntegrationInfo> element’s name attribute in the app.config file.

4. To register for an event in which focus is changed, add code similar to this one after the end of themethod after try‑catch block in the previous step:this.parent.txt.GotFocus += new EventHandler(Txt_GotFocus);

txt is a reference to a TextBox control that contains a document. This code registers the control’sSystem.EventHandler, GotFocus (which occurs when the control receives focus), with theTxt_GotFocus EventHandler.

5. In the Private Methods region, add the Txt_GofFocus EventHandler implementation:private void Txt_GotFocus(object sender, EventArgs e)1 string objectId = ActiveDocumentObjectId;



if (objectId.Equals(""))2 this.RefreshMenu(ApplicationConstants.REPOSITORY_CONTENT, false);else3 this.RefreshMenu(ApplicationConstants.REPOSITORY_CONTENT, true);

4 this.RefreshMenu(ApplicationConstants.ANY_CONTENT, true);5 base.RefreshAiConnectionMenuItem();

1 Retrieves the object ID of the document that was opened from the EventArgs parameter.2 If the document does not have an object ID, then it is not a repository document; so the menu isrefreshed and any menu item that applies to an opened repository document is disabled.3 If the document has an object ID, then it is a repository document; so the menu is refreshed and anymenu item that applies to an opened repository document is enabled.4 Any menu item that applies to any contenteither a local or repository documentis enabled.5 Any menu item that should be available when your application is connected to a repositoryis enabled.

6. Return true after code in the previous step to indicate that an instance of the IMenuProviderinterface has been successfully created.

Implementing the ActiveDocumentArgumentspropertyThe ActiveDocumentArguments property is used to return the active document’s arguments that arepassed to your application connector when a repositoy document is opened.

To implement the ActiveDocumentArguments Property:

1. Override the ActiveDocumentArguments Property.

2. Implement a get function to return the active document’s arguments.For example:public override string ActiveDocumentArgumentsget

1 return base.GetDocumentArguments(filePath);



1 Using the AppIntegrationProviderBase GetDocumentArguments method, returns the file’sarguments based on its file’s path, filePath.filePath is a class variable that holds the file path of the active document. When a repositorydocument is opened, the application connector provider saves its path. To retrieve that value, use theAppIntegrationProviderBase GetArgumentValue method. For example:filePath = base.GetArgumentValue(eventArgs, ApplicationConstants.FILENAME_WITH_PATH);

Implementing the ActiveDocumentFilePathpropertyThe ActiveDocumentFilePath property is used to return the active document’s path.

To implement the ActiveDocumentFilePath Property:

1. Override the ActiveDocumentFilePath Property.

2. Implement a get function to return the active document’s path.For example:public override string ActiveDocumentFilePathget

1 return (filePath.Length == 0) ? documentName : filePath;

1 Returns the file’s path or its file name, if it has not been saved.filePath is a class variable that holds the file path of the active document. For more information aboutthe filePath class variable, see Implementing the ActiveDocumentArguments property, page 28.

Implementing theActiveDocumentModifiedSinceLastSavepropertyThe ActiveDocumentModifiedSinceLastSave property is used to determine whether the activedocument was modified since it was last saved.

To implement the ActiveDocumentModifiedSinceLastSave Property:

1. Override the ActiveDocumentModifiedSinceLastSave Property.



2. Implement a get function to return a Boolean value indicating whether the active document hasbeen modified.For example:public override bool ActiveDocumentModifiedSinceLastSaveget

1 return parent.dirty;

1 dirty is a variable, which represents a Boolean value, on the parent object, which represents yourapplication object. You must use a similar call that returns a Boolean that signifies whether the activedocument has been modified.

Implementing the ActiveDocumentObjectIdpropertyThe ActiveDocumentObjectId property is used to return the active documents repository object ID(r_object_id attribute value).

To implement the ActiveDocumentObjectId Property:

1. Override the ActiveDocumentObjectId Property.

2. Implement a get function to return the active documents repository object ID.For example:public override string ActiveDocumentObjectIdget1 return base.GetObjectId(filePath);

1 Using the AppIntegrationProviderBase GetObjectId method, returns the files object ID based onits files path, filePath. filePath is a class variable that holds the file path of the active document. Formore information about the filePath class variable, see Implementing the ActiveDocumentArgumentsproperty, page 28.



Implementing the ActiveWindowHandlepropertyThe ActiveWindowHandle property is used to retrieve your applications active window handle.

To implement the ActiveWindowHandle property:

1. Override the ActiveWindowHandle property.

2. Implement a get function to return your applications active window handle.For example:public override IntPtr ActiveWindowHandle

get1 return parent.Handle;

1 Handle is a variable, which represents an IntPtr (a .NET data typebasically, a raw handlewhichcould be an int or long), on the parent object; and the parent object represents your application object.You must use a call similar to this one that returns an object representing your applications activewindow handle.

Implementing the Close methodThe Close method is used to close your application.

To implement the Close method:

1. Override the Close method.

2. Call the AppIntegrationProviderBase Cleanup method to clean up resources allocated by thebase implementation classes.For example:public override void Close()

base.Cleanup();

3. Call your applications close and cleanup code after calling the AppIntegrationProviderBaseCleanup method.



Implementing the CloseActiveDocumentmethodThe CloseActiveDocument method is used to close the active document in your editor.

To implement the CloseActiveDocument method:

1. Override and implement the CloseActiveDocument method.

2. Call your applications close window code, decrement the counter that keeps track of how manyrepository documents are open, and delete the documents event arguments.For example:// Call your applications close window code here// to close the active document;

1 your_application_close_code;openedRepoDocumentCount;

2 RemoveOpenDocumentArguments(filePath);

1 Decrement the openedRepoDocumentCount variable, which keeps track of how many repositorydocuments are open in your application.2 Call the RemoveOpenDocumentArguments method passing the filePath parameter, which deletesall event arguments for the document specified by the filePath parameter.

3. If this is the last window in your application, call the RefreshMenu method and set its firstparameter to ApplicationConstants.REPOSITORY_CONTENT and the second parameter to Falseso that the menu is refreshed to disable all menu items related to repository content.For example:RefreshMenu(ApplicationConstants.REPOSITORY_CONTENT, false);

Implementing the DefaultDocumentFormatpropertyThis property is used to return the default document format for your application’s documents. Thisdefault document format must be a format (dm_format object type) that exists in the repository.

To implement the DefaultDocumentFormat Property:

1. Override the DefaultDocumentFormat Property.

2. Implement a get function to return a value.For example:public override string DefaultDocumentFormat



get

1 return "crtext";

1 Returns the text, crtext, as the default format.

Implementing the DoAbout methodThe DoAbout method is used to display your application connectors About dialog box.

When you create your application connectors About dialog box, its constructor must take the WDKapplication host name as a String parameter. For an example, see the sample application.

To implement the DoAbout method:

1. Override the DoAbout method.

2. Create an instance of your application connectors About dialog box by calling itsconstructor and passing the current WDK applications host name, and then callSystem.Windows.Forms.Form.ShowDialog method on that instance.For example:public override void DoAbout()AboutAppConnectorDialog about =

1 new AboutAppConnectorDialog(base.CurrentWdkApplication.Host);about.ShowDialog();

1 Call the AppIntegrationProviderBase CurrentWdkApplication property to return anIWdkAppLocalProvider object representing an interface to the current WDK application, and then callthe IWdkAppLocalProviders Host property to return the URL of the WDK application host.

Implementing the DoOpenDocument methodThe DoOpenDocument method is called when a document is opened in your application; that is, anopen‑document event occurs.

To implement the DoOpenDocument method:

1. Override the DoOpenDocument method.

2. Retrieve the file path of the document that was opened in your editor.



For example:filePath = base.GetArgumentValue(eventArgs,

ApplicationConstants.FILENAME_WITH_PATH);

3. Because repository documents can be opened using Webtop instead of yourapplicationconsequently, the args parameter might be emptymake sure to set thedocumentOpenedViaIntegration field in your AppIntegrationProviderBase class to true. So thatother methods can check to see if the documentOpenedViaIntegration field is False, and, if so, tocall GetLocalDocumentArguments to retrieve the document’s arguments.For example:documentOpenedViaIntegration = true;

4. Build and refresh the menu state. For example:AddOpenDocumentArguments(eventArgs);base.MenuProvider.BuildMenuState(eventArgs);RefreshMenu(ApplicationConstants.REPOSITORY_CONTENT, true);

5. Increment the variable that keeps count of the number of open repository documents. For example:openedRepoDocumentCount++;

Implementing the MenuBar propertyThe MenuBar property is used to retrieve your application’s menubar object.

To implement the MenuBar property:

1. Override the MenuBar property.

2. Implement a get function to return your application’s menubar.For example:public override object MenuBarget

1 return parent.Menu;

1 Menu is a variable, which represents an object, on the parent object; and the parent object representsyour application object. You must use a call similar to this one that returns an object representingyour application’s menubar.



Implementing theOpenedRepositoryDocumentCountpropertyThe OpenedRepositoryDocumentCount property is used to return the number of repositorydocuments that are open in your application.

To implement the OpenedRepositoryDocumentCount property:

1. Override the OpenedRepositoryDocumentCount property.

2. Implement a get function to return the number of repository documents that are open in yourapplication.For example:public override int OpenedRepositoryDocumentCountget

1 return openedRepoDocumentCount;

1 openedRepoDocumentCount is a class variable that holds the number of open repositorydocuments. This variable is incremented by 1 every time a repository document is opened (in theDoOpenDocument method) and decremented by 1 every time a repository document is closed (inthe CloseActiveDocument method).

Implementing the RefreshMenu methodThe RefreshMenu method is used to set the active window’s Documentum menu item states.

To implement the RefreshMenu method:

1. Override the RefreshMenu method.

2. Call the RefreshMenu method in your class that derives from the MenuProviderBase class.For example:public void RefreshMenu(string context, bool enabled)

1 base.MenuProvider.RefreshMenu(context, enabled);

1 base.MenuProvider returns a reference to the IMenuProvider interface type. The RefreshMenumethod is called on the IMenuProvider interface to refresh the state of the application menu bar.



MenuProvider is a property type of the AppIntegrationProviderBase base class that returns the menumanager object (IMenuProvider interface type), which implements your custom menu and handlesits events.The context parameter specifies the context (for example, a repository document) of the document towhich the menu applies. The valid values for the context parameter are specified in the <aidynamic>element of the <actionmenuitem> elements in the appintgmenubar_menugroup.xml file. The enabledparameter indicates whether the menu item is to be enabled.If you application requires actions to occur before or after the refresh, you can code those actions tooccur before or after this call.

Implementing the SaveActiveDocument methodThe SaveActiveDocument method is used to save the active document in your application to thelocal file system.

To implement the SaveActiveDocument method:

1. Override the SaveActiveDocument method.

2. Check whether the caller has specified a foldercalled the target folderin which to save thedocument.The target folder could be the current folder, in which case the caller will not have specified anyvalue for the target folder.For example:1 if (targetFolder.Length == 0)

try

2 StreamWriter sw = new System.IO.StreamWriter(filePath);sw.WriteLine(parent.txt.Text);sw.Flush();sw.Close();

3 parent.dirty = false;catch(Exception e)logger.Error("Failed to save active document", e);return string.Empty;

return filePath;4 else5 string activeDocumentName = System.IO.Path.GetFileName(filePath);if (activeDocumentName.Length == 0)

activeDocumentName = documentName;



6 filePath = System.IO.Path.Combine(targetFolder, activeDocumentName);try

StreamWriter sw = new System.IO.StreamWriter(filePath);sw.WriteLine(parent.txt.Text);sw.Flush();sw.Close();parent.dirty = false;

catch(Exception e)

logger.Error("Failed to save active document", e);return string.Empty;

7 return filePath;

1 If the length of the string value passed in the targetFolder parameter is zero, then the target folderis the current folder.2 Use the System.IO.StreamWriter object to save the active document to the path specified in thefilepath variable.3 dirty is a variable, which represents a Boolean value, on the parent object, which represents yourapplication object. You must use a similar call that returns a Boolean signifying whether the activedocument has been modified.4 Otherwise, the length of the string value passed in the targetFolder parameter is greater than zero,which indicates that a target folder was specified.5 Get the file name of the active document by calling the System.IO.Path.GetFileName methodon the filepath class variable.6 Construct the target file path for the active document by calling the System.IO.Path.Combinemethod on the targetFolder parameter and the activeDocumentName variable.7 Return the path to the saved document.

3. Since this document has just been saved, set the document’s property to be unmodified. Forexample:parent.dirty = false;

dirty is a variable, which represents a Boolean value, on the parent object, which represents yourapplication object. You must use a similar call that returns a Boolean signifying whether theactive document has been modified.

Implementing the ShowBusyCursor methodThe ShowBusyCursor method is used to display a busy cursor when an operation is in progress.



To implement the ShowBusyCursor method:

1. Override the ShowBusyCursor method, which takes a windowHandle parameter:public override void ShowBusyCursor(System.IntPtr windowHandle)

2. Call your applications busy cursor code.For example:1 parent.Cursor = System.Windows.Forms.Cursors.WaitCursor;

1 System.Windows.Forms.Curors.WaitCursor gets the busy cursor from the System.Windows.Forms.Cursors collection. The busy cursor is assigned to the parent objects cursor.

Implementing the ShowDefaultCursor methodThe ShowDefaultCursor method is used to display the default cursor.

To implement the ShowDefaultCursor method:

1. Override the ShowDefaultCursor method.

2. Call your application’s default cursor code.For example:1 parent.Cursor = System.Windows.Forms.Cursors.Default;

1 System.Windows.Forms.Cursors.Default gets the default cursor from the System.Windows.Forms.Cursors collection. The default cursor is assigned to the parent object’s cursor.

Implementing theUpdateActiveDocumentArgumentsmethodThe UpdateActiveDocumentArguments method is used to update the active document’s arguments.This method is called by the Application Connectors framework when a document’s repository statechanges (for example, after checkin).

To implement the UpdateActiveDocumentArguments method:

1. Override the UpdateActiveDocumentArguments method.



2. Call the AppIntegrationProviderBase UpdateDocumentArguments method.For example:public override void UpdateActiveDocumentArguments (string args)1 base.UpdateDocumentArguments(filePath, args);

1 filePath is a class variable that references the file path of the active document. For more informationabout the filePath class variable, see Implementing the ActiveDocumentArguments property, page 28.




Chapter 5Handling Events

These topics are described:• Overview, page 41• AppConnectorEventServer scenarios, page 43• WDK events, page 46

OverviewYour application connector and WDK application rely on your application to dispatch events. Yourapplication connector might also want to receive events from another part of the system.

The event server (EventServer.exe) contains the AppConnectorEventServer object that isresponsible for registering and unregistering client interest in events and for dispatching eventsto specific or registered client event sinks. The AppConnectorEventServer object is created inthe AppIntegrationProviderBase class during initialization and can be accessed through theNotificationServer property.

Figure 4, page 42 shows the relationship between the AppConnectorEventServer (abbreviated asʺAC Event Server), its clients, and event sinks. Each process (bounded by a dotted line) can containmultiple callers and multiple event sinks. An AppConnectorEventServer client can be a callerof its registered event sink (abbreviated as ʺES) exposing a EventSink interface to be called by aAppConnectorEventServer worker thread, or both a caller and an event sink.


Handling Events

Figure 4. Event Dispatching Interaction Diagram

When a client registers an event sink with the AppConnectorEventServer, theAppConnectorEventServer associates that sink with one or more event categories. Henceforth,the AppConnectorEventServer dispatches events to that event sink based on the event categoriesassociated with that sink. A sink can be registered and unregistered multiple times. For example, yoursink might initially be interested in only a few event categories, but once it receives a particular eventcode, the sinks interest grows and it registers for the additional categories of interest.

When an event sink is first registered with the AppConnectorEventServer, RegisterEventSink is calledand a pointer to its EventSink implementation is passed. In return, the AppConnectorEventServerreturns a cookie. This cookie should be stored as a data member by the client object. It must be passedto the AppConnectorEventServer in all subsequent calls to RegisterInterest and UnregisterInterest.You can also specify event sink cookies in both SendEvent and HandleEvent.

Types of AppConnectorEventServer‑based events are:• Notifications Sent to inform the system that a planned or unplanned event has occurred.• Cancellations Sent to inform the system that a planned event has not occurred.• Queries Sent to ask the system if a condition is true.• State transitions Sent to gather system approval for an event to occur. System elements can either

veto the state transition or approve it. Once a system element approves a state transition, it plansfor the actual event to occur (that is, puts itself into a pending state). Any event code that isassociated with a state transition event type must also be associated with both notification andcancellation event types.


Handling Events

Figure 7, page 45 and Figure 8, page 46 illustrate the connection among these event types dependingon the outcome of an event dispatch involving a state transition.

An event sink should react only to notifications and cancellations it receives. Therefore, theAppConnectorEventServer returns back to its caller following the creation of worker threads,regardless of the interaction between a worker thread and its subject event sink interface. As a result,callers dispatching notifications or cancellations should not assume that the broadcast has fullycompleted (or even begun) before control returns to it from the AppConnectorEventServer.

AppConnectorEventServer clients can expect the standard response message format returned byAppConnectorEventServer from SendEvent to be: ʺ[who] what (for example, ʺ[Microsoft Word] did notrespond in time to the specified event.). The AppConnectorEventServer establishes who from the sinkname provided previously in RegisterEventSink. The sinkName parameter should have the same valueas the Name property of the event sink being registered. If the response is internal or no sink name hasbeen provided, who would become ʺDocumentum AppConnectorEventServer. what is establishedeither through the response string of the driving event sink or by the AppConnectorEventServer itself.For example, if a state transition times out, the AppConnectorEventServer would define what to beʺdid not respond in time to the specified event..

AppConnectorEventServer scenariosThe diagrams in this section illustrate the flow of control between a client, theAppConnectorEventServer, and registered event sinks during a broadcast event. Although there aremore variations than those represented here, you should be able to deduce how the flows operate inother variations based on these diagrams.

SendEvent expects an input Long value for pid. Pid should be set by the caller to its process ID viathe Win32 API GetCurrentProcessId. The AppConnectorEventServer passes pid from SendEvent tothe HandleEvent method of the appropriate event sinks. A signaled event sink can then comparethe incoming pid with its own process ID to see if the event came from the same process. Suchinformation is usefulfor example, if process‑specific caching is involved. All event sinks as well as theAppConnectorEventServer expose read‑only PID properties that allow other elements of the eventdispatching system to learn more about current system process distribution.

Unanswered broadcast query event dispatch flow

This section describes the flow of an unanswered (false) return to a broadcast query.


Handling Events

Figure 5. Unanswered Broadcast Query Event Dispatch Flow

Key points from Figure 5, page 44 are:• Event sinks answering false to a query should set their HandleEvent response output parameter to

VARIANT_FALSE (False) before returning from HandleEvent.• AppConnectorEventServer continues its broadcast until a sink answers true.

— AppConnectorEventServer manages timeouts only to keep the ball rolling.

— Upon timeout detection, the AppConnectorEventServer no longer waits on the offendingevent sink. That is, the AppConnectorEventServer is not at the mercy of ill‑behaved sinks.

• The Client should react based on SendEvent’s rv output. rv should always equal VARIANT_FALSE(False) in this broadcast case. The Client might optionally use responseMsg.

Answered broadcast query event dispatch flow

This section describes the flow of an answered (true) return to a broadcast query.

Figure 6. Answered (True) Broadcast Query Event Dispatch Flow

Key points from Figure 6, page 44 are:• Sink2 answers true to the query by setting its HandleEvent response output parameter to

VARIANT_TRUE (True) before returning from HandleEvent. Sink2 might also optionally defineresponseMsg for the Client to display additional information.


Handling Events

• AppConnectorEventServer stops its broadcast upon finding an answer of true and immediatelyreturns information defined by Sink2 to the Clientresponse (HandleEvent) becomes rv(SendEvent).

• The Client should react based on SendEvent’s rv output. The Client might optionally useresponseMsg.

• Although Sink3 was not asked, it could have also answered true for this event.

Approved state transition broadcast event dispatch flow

This section describes the flow of an approved state transition broadcast event.

Figure 7. Approved State Transition Broadcast Event Dispatch Flow

Key points from Figure 7, page 45 are:• Event sinks granting permission to transition their state should enter their own pending mode and

set response to VARIANT_TRUE (True) before returning from HandleEvent.• AppConnectorEventServer continues its broadcast until someone vetoes the event. Timeouts are

treated as implicit vetoes.• Based on SendEvent’s rv output of VARIANT_TRUE, the Client should perform its operation

and then call SendEvent specifying the same event code as the original state transition but sentthis time as a notification

• Follow‑up notification initiated by the Client allows each sink to clear its pending mode (whichindicates that the event has indeed occurred).


Handling Events

Vetoed state transition broadcast event dispatch flow

This section describes the flow of an implicitly or explicitly vetoed state transition broadcast event.

Figure 8. Vetoed State Transition Broadcast Event Dispatch Flow

Key points from Figure 8, page 46 are:• Sink2 vetoes the state transition. It could have done so explicitly by setting response to

VARIANT_FALSE (False) before returning from HandleEvent or implicitly by not returning fromHandleEvent before the AppConnectorEventServer times out on its HandleEvent call.

• AppConnectorEventServer stops its broadcast upon encountering a veto (explicit or implicit).• Upon timeout detection, the AppConnectorEventServer no longer waits on the offending event

sink. That is, the AppConnectorEventServer is not at the mercy of ill‑behaved sinks.• For each contacted event subscriber, AppConnectorEventServer invokes its HandleEvent method

with the same event code as the original state transition but sent this time as a cancellation.• Follow‑up cancellation initiated by AppConnectorEventServer allows each sink to clear its

pending mode (which indicates that the event has indeed not occurred).• After the second broadcast, AppConnectorEventServer returns information defined by Sink2 to

the Clientresponse (HandleEvent) becomes rv (SendEvent).• Based on SendEvent’s rv output of VARIANT_FALSE (False), the Client should not perform its

operation. It could optionally use responseMsg to return a reason to its user.• Although not asked, Sink3 could have also vetoed this state transition (explicitly or implicitly).

WDK eventsThe browser control registers an event listener to respond to WDK component client events.

WDK components generate events for AppConnectors. The firing of events are configured in the JSPpage using control tags. Thse types of WDK events can be fired:


Handling Events

• Browser events, which communicate client‑side JavaScript execution• WDK action completion events, which communicate server‑side state changesThe following controls fire AppConnectors browser events:• <dmf:body showdialogevent=true...>

Fires the showdialogevent when a JSP page is rendered, to open a modal dialog window in theclient application and display the component or container start page. This event is not neededin the component JSP page if the container JSP page fires the event. For example, refer to/wdk/system/changepassword/changepassword.jsp.

• <dmf:fireclientevent>

Fires a client event on page rendering that is handled on the client. For events that are handled byAppConnectors, an aiEvent is fired and passed to the AppConnectors. The actual event nameis passed in a <dmf:argument> element that is contained within <dmf:fireclientevent>. TheAppConnectors handle the event in the Windows client application.

• <dmf:firepresubmitclientevent>

Fires an aiEvent before submitting the control onclick event to the server.Application event handlers for showdialogevent and aiEvent are defined in a .js file. The file isincluded in the JSP page as follows:<script language="JavaScript" src="<%=strContextPath%>/wdk/include/appintgevents.js">

</script>

The following action completion events can be fired by WDK components:• Success: LoginSuccess, CheckinSuccess, CheckoutSuccess• ShowMessage• OpenDocument: arguments filenamewithpath, object Id, objectType, contentType, lockOwner,

folderId, actionMap


Handling Events


Chapter 6Creating and Modifying theDocumentum Menu

These topics are included:• Introduction, page 49• Building the Documentum menu, page 52• Removing menu items from all applications, page 62• Modifying menu items for all applications, page 63• Adding custom menu items to all applications, page 65• Restricting menu items to specific applications, page 65

IntroductionIn your application, you create a Documentummenu with menu items that perform functions to accessobjects in repositories. The AC SDK provides a standard Documentum menu as shown in Figure 9,page 51. You can remove and modify these standard menu items as well as add your own custommenu items. Standard menu items and their functions include:• New from Template: Create a new file from a template stored in a repository.• Open: Open an object from a repository.• Save: Save the updated document to the repository but keep the document checked out.• Save As: Save a file with a different name or to a different location.• Search Repositories: Search a repository.• Properties: Display the attributes of an object.• Locations: Display the locations of an object in a repository.• Versions: Display all the versions of an object in a repository.• Renditions: Display all the renditions of an object in a repository.• Lifecycle > Promote: Moves a file to the next state in a lifecycle.


Creating and Modifying the Documentum Menu

• Lifecycle > Demote: Moves a file back to the previous state in a lifecycle.• Lifecycle > Attach: Adds a file to the initial state in a lifecycle.• Lifecycle > Suspend: Pauses a file in a lifecycle by moving it to a Suspend state.• Lifecycle > Detach: Removes a file from a lifecycle.• Lifecycle > Resume: Restarts a file in a lifecycle by moving it from the Suspend state to the state

it was in before it was suspended.• Cancel Checkout: Cancel checkout of an object (unlock).• Send to > Quick Flow: Send file to a distribution list.• Send > Email Recipient as Web Link: Send file to single user (using a locator).• Send to >Workflow: Start a workflow and attach the file.• Login As: Log in to a repository.• Logout: Log out of a repository.• Help: Display online help for your application connector.• Preferences: Set application connector preferences for a user.• About Application Connector: Display your application connector’s product and version

information.• Run Query: Run a DQL query.



Figure 9. Application Connector standard Documentum menu

The Documentum menu is constructed from a global menu, which is configured from yourapplication connector’s app.config file, and the application connector menu definition file,appintgmenubar_menugroup.xml file, which resides in Webtop (and which is included with theApplication Connectors SDK, for your convenience). At runtime, the appintgmenubar_menugroup.xmlfile is downloaded to the local machine when your application connector is initialized and is updatedon demand; that is, the appintgmenubar_menugroup.xml file is downloaded whenever its contentchanges.

When a user chooses a menu item, a native modal dialog window that hosts a browsercontrol is launched and the corresponding WDK component or action specified in theappintgmenubar_menugroup.xml file is called. The browser control loads an action URL for theselected menu item. This URL consists of action ID, clientenv qualifer, theme, and repository.

Webtop uploads an action map each time a repository document is opened. The action map is based onthe user session and the selected object. This action map enables or disables menu items based on theuser context. This dynamic menu structure is stored in client memory and is not persisted on the client.



• To build and add the Documentum menu to your application, see Building the Documentummenu, page 52.

• To remove menu items from the Documentum menu, see Removing menu items from allapplications, page 62.

• To modify menu items on the Documentum menu, see Modifying menu items for all applications,page 63.

• To add custom menu items to the Documentum menu, see Adding custom menu items to allapplications, page 65

• To add or remove menu items to and from specific applications only, and apply menu itemmodifications to specific applications only, see Restricting menu items to specific applications,page 65.

Building the Documentum menuYou build the Documentum menu by subclassing the MenuProviderBase class and implementingits abstract methods.

To build the Documentum menu:

1. Subclass the MenuProviderBase class.For example:public class MyMenuProvider : MenuProviderBase

whereMyMenuProvider is the name of your class.You will need to write less code by subclassing the MenuProviderBase class, because theMenuProviderBase class implements many of the members of the IMenuProvider interface.

2. Add these Using statements:using System;using log4net;using System.Text;using System.Windows.Forms;using System.Collections;using System.Diagnostics;using System.Runtime.InteropServices;using System.Xml;using System.IO;

using Documentum.AppConnector.Application;using Documentum.AppConnector.Logging;using Documentum.Interop.EventServer;using Documentum.AppConnector.Utility;

3. InMyMenuProvider, override and implement these abstract methods from the MenuProviderBaseclass (see the corresponding section for instructions on implementing each method):



• BuildMenu: Builds the custom menu bar.

See Implementing the BuildMenu method, page 53.• BuildMenuState: Builds the data structure that represents menu item states for a newly

opened repository file.

See Implementing the BuildMenuState method, page 56.• DestroyMenu: Destroys the custom menu bar.

See Implementing the DestroyMenu method, page 59.• DestroyMenuState: Destroys menu item states associated with a file being closed.

See Implementing the DestroyMenuState method, page 59.• RebuildMenu: Rebuilds the menu from the updated application server side menu definition

file.

See Implementing the RebuildMenu method, page 60.• RebuildMenuState: Rebuilds menu item states associated with a particular file.

See Implementing the RebuildMenu method, page 60.• RefreshMenu: Refreshes the state of the custom menu items.

See Implementing the RefreshMenu method, page 61.For more information about these methods and properties, see the Application Connectors SDKReference Guide.

4. Modify the appintgmenubar_menugroup.xml file to add any of your own custom menu items,and modify or delete existing ones.• To delete existing menu items, see Removing menu items from all applications, page 62.• To add menu items, see Modifying menu items for all applications, page 63.• To modify menu items, see Adding custom menu items to all applications, page 65.• To restrict menu items to specific applications, see Restricting menu items to specific

applications, page 65.

Implementing the BuildMenu method

You implement the BuildMenu method to create the Documentum menu in your application.

To override and implement the BuildMenu method:

1. Make sure that the object passed to the method is an instance of IAppIntegrationProvider, andinitialize the data structure that holds menu definition information.For example:1 if (integrationProvider is IAppIntegrationProvider)



base.integrationProvider =

(IAppIntegrationProvider)integrationProvider;else

logger.Error("MenuProvider::BuildMenu parent object does not implement IAppIntegrationProvider interface");

return;

2 base.InitMenuInfoList();

1 Checks to make sure that the object passed to the method is an IAppIntegrationProvider object.2 Calls the InitMenuInfoList method in MenuProviderBase class to initialize the menu provider.

2. Retrieve the integrationProvider.MenuBar object and convert it to a menu data structure thatyour application can manage.For example, this code sample converts the menu data structure to a Windows form menu datastructure:1 if (base.integrationProvider.MenuBar is System.Windows.Forms.MainMenu)2 mainMenuBar = (System.Windows.Forms.MainMenu)

(base.integrationProvider).MenuBar;

1 The base MenuBar object is checked to see if it is a System.Windows.Forms.MainMenu object,which represents the menu structure of a form.2 The MenuBar is cast to System.Windows.Forms.MainMenu and a reference, mainMenuBar, iscreated.

3. Because the menu data structure is a linklist, use array logic to build the individual menu items.For example, you can cast each array item in the menu data structure instance, menuInfoList, to aMenuInfo object. The first array item is the top‑level main menu item (for example, Documentum):menuInfo = (MenuInfo)menuInfoList[0];

4. After building the first menu item, add the rest of the menu items using a loop.Each MenuInfo object has properties that are mapped to the <actionmenuitem> element’s childelements in appintgmenubar_menugroup.xml. For example, the menuCaption property ismapped to the <actionmenuitem> element’s <value> element.For example:for (int i = 1 ; i < menuInfoList.Count ; i++)

1 int parentIndex = GetParentIndex(i);

if (parentIndex == 1)

logger.Error("TextEditorApp::BuildMenu



did not find parent index.");return;

menuInfo = (MenuInfo)menuInfoList[i];if (menuInfo.enabledContext.Equals(ApplicationConstants.CONTENT_SOURCE))

continue;

MenuInfo parentMenuInfo = (MenuInfo)menuInfoList[parentIndex];

if (parentMenuInfo.menuCaption.Equals(ApplicationConstants.COMPANY_MENU_CAPTION))

2 MenuItemWithId menuItem = new MenuItemWithId(menuInfo.menuCaption);

menuItem.MenuId = menuInfo.menuId;

if (separatorIndex < menuInfo.group)

topLevelPopupMenuItem.MenuItems.Add("");

separatorIndex = menuInfo.group;

topLevelPopupMenuItem.MenuItems.Add(menuItem);if (menuInfo.isPopUpMenu == false)

3 menuItem.Click += new EventHandler(MenuItem_Click);

else

for (int j = 0 ; j < topLevelPopupMenuItem.MenuItems.Count ; j++)

MenuItem menuItem = topLevelPopupMenuItem.MenuItems[j];if (menuItem is MenuItemWithId)

MenuItemWithId menuItemWithId = (MenuItemWithId)menuItem;if (menuItemWithId.MenuId == menuInfo.parentMenu)

MenuItemWithId newMenuItemWithId = newMenuItemWithId(menuInfo.menuCaption);

newMenuItemWithId.MenuId = menuInfo.menuId;menuItem.MenuItems.Add(newMenuItemWithId);if (menuInfo.isPopUpMenu == false)

newMenuItemWithId.Click += new EventHandler(MenuItem_Click);



1 GetParentIndex method is a private method that returns the index of the parent menu item basedon the child menu item.2 The MenuItemWithId class is a private data structure that represents a menu item based on a menuitem ID and that includes a caption as a property.3 The MenuItem_Click event handler is a private event handler that responds to a menu item click.The MenuItem_Click event handler calls the IAppIntegrationProvider.Navigate method to display theappropriate dialog based on the URL.

5. To specify each menu items initial state (that is, enabled or disabled), call your overriddenRefreshMenu method and pass an appropriate context value (specified in the <aidynamic>element in appintgmenubar_menugroup.xml).For example, if your application starts up with a new file, make this method call:RefreshMenu(ApplicationConstants.ANY_CONTENT, true);

Calling RefreshMenu with these parameters enables all menu items that have<aidynamic>any_content</aidynamic> specified.If a user closes all documents and your application just displays the main frame window, makethis method call:RefreshMenu(ApplicationConstants.ANY_CONTENT, false);

Calling RefreshMenu with these parameters disables all menu items that have<aidynamic>any_content</aidynamic> defined.If a user opens a document from a repository, make this method call:RefreshMenu(ApplicationConstants.REPOSITORY_CONTENT, true);

Calling RefreshMenu with these parameters enables all menu items that have<aidynamic>repository_content</aidynamic> specified.

Implementing the BuildMenuState method

You implement the BuildMenuState method to hold menu state for a repository document. Forexample, when a document is opened from a repository, you build and store the menu state forthis document.

To override and implement the BuildMenuState method:

1. Override the BuildMenuState method, which takes this parameter:• args: argument list that is passed by the application server when a new repository document

is opened.

2. Use a menuStateHashtable object that had been created in the base class.Since your application’s menu is global for all open documents (assuming your application canhave multiple document windows open at the same time), you need to use a menuStateHashTableobject (a hash table) to keep the association between each open repository document and thecorresponding custom menu bar state. A unique key identifies the document with which the



menu item states are associated. Some suggestions for the key are: the document’s file name andpath or the window handle.For example:string invocationItem = "";ArrayList menuList = new ArrayList();1 ArrayList menuItemStateList = (ArrayList)menuStateHashtable[

ApplicationConstants.DEFAULT_KEY];2 string actionMap = integrationProvider.GetArgumentValue(

args,ApplicationConstants.ACTION_MAP);

string[] actionMapArray = actionMap.Split("|".ToCharArray());

//Format the file path which will be used as//unique key for menuStateHashtable.3 string filePath = integrationProvider.GetArgumentValue(

args,ApplicationConstants.FILENAME_WITH_PATH);

string key = StripSeparatorsAndMakeLowercase(filePath);//Create a new menuItemStateList that is subset of the default one //only items relevant to//repository content. Set the state of its menu items based on actionMap//and add it to the hashtable.4 for (int i = 0; i < menuItemStateList.Count; i++)5 MenuItemState temp = (MenuItemState)menuItemStateList[i];

if (temp.enabledContext.Equals(ApplicationConstants.REPOSITORY_CONTENT))

6 MenuItemState itemState = new MenuItemState();itemState.menuId = temp.menuId;itemState.menuCaption = temp.menuCaption;itemState.enabledContext = temp.enabledContext;itemState.visible = temp.visible;itemState.action = temp.action;itemState.component = temp.component;

7 if (itemState.action.Equals(""))

if (itemState.component != "")

invocationItem = itemState.component;

else

invocationItem = itemState.action;

if (invocationItem != "")

for (int j = 0; j < actionMapArray.Length; j++)

if (actionMapArray[j].Trim().IndexOf(invocationItem) > 1)string[] actionMapItemArray = actionMapArray[j].Split(



"~".ToCharArray());if (actionMapItemArray.Length > 1)8 if (actionMapItemArray[1].Equals(ApplicationConstants.VALID))

itemState.itemEnabled = true;else

itemState.itemEnabled = false;

break;

menuList.Add(itemState);

1 Creates an array list, menuItemStateList, from menuStateHashtable. The ApplicationConstants.DEFAULT_KEY constant represents the menu state of non‑repository documents. When a newdocument is created or an existing document is opend from the local file system, the menu item state isrepresented by a list stored in menuStateHashtable under the ApplicationConstants.DEFAULT_KEYconstant key.2 Retrieves the actionMap value from the integration provider using GetArgumentValue.3 Retrieves the name of and path to the file on the local machine.4 Starts the loop.5 Assigns each menu item’s state to a temporary MenuItemState object, temp.6 Creates a new MenuItemState object,, itemState, to hold the repository‑related values for a menuitem’s state. The following six lines add values from the temp object to the itemState object.7 This conditional statement checks to see if the menu item calls a component or action, because youdo not need to change the state of menu items that perform local functions.8 This conditional statement checks whether the 1 position in the actionMap is equal to theApplicationConstants.VALID constant; if it is, then the menu item is enabled; if not, then the menuitem is disabled..

3. Update the key and its associated object if the key exists.For example, this code sample removes the key and its associated object if it exists in the hash tableand then adds the new one and its associated objectwhich results in an update:1 if (menuStateHashtable.ContainsKey(key))2 menuStateHashtable.Remove(key);3 menuStateHashtable.Add(key, menuList);

1 ContainsKey checks to see if the key is in the hash table.2 If the key exists in the hash table, then call Remove to delete the specified key from the hash table.3 Add inserts the key; this call always executes.



Implementing the DestroyMenu method

You implement the DestroyMenu method to destroy the Documentum menu. You would want tocall this method when a document in your application closesif your application can have multipledocuments open at the same timeor your application (and hence your application connector) quits.You would also want to call this method when the menu definition file changes but before buildingthe new, updated menu bar.

To override and implement the DestroyMenu method:

1. Override the DestroyMenu method, which takes this parameter:• keepTopMenu: (True) whether to keep the top‑level menu item, which is usually,

Documentum, or (False) delete it.

2. Use your application’s programming model to destroy the Documentum menu.For example, the TextEditorAppConnector overrides the DestroyMenu method as follows:try

1 while (topLevelPopupMenuItem.MenuItems.Count > 0)

topLevelPopupMenuItem.MenuItems.RemoveAt(0);

2 if (keepTopMenu == false)

mainMenuBar.MenuItems.Remove(topLevelPopupMenuItem);topLevelPopupMenuItem = null;

3 menuInfoList.Clear();

1 Delete the menu item at the 0 index location until there are no more menu items on theDocumentum menu.2 After deleting all the menu items from the Documentummenu, delete the Documentummenu item.3 Cleans up an internal data structure that contains the menu bar information. This data structure isused when building the menu.

Implementing the DestroyMenuState method

You implement the DestroyMenuState method to destroy a menu’s menu item states by themenuStateHashtable key. For example, you would call this method when you close a documentwindow.



To override and implement the DestroyMenuState method:

1. Override the DestroyMenuState method, which takes this parameter:• key: specifies the menuStateHashtable table key that specifies the menu state to delete.

2. Call the Remove method (which is part of .NET) on the key for the menuStateHashtable.For example:menuStateHashtable.Remove(StripSeparatorsAndMakeLowercase(key));

The StripSeparatorsAndMakeLowercase method is a private utility method that makes key valuessimpler by making it lowercase and deleting all the forward and double backward slashes. See theTextEditorApp sample application source code for the exact implementation.

Implementing the RebuildMenu method

You implement the RebuildMenu method to rebuild the Documentum menu; for example, youwould want to rebuild the Documentum menu when a new appintgmenubar_menugroup.xml file isdownloaded from Webtop.

To override implement the RebuildMenu method:

1. Override the RebuildMenu method, which takes these parameters:• menuMap: the name that identifies the XML menu structure in memory.• updateMenuDefinitionFile whether the local copy of the appintgmenubar_menugroup.xml

configuration file is to be updated.

2. To update the local copy of appintgmenubar_menugroup.xml configuration file with one fromWebtop, call the private method, UpdateMenuDefinitionFile, then send and event notificationto other open applications so that they can update their Documentum menu with the updatedappintgmenubar_menugroup.xml configuration file.

3. To destroy the current menu, call DestroyMenu with a parameter value of true.

4. To build the new menu, call BuildMenu with a parameter value of integrationProvider, which is areference to an instance of IAppIntegrationProvider.

5. To rebuild the menu state for all open documents, call GetOpenedDocumentsArguments onintegrationProvider, and then BuildMenuState for each open document.

6. To refresh the menu state, call RefreshMenu with the parameter values (assuming that a file hasalready been checked out of a repository): ApplicationConstants.REPOSITORY_CONTENT, true.



Implementing the RefreshMenu method

You implement the RefreshMenu method to refresh the Documentum menu. For example, you wouldwant to call the RefreshMenu method when you switch document windows.

To override and implement the RefreshMenu method:

1. Override the RefreshMenu method, which takes these parameters:• context: the context in which the refresh is to take place; for example, when

a file has been checked out from a repository, you would set the context toApplicationConstants.REPOSITORY_CONTENT.

• enabled whether the state of menu items is to be enabled or disabled.

2. Use switch/case logic to iterate through the menu state hash table and set the state of menu itemsdepending on the context.The parameters passed to the method are the context of the document state and whether themenus in that state are to be enabled or disabled.For example, when a file has been checked out from a repository, you want to enablemenu items (for example, check in) that interact with the repository. So, you passthe ApplicationConstants.REPOSITORY_CONTENT value in the context parameterand TRUE in the enabled parameter. In the switch/case logic, you have a case forApplicationConstants.REPOSITORY_CONTENT that enables any menu item that has anenabledContext value of ApplicationConstants.REPOSITORY_CONTENT:switch (context)

case ApplicationConstants.REPOSITORY_CONTENT:

1 if (enabled == false)2 menuItemStateList = (ArrayList)menuStateHashtable[

ApplicationConstants.DEFAULT_KEY];for (int i = 0; i < menuItemStateList.Count; i ++)

menuItemState = (MenuItemState)menuItemStateList[i];3 if (menuItemState.enabledContext.Equals(context))4 MenuItem button = FindMenuButton(

topLevelPopupMenuItem, menuItemState.menuId);if (button != null)5 button.Enabled = false;button.Visible = menuItemState.visible;

6 else7 string filePath = integrationProvider.GetArgumentValue(

integrationProvider.ActiveDocumentArguments,



ApplicationConstants.FILENAME_WITH_PATH);8 string key = StripSeparatorsAndMakeLowercase(filePath);if (key != string.Empty)

menuItemStateList = (ArrayList)menuStateHashtable[key];for (int i = 0; i < menuItemStateList.Count; i++)

menuItemState = (MenuItemState)menuItemStateList[i];if (menuItemState.enabledContext.Equals(context))

MenuItem button = FindMenuButton(topLevelPopupMenuItem,menuItemState.menuId);

if (button != null)

button.Enabled = menuItemState.itemEnabled;button.Visible = menuItemState.visible;

...

1 Checks whether the enabled parameter value is false.2 Calls the menu state hash table.3 Checks whether the context within which the menu item is enabled is the same as the currentcontext, that is, ApplicationConstants.REPOSITORY_CONTENT.4 FindMenuButton is a private method that returns a MenuItemWithId object based on the menuitem ID and its parent index.5 The menu item is disabled. The button object is a .NET object that represents a menu item.6 Otherwise, the enabled parameter value is true.7 Retrieve the file name and path to the active document, which is used as the key in the menustate hash table.8 StripSeparatorsAndMakeLowercase is a private method that strips out the forward slashes andback slashes from a path and makes all the characters lowercase.

Removing menu items from all applicationsTo remove a menu item from all applications:

1. On the Webtop application server machine, copy the /webcomponent/config/library/appintgmenubar/appintgmenubar_menugroup.xml file to the Webtop custom/config directory.

2. In the Webtop custom/config/appintgmenubar_menugroup.xml, extend the original file by usingthe extends attribute on the <menugroup> element:<menugroup id="appintgmenubar" version="latest"extends="appintgmenubar:/webcomponent/config/library/appintgmenubar



/appintgmenubar_menugroup.xml">

3. To remove a menu item for all applications, in the Webtop custom/config/appintgmenubar_menugroup.xml, delete the <actionmenuitem> element.You can identify the menu item by finding the same string in <menuitem> element’s child <value>element as the menu item name displayed on the menu.

4. Save the Webtop custom/config/appintgmenubar_menugroup.xml file.

5. Restart the application server and your client application.

Modifying menu items for all applicationsTo modify menu items that call application connector components and actions in Webtop, you modifyelements and attributes in a <menugroup> element in /webcomponent/config/library/appintgmenubar/appintgmenubar_menugroup.xml. Table 1, page 63 describes the appintgmenubar_menugroup.xmlfile’s elements.

Note: Each action or component in the menu definition (that is, the value of the <action> or<component> element) can have a corresponding dispatch <item> element in the appintgcontrollercomponent definition that provides a specific success or failure page. If the menu item does not havean entry in the appintgcontroller component definition, the default success and failure pages are used.

Table 1. Application Connectors menu configuration elements

Element Description

<menugroup> Content authoring application menu item group.The id attribute specifies the menu configurationID. Contains one <contentsourcemenuitem>,one or more <actionmenuitem>, <nlsbundle>,and optional <menu> and <menuseparator/>elements.

<contentsourcemenuitem> Not used

<contentsourcemenuitem><value> Not used

<menuseparator/> Displays a separator between menu items

<menu> Optional. Set of <actionmenuitem> elements thatform a submenu for the <menu> item. To removean entire submenu, remove the <menu> element.



Element Description

<actionmenuitem> Content authoring application menu itemthat contains <aidynamic>, <name>, <value>,and either <action> or <component> plusoptional elements that are described below. Toremove an item from the menu, remove the<actionmenuitem> element.

<nlsid> Optional key to a localized label

<aidynamic> Specifies the way in which the state of theauthoring application affects the menu item:• no_dynamic: item always available• aiconnection: item enabled if connected torepository

• any_content: item enabled if repository orexternal document is open

• repository_content: item enabled if repositorycontent is open

<name> Specifies the menu item name

<value> Contains a string value or <nlsid> element thatresolves a string label for the menu item

<action> Maps a menu item to a WDK action. Either<action> or <component> must be present in the<actionmenuitem> element.

<component> Maps a menu item to a WDK component. Either<action> or <component> must be present in the<actionmenuitem> element.

<arguments><argument> The values of the name and value attributeon the <argument> element are passed to theWDK action. The name must be a definedparameter for the action, and the value must bea valid value for that parameter. This parametercan have a hardcoded value (for example,startworkflowdrilldown, or a dynamic value,indicated by the string, contextvalue, whichwill be substituted at runtime with the validcontext value.



Adding custom menu items to all applicationsTo add a custom menu item:


2. In the Webtop custom/config/appintgmenubar_menugroup.xml, extend the original file by usingthe extends attribute on the <menugroup> element:<menugroup id="appintgmenubar" version="latest"extends="appintgmenubar:/webcomponent/config/library/appintgmenubar/appintgmenubar_menugroup.xml">

3. Add an <actionmenuitem> element in the desired location in the appintgmenubar_menugroup.xmlfile.See Table 1, page 63 for a description of the child elements that comprise the <actionmenuitem>element.

4. Save the appintgmenubar_menugroup.xml file.


Restricting menu items to specific applicationsYou can restrict menu items to specific applicationsthat is, remove them from or add them to specificapplications.

For example, if your users use lifecycles for Word documents, but not for Excel and PowerPointdocuments, then you can remove the Lifecycle menu items from Microsoft Excel and PowerPoint, butkeep it in Microsoft Word.

To restrict a menu item to specific applications:


2. In the Webtop custom/config/appintgmenubar_menugroup.xml, extend the original file by usingthe extends attribute on the <menugroup> element:<menugroup id="appintgmenubar" version="latest"extends="appintgmenubar:/webcomponent/config/library/appintgmenubar/appintgmenubar_menugroup.xml">

3. To find the available application name strings for the Webtop installation, find the appintg<parent> element in the <clientenv> element in the app.xml file in the webtop\wdk directory ofyour Webtop installation.



If you have not created an application name string for your application, add it using the Generalprocedure for creating and integrating an application connector with your application, page 17starting with Step 6.

4. To remove a menu item for specific applications only, in the Webtop custom/config/appintgmenubar_menugroup.xml, enclose the <actionmenuitem> element in a <filter> elementthat negates (using the not keyword) the desired application name strings, separated by commas.You can identify the menu item by finding the same string in <menuitem> element’s child <value>element as the menu item name displayed on the menu.For example, to remove the Create New from Templatemenu item for the TextEditor and myAppapplications:<filter clientenv="not TextEditor, not MyApp"><actionmenuitem>

<aidynamic>no_dynamic</aidynamic><name>new_from_template</name><value>

<nlsid>MSG_NEW_FROM_TEMPLATE</nlsid></value><action>appintgnewfromtemplate</action><arguments>

<argument name="contentType" value="contextvalue"/></arguments>

</actionmenuitem></filter>

5. To limit a menu item to specific applications, in the Webtop custom/config/appintgmenubar_menugroup.xml, enclose the <actionmenuitem> element in a <filter> element that specifies thedesired application name strings, separated by commas.You can identify the menu item by finding the same string in <menuitem> element’s child <value>element as the menu item name displayed on the menu.For example, to add the Create New from Template menu item for the TextEditor and myAppapplications:<filter clientenv="TextEditor, MyApp"><actionmenuitem>

<aidynamic>no_dynamic</aidynamic><name>new_from_template</name><value>

<nlsid>MSG_NEW_FROM_TEMPLATE</nlsid></value><action>appintgnewfromtemplate</action><arguments>

<argument name="contentType" value="contextvalue"/></arguments>

</actionmenuitem></filter>

6. Save the Webtop custom/config/appintgmenubar_menugroup.xml file.







Chapter 7Customizing and Creating ApplicationConnector Components and Actions

These topics are included:• Overview, page 69• List of Application Connectors components and actions, page 69• appintgcontroller component, page 71• Creating new application connector components and actions, page 70

OverviewAll Documentum menu selections in the content authoring application are dispatched through theApplication Connectors controller component, appintgcontroller. This component launches an actionor component via a URL and adds messages and return listeners so that it can return messages, errorsor results to the native modal dialog window. If authentication is required, the appintgcontrollercomponent jumps to the appintgcontrollerlogin component.

All Application Connectors components and actions are described inWeb Development Kit ReferenceGuide.

List of Application Connectors componentsand actionsAll Application Connectors component and action names and configuration files are prependedwith the text, appintg.

Application Connectors components are:

appintgcontroller, appintgcontrollerlogin, appintghelp, appintgnewfromtemplate, appintgopen,appintgopenfrom, appintgopenfromcabinetslocator, appintgopenfromcategorieslocator,


Customizing and Creating Application Connector Components and Actions

appintgopenfromlocatorcontainer, appintgopenfrommyfileslocator,appintgopenfromrecentfileslocator, appintgopenfromsubscriptionslocator, appintgsaveascabinets,appintgsaveascategories, appintgsaveascontainer, appintgsaveasmyfiles, appintgsaveasrecentfiles,appintgsaveassubscriptions,

Application Connectors actions are:

appintgnewfromtemplate, appintgopenfrom, appintgsaveas,

Creating new application connectorcomponents and actionsYou can create a completely new component or action or extend an existing one. Extending an existingcomponent or action means that the new component or action inherits the existing component oraction’s configuration file <component> or <action> element’s child elements.

Note: Hereafter, a <component> or <action> element’s child elements will be called a configurationstructure. For example, a <params> configuration structure is:<params>

<param name="param1" required="true"/><param name="param2" required="false"/>

</params>

To create a new Aapplication connector component or action:

1. Copy the configuration file of an application connector component or action that closely resemblesyour new component or acion to the webtop\custom\config directory.

2. Rename the configuration file to the name of your new component or action.

3. To extend an existing component or action, add the extends attribute to the component or actionelement and specify the relative path to the component or action that you want to extend.For example, your new component, appintgnewcomponent extends the appintgnewfromtemplatecomponent:<component id="appintgnewcomponent" extends="appintgnewfromtemplate:webcomponent/config/library/appintgnewfromtemplate/appintgnewfromtemplate_component.xml">

4. Specify <component> or <action> configuration structures.See theWeb Development Kit Reference Guide andWeb Development Kit Development Guide for thespecific configuration structures that are available.

5. If you have extended an existing component or action, override or create a new <component> or<action> configuration structure by specifying the entire configuration structure including anyunmodified sibling elements in the parent configuration file.For example, to override the contentType parameter:



<params><param name="contentType" required="true"/>

1 <param name="existingparam" required="false"/></params>

1 If the configuration structure of an element that you want to modify includes sibling elements thatyou want to inherit, you must specify them as well. In this case, the parameter, existingparam, alreadyexists in the parent configuration file, but because you modified contentType, you must you must alsospecify the existingparam parameter exactly as it is in the parent configuration file.

6. To remove or add configuration structures or JSP user interface elements based on your applicationconnector, use the <filter> element.See Restricting menu items to specific applications, page 65.

7. To display the new component’s own success and failure JSP pages, add the new component’ssuccess and failure JSP pages in the appintgcontroller component configuration file.For example, for the appintgnewmenu menu item, the shownewcomponentpage success page isspecifiedbut no failure page is specified, so the default failure page in <pages><failure> is used.<item>

<name>appintgnewmenu</name><type>action</type><successpage>shownewcomponentpage</successpage>

</item>

8. Either add a new menu item or modify an existing one that causes the appintgcontroller to executeand display your component.See Restricting menu items to specific applications, page 65 and Adding custom menu itemsto all applications, page 65.

appintgcontroller componentThe appintgcontroller component consists of the AppIntgController servlet and JavaScript. Thiscomponent performs these functions:• Sets the locale, theme, Webtop view, and current repository if they are defined in the component

arguments or stored in a cookie. If they are not in the argument list or a cookie, the default valuesas defined in the appintgcontroller component definition are used.

• Enables login: Checks for connection requirement and, if required, sets a menu version eventand forces login. Provides the loginas action that disconnects from all repositories and allowsthe user to log in with different credentials.



• Dispatches a JSP page or action as specified in the <type> element:

Value of page in <type> element dispatches an event and, if the dispatch item has a <page>element, loads a named JSP page from the component definition in a native modal dialog window.

Value of action in <type> element dispatches the action, adds a return listener, and displays thesuccess or failure page after action completion. Adds context arguments to a menu action mapthat is downloaded to the client.

If the menu item does not have a <dispatchitems> entry, the action or component is dispatchedand the default success or failure page is used.

The appintgcontroller dispatches menu items from the menu that is named in the <menugroupid>element of the appintgcontroller component definition. Each action or component that isdefined as a menu item in the menugroup definition (in appintgmenubar_menugroup.xml)can have a corresponding entry of type ʺaction in the appintgcontroller component definition.This allows you to configure a specific success or failure page for the action. For example,for the appintgnewfromtemplate menu item, there is an item in the controller definition (inapptgcontroller_component.xml) that specifies a success page:<dispatchitems><item><name>appintgnewfromtemplate</name><type>action</type><successpage>opendocumentevent</successpage>

</item></dispatchitems>

Table 2, page 72 describes the configuration elements for dispatching actions or components.

Table 2. Appintgcontroller <dispatchitems> elements

Element Description

<item> Contains one of each: <name>, <type>, and either<page> or <successpage>

.<name> Contains the name of a menu action, if the typeis action. Contains the name of an event, if thetype is page.

.<type> Specifies the type of menu item to dispatch:action or page

.<page> Specifies a named child element of <pages>, tolaunch a page



Element Description

.<successpage> Optional. Specifies a named child element of<pages>, to launch a success page after actioncompletes. If this element is not present, thedefault success page in <pages><success> is used.

.<failurepage> Optional. Specifies a named child element of<pages>, to launch a failure page after actionfails. If this element is not present, the defaultsuccess page in <pages><success> is used.

When the user selects a menu item, the appintgcontroller builds a URL, and the requested page loadsin a modal dialog window that hosts a browser control within your application. If the menu item mapsto an action, the WDK action dispatcher performs the action and returns the success or failure JSP pageto the modal dialog window. If the menu item maps to a component, the WDK component dispatcherreturns the component JSP start page to the modal dialog window.

Each JSP page that is named for a dispatch item must be defined in the apptgcontroller componentdefinition. For example, the appintgopendocumentevent item specifies a value of opendocumenteventfor the <successpage> element. The element <pages>.<opendocumentevent> defines this page andhas a value of /webcomponent/library/appintgcontroller/appIntgOpenDocumentEvent.jsp, whichspecifies the path to the page to be loaded.

The following default pages are defined within the <pages> element of the component definition. If anitem does not specify a success or failure page, then the default page is used:

Table 3. Required pages in appintgcontroller component definition

Element Description

<start> Specifies the path to an error handler pagethat is loaded if the action or component is notdispatched

<disconnect> Specifies the path to a page that is used todisconnect existing sessions and return to thecontroller for new login. This page invalidatesthe HTTP session.

<success> Specifies the path to the default success page thatis loaded after the action completes successfully

<failure> Specifies the path to the default faliure page thatis loaded after the action fails to complete



Client environment qualifier in the WDKapplicationThe clientenv qualifier is introduced to enable component configuration based on the clientenvironment. This qualifier matches the context value ʺwebbrowser or ʺappintg to the contextʺclientenv.

The client environment context is established in one of the following ways:• Specify clientenv in a URL request parameter, preferably in the first URL request that invokes a

WDK‑based application. This method takes precedence over the value in app.xml (the secondoption). For example:http://webtop/component/main?clientenv=webbrowser

• Specify the default clientenv value in your custom app.xml as the value of<application>.<environment>.<clientenv>. Valid values: webbrowser | appintg | not appintg

The client environment is stored as a session cookie so that WDK can restore the context for a givenclient session when the server times out.

The clientenv qualifier can be used as a filter in component definitions to specify a different set of JSPpages depending on the environment. For example, the changepassword component definition usesthe value of appintg and not appintg to present different pages depending on whether the user is in anApplication Connectors environment. The filter is applied as follows:<pages><filter clientenv="not appintg"><start>/wdk/system/changepassword/changepassword.jsp</start>

</filter><filter clientenv="appintg"><start>/wdk/system/changepassword/appintgchangepassword.jsp</start>

</filter></pages>

A more granular environment configuration can be applied within a JSP page itself using theclientenvpanel control. This control is used to show or hide UI elements based on the runtimeclientenv context. The client environment is specified as the value of the environment attribute. Forexample, the 5.3 checkin component JSP page has a clientenvpanel control that is rendered onlyin the AppConnectors environment:<dmfx:clientenvpanel environment="appintg"><dmf:fireclientevent event="aiEvent"

includeargname="true"><dmf:argument name="event" value="ShowDialog"/>...

</dmf:fireclientevent></dmfx:clientenvpanel>

The reversevisible attribute on the clientenvpanel control toggles the display. In the same exampleabove (checkin.jsp), another panel is hidden in the AppConnectors environment:<dmfx:clientenvpanel environment="appintg" reversevisible="true">



...<dmf:checkbox name="checkinfromfile"

id="checkinfromfile" nlsid="MSG_CHECKIN_FROM_FILE"onclick="onCheckinFromFileClick" runatclient="true"/>

...</dmfx:clientenvpanel>

JSP fragments can also be defined, so that a component JSP page includes fragments that aredispatched based on the client environment. For information on JSP fragments, refer to .

To trace problems in the client environment, turn on the tracing flag CLIENTENV.

Sample

Introduction

This sample demonstrates adding a Documentum menu item, Delete, in your application. The Deletemenu item calls the standard Webtop delete action.

Procedure1. On the Webtop application server machine, copy the \webcomponent\config/

library\appintgmenubar\appintgmenubar_menugroup.xml file to the Webtop custom\configdirectory.

2. In the Webtop custom\config\appintgmenubar_menugroup.xml, extend the original file by usingthe extends attribute on the <menugroup> element:<menugroup id="appintgmenubar" version="latest" extends="appintgmenubar:/webcomponent/config/library/appintgmenubar/appintgmenubar_menugroup.xml">

3. Add this <actionmenuitem> element after the save_as <actionmenuitem> in theappintgmenubar_menugroup.xml file:<actionmenuitem>

<aidynamic>repository_content</aidynamic><name>delete_menu</name><value>Delete...</value><action>delete</action><arguments><argument name="objectId" value="contextvalue"></argument>

</arguments></actionmenuitem>



4. Save the appintgmenubar_menugroup.xml file.

5. Copy the webtop\config\appintgcontroller_component.xml file to the Webtop custom/configdirectory

6. In the Webtop custom\config\appintgcontroller_component.xml, extend the original file by usingthe extends attribute on the <component> element:<component id="appintgcontroller" extends="appintgcontroller:/webtop/config/appintgcontroller_component.xml">

7. In the Webtop custom\config\appintgcontroller_component.xml file after the<pages><appintgmenumap> element, add this code:<deletesuccess>/webcomponent/library/appintgcontroller/deleteSuccess.jsp</deletesuccess>

and after the checkin <item> element, add this code:<! delete page ><item>

<name>delete</name><type>action</type><successpage>deletesuccess</successpage>

</item>

8. In the Webtop custom/config directory, create a file named deleteSuccess.jsp that contains thisJSP code:<%@ page contentType="text/html; charset=UTF8" %><%@ page errorPage="/wdk/errorhandler.jsp" %><%@ page import="com.documentum.webcomponent.library.appintgcontroller.

AppIntgController"%><%@ taglib uri="/WEBINF/tlds/dmform_1_0.tld" prefix="dmf" %><%@ taglib uri="/WEBINF/tlds/dmformext_1_0.tld" prefix="dmfx" %>

<dmf:html><dmf:head>

<! Project Application Connectors ><! Module Controller ><! File deleteSuccess.jsp ><!>

<dmf:webform/>

<! Send the AI component HideDialog event ><dmf:fireclientevent event=’aiEvent’ includeargname=’true’>

<dmf:argument name=’event’ value=’HideDialog’/></dmf:fireclientevent>

<! Send the AI ShowMessage event ><dmf:fireclientevent event=’aiEvent’ includeargname=’true’>

<dmf:argument name=’event’ value=’DeleteSuccess’/><dmfx:argument name=’message’ contextvalue=’

<%=AppIntgController.MESSAGE%>’/></dmf:fireclientevent>



</dmf:head>

<dmf:body><dmf:form></dmf:form>

</dmf:body>

</dmf:html>

9. In your application connector’s app.config file as a child of <actionSettings>, add this code:

Note: You must generate your own public key tokens for MyCompany.AppConnector.TextEditorAppIntg.CustomNotificationHandler and MyCompany.AppConnector.MyAppIntg.MyAppAppIntegrationProvider and specify them for each one’s PublicKeyToken attribute.

<actionInfo name="customhandler"type="MyCompany.AppConnector.TextEditorAppIntg.CustomNotificationHandler,

MyCompany.AppConnector.TextEditorAppIntg,Version=1.0.0.0,Culture=neutral,PublicKeyToken=CustomNotificationHandlerPublicKeyToken" />

and after the <actionSettings> element code, add this code:<appIntegrationSettings version="1.0">

<appIntegrationInfo name="MyCompany Application Connector for MyApp"type="MyCompany.AppConnector.MyAppIntg.

MyAppAppIntegrationProvider,MyCompany.AppConnector.MyAppAppIntg,

Version=1.0.0.0,Culture=neutral,PublicKeyToken=a289a5c6e19bab4f"clientSideEventHandlers="session,notification,component,

customhandler"canConnectTimerDuration="7000"contentSources="webtop" >

</appIntegrationInfo></appIntegrationSettings>

10. In your application connector project, implement a CustomNotificationHandler that inherits fromActionProviderBase by creating this code in a CustomNotificationHandler.cs file:using System;

using log4net;using Documentum.AppConnector.Logging;using Documentum.AppConnector.Application;

namespace MyCompany.AppConnector.TextEditorAppIntgpublic class CustomNotificationHandler : ActionProviderBase

private const string DELETE_SUCCESS = "DeleteSuccess";

private static readonly ILog logger =Log.GetLogger(typeof(WdkComponentNotificationHandler));



TextEditorAppIntegrationProvider provider = null;

public CustomNotificationHandler()

public override void HandleWdkEvent(string args)

logger.Info("Within CustomNotificationHandler::HandleWdkEvent...");

string eventName =actionParent.GetArgumentValue(args, ApplicationConstants.EVENT);

if (base.actionParent is TextEditorAppIntegrationProvider)

provider = (TextEditorAppIntegrationProvider) base.actionParent;

switch (eventName)

case DELETE_SUCCESS:if (provider != null)

string message =actionParent.GetArgumentValue(args,

ApplicationConstants.MESSAGE);

provider.HandleMyCustomEvent(eventName, message);break;

default:

break;



Chapter 8Deploying Your Application Connector

• Overview, page 79• Installing with an MSI or InstallShield installer, page 79• Installing with a non‑MSI or non‑InstallShield installer, page 79

OverviewThe AC SDK includes a merge module that an MSI or InstallShield installer can use. If you use anotherinstaller, manual instructions for the files and services that need to be installed are provided.

Installing with an MSI or InstallShield installerAdd the AC SDK Common Merge Module to your application or application connector’s MSI orInstallShield installer.

Installing with a nonMSI or nonInstallShieldinstallerTo deploy your application connector to client machines, your installer must:

1. Install these files in the C:\Program Files\Documentum\AppConnector folder:

atl71.dllDocumentum.AppConnector.Configuration.dllDocumentum.AppConnector.Credentials.dllDocumentum.AppConnector.CredentialService.exeDocumentum.AppConnector.CredentialService.exe.config


Deploying Your Application Connector

Documentum.AppConnector.CredentialService.exe.log4net.configdocumentum.appconnector.credentialservice.InstallStateDocumentum.AppConnector.DataProtection.dllDocumentum.AppConnector.DataProtection.Interfaces.dllDocumentum.AppConnector.Locale.dllDocumentum.AppConnector.LocaleManager.exeDocumentum.AppConnector.LocaleManager.exe.log4net.configDocumentum.AppConnector.Logging.dllDocumentum.AppConnector.Preferences.dllDocumentum.AppConnector.Provider.dllDocumentum.AppConnector.Provider.Interfaces.dllDocumentum.Interop.EventServer.dllEventServer.exeICSharpCode.SharpZipLib.dllICSharpCode.SharpZipLib‑license.txtlog4net.dlllog4net‑license.txtMicrosoft.mshtml.dllmsvcp71.dllmsvcr71.dll

2. Add this registry entry key for your application connector:HKEY_LOCAL_MACHINE\SOFTWARE\your_company_name\AppConnector\Installed\

your_app_connector_name

with these values:App.config:REG_SZ: your_app_connector_name.exe.configInstallPath:REG_EXPAND_SZ:your_app_connector_install_path

Use the HKEY_LOCAL_MACHINE predefined key to make your application connector availableto all users on the machine or HKEY_CURRENT_USER to make your application connectoravailable to only the user that installs your application connector.

3. To register the Documentum.AppConnector.CredentialService.exe with the service manager,execute this command in a command window:installutil.exe "C:/Program Files/Documentum/AppConnectors/Documentum.

AppConnector.CredentialService.exe


Chapter 9Debugging Application ConnectorExecution

These topics are described:• Setting logging options, page 81

Setting logging optionsApplication Connectors use the open source logger, log4net, which you can find athttp://logging.apache.org/log4net/.

Logging is configured in a file specific to your application and to the Application Connectors servicesand processes. The log files for Application Connectors services and Microsoft Office ApplicationConnectors are:• Application Connectors Credential Service:

Documentum.AppConnector.CredentialService.exe.log4net.config• Application Connectors Locale Manager:

Documentum.AppConnector.LocaleManager.exe.log4net.config• Microsoft Word: winword.exe.log4net.config• Microsoft Excel: excel.exe.log4net.config• Microsoft PowerPoint: powerpnt.exe.log4net.configThe Application Connectors default configuration is:<?xml version="1.0" encoding="utf8" ?><log4net>

<appender name="RollingLogFileAppender" type="log4net.Appender.RollingFileAppender"><threshold value="OFF" /><file value="$APPDATA\\Documentum\\AppConnector\\Log\\

Documentum Application Connector for Word.log" /><appendToFile value="true" /><maxSizeRollBackups value="5" /><maximumFileSize value="500KB" /><rollingStyle value="Size" />


Debugging Application Connector Execution

<staticLogFileName value="true" /><layout type="log4net.Layout.PatternLayout,log4net">

<conversionPattern value="%d [%t] %5p %c [%x] %m%n" /></layout>

</appender><root>

<level value="ALL" /><appenderref ref="RollingLogFileAppender" />

</root></log4net>

Assembly RequirementsBecause the sample application, TextEditorApp, depends on other assemblies, you must set the thestart application setting in Visual Studio.NET to the TextEditorApp.exe installed in the drive:\ProgramFiles\EMC Documentum Application Connectors SDK 5.3 folder.


Chapter 10Troubleshooting

The following issues can arise during the installation or use of AppConnectors:

Documentum menu does not appear in the authoring application — Check the following areas:• Find the install.log file that is created in the location from which the client installer is run. This

file will show whether the installation completed successfully.• Check the Windows Task Manager to see whether at least two AppConnectors processes are

running: Documentum Credentials Service andDocumentum Locale Manager.• Verify that a menu configuration file has downloaded to the client, for example,

%ProgramFiles%\MyApp\Documentum\Webtop\appintgmenubar_menugroup.xml. If this fileis not present, stop and start the Locale Manager Windows process. MyApp is the path that youhave chosen for your application.

• Check the log4net log files for errors. If none are found, declare a more verbose logging level andrestart the affected process.

User is asked to log in unexpectedly — Check the following causes for this problem:• The client‑side app.config file does not specify system scope. If this is the case, the user must

log in for each authoring application instance.• The Documentum Credential Service is not running. Check this in the Windows Task Manager

and restart the service if needed.• Saved credentials are not supported by the configuration setting in the WDK application app.xml

file (value of <save_credential>.<enabled> is true).

Unreliable content transfer (older Java applet basis) — Pre‑WDK 5.3 content transfer applets andcomponents, or custom components that extend them, are not supported with AppConnectors.

User credentials are not being saved as expected — You may be required to reenter your logincredentials when you expected to be logged in silently. Chances are that the Credential Service has notbeen started properly. To manually start this Windows Service, go to the Windows Startmenu andselect Administrative Tools Services, scroll down to ʺDocumentum Application Connector CredentialService,ʺ and click Start. A properly started Credential Service in the Services control panel willdisplay a status of ʺStarted.


Troubleshooting

Localized UI not displayed — The Documentum Application Connector Locale Manager displaysthe localized menu. To start this program, double‑click it in its default location: C:\ProgramFiles\Documentum\AppConnector\Documentum.AppConnector.LocaleManager.exe.


Chapter 11Creating Application Connectors ThatIntegrate with C++ or Visual Basic 6Applications

These topics are included:• Introduction, page 85• Overview, page 85• Creating application connectors that integrate with C++ applications, page 87

IntroductionApplication connectors can work with .NET, C++, and Visual Basic 6 applications. If your applicationis written in C++ or Visual Basic 6, you can create a COM component that works as a bridge betweenyour application connector and application. To create an application connector and COM object thatwork with a C++ application, follow the MDITextEditorSampleApp solution, which consists of asample C++ application and C# application connector.

OverviewThe MDITextEditorSampleAppConnector solution implements Microsoft ATL Connection Points. Formore information about ATL Connection Points, see the MSDN ATL Connection Points web page. For.NET‑specific information, see the MSDN ComSourceInterfacesAttribute Class web page (the Connectclass in the MDITextEditorSampleApp solution uses the ComSourceInterfacesAttribute class).

Figure 10, page 86 shows that events in the Connect class of the MyCompany.AppConnector.MDITextEditorAppIntg sample application connector cause the AppConnectorEventClientclass to call into the C++ application CMainFrame class. It also shows that calls from theCMainFrame class go through the _connect interface to the Connect class, which then calls either


http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vccore/html/_atl_connection_points.asp

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfsystemruntimeinteropservicescomsourceinterfacesattributeclasstopic.asp

Creating Application Connectors That Integrate with C++ or Visual Basic 6 Applications

MDITextEditorAppIntegrationProvider or MenuProvider. In ATL connection points terms, theConnect class is the source that calls the IAppConnectorConnect outgoing interface.

Figure 10. MDITextEditorSampleAppConnector solution architecture

When the MDITextEditorApp application starts up, the Documentum menu is added to it in thissequence of execution:

1. The MDITextEditorApp Application class initializes the CMainFrame class, which instantiates theAppConnectorEventClient and Connect classes.

The AppConnectorEventClient class implements the IAppConnectorConnect interface. Throughthe IAppConnectorConnect interface, the Connect class’s outgoing events are fired.

2. When the CMainFrame class is initialized, it calls the Connect class’s InitAppIntegration methodthrough the _connect interface.

3. The Connect class instantiates the MDITextEditorAppIntegrationProvider and MenuProviderclasses.

4. Then, the MenuProvider’s menu info is sent via IAppConnectorConnect interface to theCMainFrame class, which builds the Documentum menu.



Creating application connectors that integratewith C++ applicationsThis section describes how to create an application connector and modify your C++application to work with that application connector. The sample code is drawn from theMDITextEditorSampleAppConnector solution. See the MDITextEditorSampleAppConnector solutionfor the complete source code.

Creating your application connector1. Follow the steps in Creating an application connector, page 19.

2. Immediately before the beginning of your MyAppIntegrationProvider class, add the ComVisibleattribute and set it to false.Because the default setting on the entire assembly level for the ComVisible attribute is true, eachprogramming element that should not be visible to COM clients must be explicitly hidden bysetting the ComVisible attribute to false.For more information about the ComVisible attributes, seehttp://msdn.microsoft.com/library/default.asp?url=/library/en‑us/cpref/html/frlrfSystemRuntimeInteropServicesComVisibleAttributeClassTopic.asp.

3. In your MyAppIntegrationProvider class, add the CLSCompliant attribute immediately before thebeginning of the InitializeAppIntegrationand set the attribute to falseBecause the default setting on the entire assembly level for the CLSCompliant attribute is true,each programming element that uses elements that are not part of the Common LanguageSpecification must be explicitly identified by setting the CLSCompliant attribute to false.For more information about the CLSCompliant attribute, see http://msdn.microsoft.com/library/default.asp?url=/library/en‑us/cpref/html/frlrfSystemCLSCompliantAttributeClassTopic.asp.

4. Instead of using MainForm as the parent class, use the Connect class.

a. Instead of declaring the parent as MainForm object in the Data members region of yourMyAppIntegrationProvider class, add this code:Connect parent;

Because your programming model does not have an application object as the methodologyused in Creating an application connector, page 19 assumes, your application connectoruses the Connect class as the parent.

b. When you need to make sure that the parent object is a Connect object, use Connect.

5. To create event handlers and register for the specified events, in the InitializeAppIntegrationmethod right before the return(true) line, add this code:


http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemRuntimeInteropServicesComVisibleAttributeClassTopic.asp


http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemCLSCompliantAttributeClassTopic.asp

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemCLSCompliantAttributeClassTopic.asp


Note: In order for VS.NET intellisense to recognize these events, you must first add theappropriate delegates in your Connect class.this.parent.WindowActivate += new Connect.WindowActivateDelegate(WindowActivate);this.parent.DocumentOpen += new Connect.DocumentOpenDelegate(DocumentOpen);this.parent.NewDocument += new Connect.NewDocumentDelegate(NewDocument);this.parent.DocumentBeforeClose += new Connect.DocumentBeforeCloseDelegate(

DocumentBeforeClose);this.parent.DocumentBeforeSave += new Connect.DocumentBeforeSaveDelegate(

DocumentBeforeSave);

6. Create a C# file called Connect.cs and create an IAppConnectorConnect interface definition in aregion similar to this one and generate your own GUID:#region Source interface definition[InterfaceType(ComInterfaceType.InterfaceIsIDispatch)][Guid("8A8FBEE270CA41b88551AF6411B61AF3")]public interface IAppConnectorConnect

[DispId(1)] void CreateMenuItem(int menuItemId, int parentId,bool isPopup, string caption);

[DispId(2)] long GetActiveWindowHandle();[DispId(3)] void SetMenuItemState(int menuItemId, bool enabled);[DispId(4)] void DoOpenDocument(string filePath);[DispId(5)] bool GetActiveDocumentModifiedSinceLastSave();[DispId(6)] string SaveDocument(string targetFolder);[DispId(7)] void CloseActiveDocument();

#endregion

The IAppConnectorConnect event interface is implemented by the client‑side sink. Functions ofthis interface are called by Connect class, which is the source. The AppConnectorEventClient classis the listener and is located in your main frame class file.

7. Create a Connect class declaration and corresponding COM interface definition similar to thisone and generate your own GUID:[ComSourceInterfaces(typeof(IAppConnectorConnect))][ClassInterface(ClassInterfaceType.AutoDual)][Guid("1B7D7AA4216B4ad0B653C499B7DC497A")]public class Connect

8. In the Connect class, implement these methods corresponding delegates and events that are firedby the IAppConnectorConnect implementation:• FireCreateMenuItem• FireGetActiveWindowHandle• FireSetMenuItemState• FireDoOpenDocument• FireGetActiveDocumentModifiedSinceLastSave• FireSaveDocument



• FireCloseActiveDocument

9. In the Connect class, implement these methods and corresponding delegates and events thatare fired by your main frame class:• FireWindowActivate• FireDocumentOpen• FireNewDocument• FireDocumentBeforeClose• FireDocumentBeforeSave

10. In the Connect class, implement these methods that are directly called by your main frame class:• InitAppIntegration• CloseAppIntegration• HandleCustomMenuEvent

11. Create a C# file called MenuProvider.cs and immediately before the beginning of yourMenuProvider class, add the ComVisible attribute and set it to false.Because the default setting on the entire assembly level for the ComVisible attribute is true, eachprogramming element that should not be visible to COM clients must be explicitly hidden bysetting the ComVisible attribute to false.For more information about the ComVisible attributes, seehttp://msdn.microsoft.com/library/default.asp?url=/library/en‑us/cpref/html/frlrfSystemRuntimeInteropServicesComVisibleAttributeClassTopic.asp.

12. In addition to the standard methods (as described in Building the Documentum menu, page 52) toimplement in the MenuProvider class, also implement the HandleCustomMenuEvent method.

Creating your MyAppConnectorEventClient1. In your application’s main frame class file, create a class, MyAppConnectorEventClient, that

implements the connection point IAppConnectorConnect interface. For example:class MyAppConnectorEventClient : public IDispEventSimpleImpl<1,

AppConnectorEventClient, &DIID_IAppConnectorConnect>

2. In MyAppConnectorEventClient, add this sink map:public:BEGIN_SINK_MAP(AppConnectorEventClient)SINK_ENTRY_INFO(1, DIID_IAppConnectorConnect, 1,

OnCreateMenuItem, &OnCreateMenuItemInfo)SINK_ENTRY_INFO(1, DIID_IAppConnectorConnect, 2,

OnGetActiveWindowHandle, &OnGetActiveWindowHandleInfo)





SINK_ENTRY_INFO(1, DIID_IAppConnectorConnect, 3,OnSetMenuItemState, &OnSetMenuItemStateInfo)

SINK_ENTRY_INFO(1, DIID_IAppConnectorConnect, 4,OnDoOpenDocument, &OnDoOpenDocumentInfo)

SINK_ENTRY_INFO(1, DIID_IAppConnectorConnect, 5,OnGetActiveDocumentModifiedSinceLastSave,&OnGetActiveDocumentModifiedSinceLastSaveInfo)

SINK_ENTRY_INFO(1, DIID_IAppConnectorConnect, 6,OnSaveDocument, &OnSaveDocumentInfo)

SINK_ENTRY_INFO(1, DIID_IAppConnectorConnect, 7,OnCloseActiveDocument, &OnCloseActiveDocumentInfo)

END_SINK_MAP()

3. In the constructor, add this code to create the connection:AppConnectorEventClient(_Connect* pObj, CMainFrame* mainFrame)

pDotNetObject = pObj;this>mainFrame = mainFrame;pDotNetObject>AddRef();DispEventAdvise((IUnknown*)pDotNetObject);

In the private region of your class, declare this pointer:_Connect* pDotNetObject;

4. In the destructor, add this code to close the connection:~AppConnectorEventClient()

pDotNetObject>Release();DispEventUnadvise((IUnknown*)pDotNetObject);

5. Implement these methods, which are basically pass‑thru calls to the main frame class methods thatactually implement the functionality:• OnCreateMenuItem• OnGetActiveWindowHandle• OnSetMenuItemState• OnDoOpenDocument• OnGetActiveDocumentModifiedSinceLastSave• OnSaveDocument• OnCloseActiveDocument

Modifying your main frame class1. In your main frame class file, create ATL code that creates function information for each event:

_ATL_FUNC_INFO OnCreateMenuItemInfo = CC_STDCALL, VT_EMPTY, 4, VT_I4,VT_I4, VT_BOOL, VT_BSTR;



_ATL_FUNC_INFO OnGetActiveWindowHandleInfo = CC_STDCALL, VT_I4, 0, ;_ATL_FUNC_INFO OnSetMenuItemStateInfo = CC_STDCALL, VT_EMPTY, 2, VT_I4,

VT_BOOL;_ATL_FUNC_INFO OnDoOpenDocumentInfo = CC_STDCALL, VT_EMPTY, 1, VT_BSTR;_ATL_FUNC_INFO OnGetActiveDocumentModifiedSinceLastSaveInfo = CC_STDCALL,

VT_BOOL, 0, ;_ATL_FUNC_INFO OnSaveDocumentInfo = CC_STDCALL, VT_BSTR, 1, VT_BSTR;_ATL_FUNC_INFO OnCloseActiveDocumentInfo = CC_STDCALL, VT_EMPTY, 0, ;

2. In your main frame class constructor, declare these pointers:pAppConnectorEventClient = NULL;pConnect = NULL;

3. In your main frame class onShowWindow event, initialize the MyCompany.AppConnector.MDITextEditorAppIntg Connect (through the _Connect class) and AppConnectorEventClientclasses:

if (bShow)

//Create instance of Connect class.HRESULT hr = CoCreateInstance(CLSID_Connect, NULL, CLSCTX_SERVER,

IID__Connect, (void**)&pConnect);

if (SUCCEEDED(hr) && (pConnect != NULL))

//Create instance of AppConnectorEventClient class.pAppConnectorEventClient = new AppConnectorEventClient((_Connect*)pConnect, this);

pConnect>InitAppIntegration();pConnect>FireWindowActivate("");

4. In your main frame class’s OnDestroy event, destroy and cleanup the MyCompany.AppConnector.MDITextEditorAppIntg Connect and AppConnectorEventClient classes:if (pConnect != NULL)

pConnect>CloseAppIntegration();pConnect>Release();pConnect = NULL;

if (pAppConnectorEventClient != NULL)

delete pAppConnectorEventClient;

5. Implement these events in your main frame class:• HandleCustomMenuEvent• OnDoOpenDocument• OnWindowActivate• OnDocumentOpen



• OnNewDocument• OnClose• OnCloseDocument• OnSaveDocument• OnBeforeSaveDocument• OnCloseActiveDocument


Chapter 12Executing Documentum FoundationClass Functionality from YourApplication Connector

These topics are included:• Introduction, page 93• Overview, page 93• Procedure, page 94

IntroductionYou can execute functionality in the Documentum Foundation Classes (DFC) from your applicationconnector by creating a WDK component that uses DFC functionality to call a repository; then, youcan call that component from your application connector.

OverviewThe Application Connector SDK does not install DFC; instead, DFC is installed with Webtop onthe application server.

DFC enables you to:• Check in, check out, view, import, export, delete, move, and copy objects• Manage object types, permissions, groups, users, relationships, folders, cabinets, and retention

policies• Manage value assistance and validate object attribute data• Manage workflows, work queues, and lifecycles• Manage virtual documents


Executing Documentum Foundation Class Functionality from Your Application Connector

• Manage Documentum business objects• Manage audit trail logging• Perform queries and transformations on XML documents• Build and execute DQL queries• Retrieve information about Business Process Manager transition conditions (including XPath)• Manage Accelerated Content Services (ACS) configuration• Manage Branch Office Caching Services (BOCS) configurationFor a complete description of DFC functionality, see the DFC Development Guide.

The MyCompany.AppConnector.TextEditorAppIntg sample contains functionality that calls DFC.This sample creates a Run Querymenu item on the Documentum menu that calls a WDK componenton Webtop, which executes a DQL query against a repository.

Procedure1. Build a menu as you would any other menu.

See the MenuProvider.cs file for examples of the values that are specified for the RunQuery menu item. Although the sample application connector generates this menuitem dynamically, you should follow the best practice of specifying the menu item in theappintgmenubar_menugroup.xml file.In the MenuProvider.cs file, the DQL query is specified as a value of the MenuInfo class’sdispatchArguments field. In the MenuProvider.cs class, it is specified as follows:queryMenuInfo.dispatchArguments = "query~select * from dm_format";

query is the argument name that is passed to the component, the tilde (~) is a separator, and thevalue of the argument is the remainder of the string (that is, the DQL query, select * from

dm_format).

2. Create a custom component to handle DFC calls to the repository.

Note: For a complete example, see the appintgxdql component in thewebcomponent\config\library\appintgxdql\appintgxdql_component.xml configuration file andthe com.documentum.webcomponent.library.appintgxdql.AppIntgXdql class.

a. Write the component configuration file.

b. Write the Java class to execute your custom functionality.

i. Import these DFC classes to retrieve a session to the repository:import com.documentum.com.IDfClientX;import com.documentum.com.DfClientX;

ii. Import the DFC classes and interfaces that contain the functionality that you want to use.For example, to call the functionality that executes a DQL query, import these classes:



import com.documentum.fc.client.IDfQuery;import com.documentum.fc.common.DfException;import com.documentum.xml.xdql.IDfXmlQuery;

iii. Write the code to execute the functionality.For example, to execute a DQL query:String dqlQuery = args.get(QUERY);

IDfXmlQuery queryApi = s_clientX.getXmlQuery();queryApi.init();queryApi.setDql(dqlQuery);queryApi.execute(IDfQuery.DF_EXEC_QUERY, this.getDfSession());

String queryResult = nulltry

queryResult = queryApi.getXMLString();queryResult = StringUtil.replace(queryResult, "\"", "’");queryResult = StringUtil.replace(queryResult, "\n", "");

catch (DfException e)ErrorMessageService.getService().setNonFatalError(this,

"Failed to get query result.", e);setReturnValue(Form.SUCCESS_ON_RETURN, FALSE);setComponentReturn();

setReturnValue(QUERYRESULT, queryResult);

3. Write an event handler to handle events fired by your custom component.See the TextEditorAppEventHandler class, which inherits from the ActionProviderBase, in theMyCompany.AppConnector.TextEditorAppIntg sample. For example:public override void HandleWdkEvent(string args)

string eventName = actionParent.GetArgumentValue(args,ApplicationConstants.EVENT);

if (eventName.Equals("XdqlSuccess"))

actionParent.ShowDefaultCursor();string queryResult = actionParent.GetArgumentValue(args, "queryResult");logger.Info(queryResult);System.Windows.Forms.MessageBox.Show(queryResult);

4. Generate a public key and add your custom event handler to your myapp.config.exe file. Forexample:<actionInfo name="custom"

type="MyCompany.AppConnector.TextEditorAppIntg.TextEditorAppEventHandler,MyCompany.AppConnector.TextEditorAppIntg,Version=1.0.0.0,Culture=neutral,



PublicKeyToken=a289a5c6e19bab4f" />


Appendix A

Sample Applications

These topics are described:• Running in debug mode, page 97

Running in debug modeTo run the sample applications in debug mode, the sample application projects must run the sampleapplication executables installed by the Application Connectors SDK installer and the applicatonconnector project must the the startup project.

To specify the installed sample application executable and run it in debug mode:

1. After opening one of the sample applications in Visual Studio.NET, make sure that the applicationconnector project name (for example, MyCompany.AppConnector.TextEditorAppIntg) is bolded,which indicates that it is the startup project.By default, the application connector project is the startup project. If it is not bolded, right‑click onthe application connector project and select Set as StartUp Project.

2. Right‑click on the application connector project (for example, MyCompany.AppConnector.TextEditorAppIntg) and select Properties.The application connector project is the startup project for debug mode.

3. In the dialog box, click Configuration Properties > Debugging.

4. Set the Debug Mode field to Program and click Apply.

5. Click in the Start Application field, click the browse icon (that is, the gray icon with the ellipsis(...)) and browse to the location of sample application’s installed executable.For example, the default location of the TextEditorApp.exe installed by the SDK installer isC:\Program Files\EMC Documentum Application Connectors SDK 5.3\TextEditorApp.exe.

6. Click OK.


Sample Applications

7. Compile the application connector project (which is the active project) and copy the assembly anddebug symbols file to the same location as the sample application’s installed executable.For example, copy the MyCompany.AppConnector.TextEditorAppIntg.DLL andMyCompany.AppConnector.TextEditorAppIntg.pdb files to C:\Program Files\EMCDocumentum Application Connectors SDK 5.3.To automate this step as part of the post‑build process:

a. Right‑click the sample application connector project, and select Properties > Build Events.

b. Click the Post‑build Command Line field in the Common Properties folder and add these lines:copy /y "$(TargetDir)MyAppIntg.dll" "ac_sdk_install_path"

copy /y "$(TargetDir)MyAppIntg.pdb" "ac_sdk_install_path"

where:

MyAppIntg is the name of your application connector (for example, MyCompany.AppConnector.TextEditorAppIntg)ac_sdk_install_path is the path to your Application Connectors SDK installation (forexample, C:\Program Files\EMC Documentum Application Connectors SDK 5.3).

8. Press F5 to run the sample application in debug mode.


Index

AActiveDocumentArguments property

implementing, 28ActiveDocumentFilePath property

implementing, 29ActiveDocumentModifiedSinceLastSave

propertyimplementing, 29

ActiveDocumentObjectId propertyimplementing, 30

ActiveWindowHandle propertyimplementing, 31

AppConnectorEventServerscenarios, 43

appintgcontrollerdescription, 71

application connectorevents, WDK, 46

application connector componentsappintgcontroller, 71creating new, 70list of, 69overview, 69

application connectorsauthentication, 74

architectureApplication Connectors SDK, 11

BBuildMenu method

implementing, 53BuildMenuState method

implementing, 56

CC++ applications

procedure for integrating ApplicationConnectors with, 87

samples, 85

calling application connectorsprocedure, 23

cleaning upapplication connectors, 21

clientenvfor application connectors, 74

Close methodimplementing, 31

CloseActiveDocument methodimplementing, 32

creating application connectorsprocedure, coding, 19procedure, general, 17

Ddebugging

debug mode, 97logging options, 81

DefaultDocumentFormat propertyimplementing, 32

deployingapplication connectors, 79

DestroyMenu methodimplementing, 59

DestroyMenuState methodimplementing, 59

DoAbout methodimplementing, 33

Documentum menuadding custom menu items to all

applications, 65building, 52modifying menu items for all

applications, 63overview, 49removing menu items from all

applications, 62restricting menu items to specific

applications, 65samples, 75


Index

DoOpenDocument methodimplementing, 33

Eevents

AppConnectorEventServerscenarios, 43

overview, 41

Ffiles

installed, 15

IInitializeAppIntegration method

implementing, 26initializing

application connectors, 21installation

default path for application connectordevelopment files, 15

default path for shared files, 15documentation, 16installed folders and files, 15procedure, 15sample source files, 16testing, 16

Llogging

setting options, 81

MMenuBar property

implementing, 34MyAppIntegrationProviderBase class

implementing, 26

OOpenedRepositoryDocumentCount

propertyimplementing, 35

overviewapplication connector components, 69Application Connectors SDK, 11Documentum menu, 49events, 41

RRebuildMenu method

implementing, 60RefreshMenu method

implementing, 35, 61

Ssamples

adding menu items, 75C++ applications, 85debug mode, 97executing DFC functionality, 93

SaveActiveDocument methodimplementing, 36

ShowBusyCursor methodimplementing, 37

ShowDefaultCursor methodimplementing, 38

Ttroubleshooting

issues, 83

UUpdateActiveDocumentArguments

methodimplementing, 38


Documents

EMC Documentum ApplicationConnectorsSDK Documentum® ApplicationConnectorsSDK Version6 DevelopmentGuide P/N300­005­257 EMCCorporation CorporateHeadquarters: Hopkinton,MA01748‑9103

EMC Documentum ApplicationConnectorsSDK Documentum® ApplicationConnectorsSDK Version6 DevelopmentGuide P/N300005257 EMCCorporation CorporateHeadquarters: Hopkinton,MA01748‑9103