EMC Documentum Application Connectors Software Development Kit

Transcription

1 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide EMC Corporation Corporate Headquarters: Hopkinton, MA

2 Legal Notice Copyright EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED "AS IS." EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS 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. Adobe and Adobe PDF Library are trademarks or registered trademarks of Adobe Systems Inc. in the U.S. and other countries. All other trademarks used herein are the property of their respective owners. Documentation Feedback Your opinion matters. We want to hear from you regarding our product documentation. If you have feedback about how we can make our documentation better or easier to use, please send us your feedback directly at [email protected]

3 Table of Contents Preface... 9 Chapter 1 Overview Introduction Architecture Configuring and customizing WDK and WDK applications Chapter 2 Installing and Setting Up the Documentum Application Connectors Software Development Kit Installing Documentum Application Connectors SDK Installed folders and files Chapter 3 Quick Start General procedure for creating and integrating an application connector with your application Creating an application connector Initializing and cleaning up your application connector Calling the application connector from your application Chapter 4 Implementing Your Application Connector Provider General procedure for implementing your MyAppIntegrationProviderBase class Implementing the InitializeAppIntegration method Implementing the ActiveDocumentArguments property Implementing the ActiveDocumentFilePath property Implementing the ActiveDocumentModifiedSinceLastSave property Implementing the ActiveDocumentObjectId property Implementing the ActiveWindowHandle property Implementing the Close method Implementing the CloseActiveDocument method Implementing the DefaultDocumentFormat property Implementing the DoAbout method Implementing the DoOpenDocument method Implementing the MenuBar property Implementing the OpenedRepositoryDocumentCount property Implementing the RefreshMenu method Implementing the SaveActiveDocument method Implementing the ShowBusyCursor method EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 3

4 Table of Contents Implementing the ShowDefaultCursor method Implementing the UpdateActiveDocumentArguments method Chapter 5 Handling Events Overview AppConnectorEventServer scenarios Unanswered broadcast query event dispatch flow Answered broadcast query event dispatch flow Approved state transition broadcast event dispatch flow Vetoed state transition broadcast event dispatch flow WDK events Chapter 6 Creating and Modifying the Documentum Menu Introduction Building the Documentum menu Calling the SetCompanyMenuName and SetCompanyName methods Implementing the BuildMenu method Implementing the BuildMenuState method Implementing the DestroyMenu method Implementing the DestroyMenuState method Implementing the RebuildMenu method Implementing the RefreshMenu method Removing menu items from all applications Modifying menu items for all applications Adding custom menu items to all applications Restricting menu items to specific applications Chapter 7 Customizing and Creating Application Connector Components and Actions Overview List of Application Connectors components and actions Creating new application connector components and actions appintgcontroller component Client environment qualifier in the WDK application Sample Introduction Procedure Chapter 8 Deploying Your Application Connector Overview Installing with an MSI or InstallShield installer Installing with a non-msi or non-installshield installer Chapter 9 Debugging Application Connector Execution Setting logging options Assembly Requirements Chapter 10 Troubleshooting EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

5 Table of Contents Chapter 11 Chapter 12 Creating Application Connectors That Integrate with C++ or Visual Basic 6 Applications Introduction Overview Creating application connectors that integrate with C++ applications Creating your application connector Creating your MyAppConnectorEventClient Modifying your main frame class Executing Documentum Foundation Class Functionality from Your Application Connector Introduction Overview Procedure Appendix A Sample Applications Running in debug mode EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 5

6 Table of Contents List of Figures Figure 1. Documentum Application Connectors SDK Architecture Figure 2. Application Connector, Webtop, Repository Relationship Figure 3. DAC SDK.NET Runtime Assemblies and Runtime Service Structure Figure 4. Event Dispatching Interaction Diagram Figure 5. Unanswered Broadcast Query Event Dispatch Flow Figure 6. Answered (True) Broadcast Query Event Dispatch Flow Figure 7. Approved State Transition Broadcast Event Dispatch Flow Figure 8. Vetoed State Transition Broadcast Event Dispatch Flow Figure 9. Application Connector standard menu Figure 10. MDITextEditorSampleAppConnector solution architecture EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

7 Table of Contents List of Tables Table 1. Application Connectors menu configuration elements Table 2. Appintgcontroller <dispatchitems> elements Table 3. Required pages in appintgcontroller component definition EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 7

8 Table of Contents 8 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

9 Preface This document describes how to use the Documentum Application Connectors Software Development Kit to enable Windows desktop applications to access and manipulate objects in Documentum repositories. Intended Audience The audience of this manual is intended to be Windows developers who are not familiar with Documentum. Revision History Revision Date December 2014 Description Initial publication EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 9

10 Preface 10 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

11 Chapter 1 Overview These topics are described: Introduction, page 11 Architecture, page 11 Configuring and customizing WDK and WDK applications, page 13 Introduction You use the Documentum Application Connectors Software Development Kit (DAC SDK) to create EMC Documentum Application Connectors that enable Windows applications, such as rich editors, to check in and check out files from Documentum repositories (as well as many other tasks, such as searching repositories) through a combination of a.net client assemblies and runtime services, and components running on EMC Documentum WDK-based application server applications (for example, Webtop). EMC Documentum has used the DAC SDK to create its application connectors for these Microsoft Office applications: Word, Excel, PowerPoint, and Outlook. From version 6.7, DAC SDK supports Microsoft.NET Framework version 2.0 instead of Microsoft.NET Framework version 1.1. Architecture DAC SDK is a collection of.net assemblies and runtime services that your application uses through an application connector that you develop. Your application initializes your application connector, which creates a Documentum menu in your application. From that point on, users can use the Documentum menu to check in files from their local machine into Documentum repositories as well as many other task, including checking out files from and searching repositories. When users choose menu items or your application posts events (such as when a file is opened), logic in your application connector is called. Figure 1, page 12 shows that your application uses DAC SDK in the same way that Excel, Word, PowerPoint, and Outlook use DAC SDK. That is, DAC SDK is a generic layer of code that both your application connector and each Microsoft Office application connector use. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 11

12 Overview Figure 1. Documentum Application Connectors SDK Architecture Figure 2, page 12 shows that when your application needs to manipulate files in a repository, it calls the 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 DAC SDK depends on the.net framework; it also shows that DAC SDK consists of runtime assemblies and runtime services. 12 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

13 Overview Figure 3. DAC SDK.NET Runtime Assemblies and Runtime Service Structure Configuring and customizing WDK and WDK applications The EMC Documentum Web Development Kit Development Guide contains detailed information on configuring and customizing WDK and WDK applications. The Microsoft.NET Framework Developer Center contains more information on.net development. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 13

14 Overview 14 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

15 Chapter 2 Installing and Setting Up the Documentum Application Connectors Software Development Kit The EMC Documentum Application Connectors SDK Release Notes contains the system requirements information. Installing Documentum Application Connectors SDK To install DAC SDK, double-click the EMC Documentum Application Connectors SDK.msi file and follow the instructions. Installed folders and files.net assemblies, supporting DLLs and runtime services that are shared across all installed application connectors are, by default, installed in: C:\Program Files\Documentum\AppConnector These DAC SDK runtime services are installed. Credential Manager Event Server Locale Manager The Credential Manager and Locale Manager processes are automatically started after installation completes. To view these processes, open the Task Manager s Processes tab. The Event Server is started when an application connector is initialized. To support application connector development, another set of.net assemblies and supporting DLLs are installed, by default, into: C:\Program Files\EMC Documentum Application Connectors SDK <version> EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 15

16 Installing and Setting Up the Documentum Application Connectors Software Development Kit This folder contains the sample applications executables, assemblies, configuration files, and manifest files. It also contains these subfolders: Developer Help: contains the EMC Documentum 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 2008 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 your company. Note: The Webtop URL is saved to the application connector s app.config filein the <host> element. For example: <wdkapplocalsettings version="1.0"> <wdkapplocalinfo... > <host> </wdkapplocalsettings> 4. To log into a Documentum repository, choose Documentum > Login As and enter your user name, 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 the Documentum Application Connectors SDK. 16 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

17 Chapter 3 Quick Start This chapter includes these topics: 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 20 Calling the application connector from your application, page 23 General procedure for creating and integrating an application connector with your application To 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 application connector, page In the appropriate locations in your application, call the initialization and cleanup methods in your MyConnect class. 3. Copy the TextEditorApp.exe.config file to your application executable s directory, and change the TextEditorApp portion of TextEditorApp.exe.config to your application s name (for example, MyApp.exe.config) EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 17

18 Quick Start Specify these values for your MyAppIntegrationProvider and MyMenuProvider classes: <appintegrationsettings version="1.0"> 1 <appintegrationinfo name="mycompanyappconnectorformyapp" 2 type="integrationprovider, 3 MyAppIntegrationProviderNamespace, 4 Version= , 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= , 11 Culture=neutral, 12 PublicKeyToken=a289a5c6e19bab4f" >... </menusettings> 1 MyCompanyAppConnectorForMyApp is a string that identifies your MyAppIntegrationProvider class and 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 for MyAppIntegrationProvider. For example: MyCompany.AppConnector.TextEditorAppIntg. TextEditorAppIntegrationProvider. 3 MpAppIntegrationProviderNamespace is the namespace of MyAppIntegrationProvider. For example: MyCompany.AppConnector.TextEditorAppIntg 4 Version of your assembly that contains the MyAppIntegrationProvider class. 5 Default culture of your assembly that contains the MyAppIntegrationProvider class defines the default 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 will be compromised. 7 MyCompanyMenuProviderForMyApp is a string that identifies your MyMenuProvider class and matches 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 for MyMenuProvider. For example: MyCompany.AppConnector.TextEditorAppIntg.MenuProvider. 9 MyMenuProviderNamespace is the namespace of MyMenuProvider. For example: MyCompany.AppConnector.TextEditorAppIntg 10 Version of your assembly that contains the MyMenuProvider class. 11 Default culture of your assembly that contains the MyMenuProvider class. 12 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 will be compromised. 18 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

19 Quick Start 4. Make a copy the TextEditorApp.exe.log4net.config file in the Documentum directory, change the TextEditorApp portion of its name to your application s name, and change the param element s file 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 the TextEditorApp 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 scoping uses) in your application onlyand not other application connectors create a string identifying your 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 same application 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 connector 1. Create a new application in Visual Studio 2008 or any other development tool that supports.net 2.0-based development. 2. Copy the Documentum folder to your application s directory. The Documentum folder is in the DAC SDK installation directory, which is, by default: C:\Program Files\EMC Documentum Application Connectors SDK <version> 3. Add references to these DAC SDK assemblies: Documentum.AppConnector.Application Documentum.AppConnector.Application.Interfaces Documentum.AppConnector.Logging Documentum.AppConnector.Provider Documentum.AppConnector.Provider.Interfaces EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 19

20 Quick Start Documentum.AppConnector.Utility Documentum.Interop.AdvHosting Documentum.Interop.EventServer log4net Except for the Documentum.Interop.EventServer assembly, which is located in the AppConnector folder, all these assemblies are located in the Documentum folder of your application s executable folder. 4. Implement a MyConnect class that contains the application connector initialization and cleanup methods that your application calls. See Initializing and cleaning up your application connector, page Implement a MyAppIntegrationProvider class that contains the core logic of your application connector. See Chapter 4, Implementing Your Application Connector Provider. As a part of the initialization process, the MyAppIntegrationProvider class expects an object that represents your application. This object is a bridge encapsulating your editor-specific programming model. For example, the Microsoft Office programming model has an Application object that allows access to other objects (for instance, menu bar, open documents) and events that 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.cs files of the TextEditorApp sample application. If your application s programming model does not have an object that represents your application and 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 a MyMenuProvider class that creates and manages the Documentum menu in your application. See Chapter 6, Creating and Modifying the Documentum Menu. Initializing and cleaning up your application connector You create a MyConnect 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 the System.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); 20 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

21 Quick Start 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 method retrieves the configuration file name. 2 The System.Runtime.Remoting.RemotingConfiguration.Configure.NET method configures the remoting 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; try 3 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) try 4 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 provider class. 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 current AppIntegrationProviderManager factory indicated by the Current property. The Create method takes your application connector name as a parameter. Your application connector name is specified as an INTEGRATION_WITH_YOUR_APP constant in your MyAppAppConstants class for constants. The INTEGRATION_WITH_YOUR_APP constant value must be the same as the appintegrationinfo element s name attribute value in your application connector s app.config file. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 21

22 Quick Start For example, the TextEditorAppConstants class (in the TextEditorAppConstants.cs file) has this constant 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 the TextEditorAppConnector 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> 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 the MyAppIntegrationProvider instance s reference to null. For example: public void CloseYourAppAppIntegration() if (MyAppAppIntegrationProvider!= null) MyAppAppIntegrationProvider.MenuProvider.DestroyMenu(false); MyAppAppIntegrationProvider.Close(); MyAppAppIntegrationProvider = null; 22 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

23 Quick Start Calling the application connector from your application 1. In your application, add a reference to your application connector. 2. Create an instance of the MyConnect class. 3. Implement the code to initialize your application connector when your application starts by calling your initialization method in the MyConnect class. 4. Implement the code to terminate and cleanup your application connector when your application terminates by calling your cleanup method in the MyConnect class. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 23

24 Quick Start 24 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

25 Implementing Your Application Connector Provider Chapter 4 This chapter includes these topics: 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 28 Implementing the ActiveDocumentModifiedSinceLastSave property, page 29 Implementing the ActiveDocumentObjectId property, page 30 Implementing the ActiveWindowHandle property, page 30 Implementing the Close method, page 31 Implementing the CloseActiveDocument method, page 31 Implementing the DefaultDocumentFormat property, page 32 Implementing the DoAbout method, page 32 Implementing the DoOpenDocument method, page 33 Implementing the MenuBar property, page 33 Implementing the OpenedRepositoryDocumentCount property, page 34 Implementing the RefreshMenu method, page 34 Implementing the SaveActiveDocument method, page 35 Implementing the ShowBusyCursor method, page 37 Implementing the ShowDefaultCursor method, page 37 Implementing the UpdateActiveDocumentArguments method, page 37 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 25

26 Implementing Your Application Connector Provider General procedure for implementing your MyAppIntegrationProviderBase class To instantiate your application connector and respond to events: 1. You create MyAppIntegrationProvider 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 28. ActiveDocumentModifiedSinceLastSave see Implementing the ActiveDocumentModifiedSinceLastSave property, page 29. ActiveDocumentObjectId see Implementing the ActiveDocumentObjectId property, page 30. ActiveWindowHandle see Implementing the ActiveWindowHandle property, page 30. Close see Implementing the Close method, page 31. CloseActiveDocument see Implementing the CloseActiveDocument method, page 31. DefaultDocumentFormat see Implementing the DefaultDocumentFormat property, page 32. DoAbout see Implementing the DoAbout method, page 32. DoOpenDocument see Implementing the DoOpenDocument method, page 33. InitializeAppIntegration see Implementing the InitializeAppIntegration method, page 26. MenuBar see Implementing the MenuBar property, page 33. OpenedRepositoryDocumentCount see Implementing the OpenedRepositoryDocumentCount property, page 34. RefreshMenu see Implementing the RefreshMenu method, page 34. SaveActiveDocument see Implementing the SaveActiveDocument method, page 35. ShowBusyCursor see Implementing the ShowBusyCursor method, page 37. ShowDefaultCursor see Implementing the ShowDefaultCursor method, page 37. UpdateActiveDocumentArguments see Implementing the UpdateActiveDocumentArguments method, page 37. Implementing the InitializeAppIntegration method The InitializeAppIntegration method is used to initialize your application connector. To implement the InitializeAppIntegration method: 1. Override the InitializeAppIntegration method. 26 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

27 Implementing Your Application Connector Provider 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). try 1 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 method returns the IMenuProvider instance. The constant that identifies the IMenuProvider interface is 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 the method 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 s System.EventHandler, GotFocus (which occurs when the control receives focus), with the Txt_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); else 3 this.refreshmenu(applicationconstants.repository_content, true); 4 this.refreshmenu(applicationconstants.any_content, true); EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 27

28 Implementing Your Application Connector Provider 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 is refreshed 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 any menu 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 repository is enabled. 6. Return true after code in the previous step to indicate that an instance of the IMenuProvider interface has been successfully created. Implementing the ActiveDocumentArguments property The ActiveDocumentArguments property is used to return the active document s arguments that are passed 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 ActiveDocumentArguments get 1 return base.getdocumentarguments(filepath); 1 Using the AppIntegrationProviderBase GetDocumentArguments method, returns the file s arguments based on its file s path, filepath. filepath is a class variable that holds the file path of the active document. When a repository document is opened, the application connector provider saves its path. To retrieve that value, use the AppIntegrationProviderBase GetArgumentValue method. For example: filepath = base.getargumentvalue(eventargs, ApplicationConstants. FILENAME_WITH_PATH); Implementing the ActiveDocumentFilePath property The ActiveDocumentFilePath property is used to return the active document s path. 28 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

29 Implementing Your Application Connector Provider 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 ActiveDocumentFilePath get 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 about the filepath class variable, see Implementing the ActiveDocumentArguments property, page 28. Implementing the ActiveDocumentModifiedSinceLastSave property The ActiveDocumentModifiedSinceLastSave property is used to determine whether the active document 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 has been modified. For example: public override bool ActiveDocumentModifiedSinceLastSave get 1 return parent.dirty; 1 dirty is a variable, which represents a Boolean value, on the parent object, which represents your application object. You must use a similar call that returns a Boolean that signifies whether the active document has been modified. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 29

30 Implementing Your Application Connector Provider Implementing the ActiveDocumentObjectId property The 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 ActiveDocumentObjectId get 1 return base.getobjectid(filepath); 1 Using the AppIntegrationProviderBase GetObjectId method, returns the files object ID based on its files path, filepath. filepath is a class variable that holds the file path of the active document. For more information about the filepath class variable, see Implementing the ActiveDocumentArguments property, page 28. Implementing the ActiveWindowHandle property The 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 get 1 return parent.handle; 1 Handle is a variable, which represents an IntPtr (a.net data typebasically, a raw handlewhich could 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 active window handle. 30 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

31 Implementing Your Application Connector Provider Implementing the Close method The 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 the base implementation classes. For example: public override void Close() base.cleanup(); 3. Call your applications close and cleanup code after calling the AppIntegrationProviderBase Cleanup method. Implementing the CloseActiveDocument method The 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 many repository 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 repository documents are open in your application. 2 Call the RemoveOpenDocumentArguments method passing the filepath parameter, which deletes all 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 first parameter to ApplicationConstants.REPOSITORY_CONTENT and the second parameter to False so that the menu is refreshed to disable all menu items related to repository content. For example: RefreshMenu(ApplicationConstants.REPOSITORY_CONTENT, false); EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 31

32 Implementing Your Application Connector Provider Implementing the DefaultDocumentFormat property This property is used to return the default document format for your application s documents. This default 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 method The 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 WDK application 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 its constructor and passing the current WDK applications host name, and then call System.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 an IWdkAppLocalProvider object representing an interface to the current WDK application, and then call the IWdkAppLocalProviders Host property to return the URL of the WDK application host. 32 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

33 Implementing Your Application Connector Provider Implementing the DoOpenDocument method The DoOpenDocument method is called when a document is opened in your application; that is, an open-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 your application and consequently, the args parameter might be empty. Set the documentopenedviaintegration field in your AppIntegrationProviderBase class to true, so that other methods can check to see if the documentopenedviaintegration field is False, and, if so, call 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 property The 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 MenuBar get 1 return parent.menu; EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 33

34 Implementing Your Application Connector Provider 1 Menu is a variable, which represents an object, 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 application s menubar. Implementing the OpenedRepositoryDocumentCount property The OpenedRepositoryDocumentCount property is used to return the number of repository documents 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 your application. For example: public override int OpenedRepositoryDocumentCount get 1 return openedrepodocumentcount; 1 openedrepodocumentcount is a class variable that holds the number of open repository documents. This variable is incremented by 1 every time a repository document is opened (in the DoOpenDocument method) and decremented by 1 every time a repository document is closed (in the CloseActiveDocument method). Implementing the RefreshMenu method The 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 RefreshMenu method 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 34 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

35 Implementing Your Application Connector Provider menu manager object (IMenuProvider interface type), which implements your custom menu and handles its events. The context parameter specifies the context (for example, a repository document) of the document to which 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 enabled parameter 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 to occur before or after this call. Implementing the SaveActiveDocument method The SaveActiveDocument method is used to save the active document in your application to the local file system. To implement the SaveActiveDocument method: 1. Override the SaveActiveDocument method. 2. Check whether the caller has specified a folder called the target folder in which to save the document. The target folder could be the current folder, in which case the caller will not have specified any value for the target folder. For example: 1 if (targetfolder.length == 0) try 2 System.IO.StreamWriter sw = new System.IO.StreamWriter(filePath); sw.writeline(parent.txt.text); sw.flush(); sw.close(); 3 parent.dirty = false; catch (UnauthorizedAccessException e) logger.info("cannot save the file because of an access violation", e); return filepath; catch(exception e) logger.error("failed to save active document", e); return string.empty; return filepath; 4 else 5 string activedocumentname = System.IO.Path.GetFileName(filePath); if (activedocumentname.length == 0) activedocumentname = documentname; EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 35

36 Implementing Your Application Connector Provider 6 filepath = System.IO.Path.Combine(targetFolder, activedocumentname); int delimpos = filepath.indexof("_tmp_"); int dotposition = filepath.lastindexof(applicationconstants.dot); String part1 = "", part2 = ""; if (dotposition > 0) if(delimpos > 0) part1 = filepath.substring(0, delimpos); else part1 = filepath.substring(0, dotposition); part2 = filepath.substring(dotposition); else filepath = part1; filepath = part1 + "_tmp_0" + part2; try System.IO.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 folder is the current folder. 2 Use the System.IO.StreamWriter object to save the active document to the path specified in the filepath variable. 3 dirty is a variable, which represents a Boolean value, on the parent object, which represents your application object. You must use a similar call that returns a Boolean signifying whether the active document 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 method on the filepath class variable. 6 Construct the target file path for the active document by calling the System.IO.Path.Combine method 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. For example: parent.dirty = false; 36 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

37 Implementing Your Application Connector Provider dirty is a variable, which represents a Boolean value, on the parent object, which represents your application object. You must use a similar call that returns a Boolean signifying whether the active document has been modified. Implementing the ShowBusyCursor method The 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 method The 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 the UpdateActiveDocumentArguments method The 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 state changes (for example, after checkin). EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 37

38 Implementing Your Application Connector Provider 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 information about the filepath class variable, see Implementing the ActiveDocumentArguments property, page EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

39 Chapter 5 Handling Events This chapter includes these topics: Overview, page 39 AppConnectorEventServer scenarios, page 41 WDK events, page 44 Overview Your application connector and WDK application rely on your application to dispatch events. Your application connector might also want to receive events from another part of the system. The event server (EventServer.exe) contains the AppConnectorEventServer object that is responsible for registering and unregistering client interest in events and for dispatching events to specific or registered client event sinks. The AppConnectorEventServer object is created in the AppIntegrationProviderBase class during initialization and can be accessed through the NotificationServer property. Figure 4, page 40 shows the relationship between the AppConnectorEventServer (abbreviated as "AC Event Server), its clients, and event sinks. Each process (bounded by a dotted line) can contain multiple callers and multiple event sinks. An AppConnectorEventServer client can be a caller of its registered event sink (abbreviated as "ES) exposing a EventSink interface to be called by a AppConnectorEventServer worker thread, or both a caller and an event sink. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 39

40 Handling Events Figure 4. Event Dispatching Interaction Diagram When a client registers an event sink with the AppConnectorEventServer, the AppConnectorEventServer associates that sink with one or more event categories. Henceforth, the AppConnectorEventServer dispatches events to that event sink based on the event categories associated with that sink. A sink can be registered and unregistered multiple times. For example, your sink might initially be interested in only a few event categories, but once it receives a particular event code, 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 called and a pointer to its EventSink implementation is passed. In return, the AppConnectorEventServer returns a cookie. This cookie should be stored as a data member by the client object. It must be passed to 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 plans for the actual event to occur (that is, puts itself into a pending state). Any event code that is associated with a state transition event type must also be associated with both notification and cancellation event types. Figure 7, page 43 and Figure 8, page 44 illustrate the connection among these event types depending on the outcome of an event dispatch involving a state transition. An event sink should react only to notifications and cancellations it receives. Therefore, the AppConnectorEventServer returns back to its caller following the creation of worker threads, 40 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

41 Handling Events 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 fully completed (or even begun) before control returns to it from the AppConnectorEventServer. AppConnectorEventServer clients can expect the standard response message format returned by AppConnectorEventServer from SendEvent to be: "[who] what (for example, "[Microsoft Word] did not respond in time to the specified event.). The AppConnectorEventServer establishes who from the sink name provided previously in RegisterEventSink. The sinkname parameter should have the same value as the Name property of the event sink being registered. If the response is internal or no sink name has been provided, who would become "Documentum AppConnectorEventServer. what is established either 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 scenarios The diagrams in this section illustrate the flow of control between a client, the AppConnectorEventServer, and registered event sinks during a broadcast event. Although there are more variations than those represented here, you should be able to deduce how the flows operate in other variations based on these diagrams. SendEvent expects an input Long value for pid. Pid should be set by the caller to its process ID via the Win32 API GetCurrentProcessId. The AppConnectorEventServer passes pid from SendEvent to the HandleEvent method of the appropriate event sinks. A signaled event sink can then compare the incoming pid with its own process ID to see if the event came from the same process. Such information is usefulfor example, if process-specific caching is involved. All event sinks as well as the AppConnectorEventServer expose read-only PID properties that allow other elements of the event dispatching 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. Figure 5. Unanswered Broadcast Query Event Dispatch Flow EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 41

42 Handling Events Key points from Figure 5, page 41 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 offending event 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 42 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 define responsemsg for the Client to display additional information. AppConnectorEventServer stops its broadcast upon finding an answer of true and immediately returns 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 use responsemsg. 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. 42 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

43 Handling Events Figure 7. Approved State Transition Broadcast Event Dispatch Flow Key points from Figure 7, page 43 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 sent this time as a notification Follow-up notification initiated by the Client allows each sink to clear its pending mode (which indicates that the event has indeed occurred). Vetoed state transition broadcast event dispatch flow This section describes the flow of an implicitly or explicitly vetoed state transition broadcast event. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 43

44 Handling Events Figure 8. Vetoed State Transition Broadcast Event Dispatch Flow Key points from Figure 8, page 44 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 from HandleEvent 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 events The 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 JSP page using control tags. Thse types of WDK events can be fired: Browser events, which communicate client-side JavaScript execution WDK action completion events, which communicate server-side state changes The 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 the client application and display the component or container start page. This event is not 44 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

45 Handling Events needed in 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 by AppConnectors, an aievent is fired and passed to the AppConnectors. The actual event name is passed in a <dmf:argument> element that is contained within <dmf:fireclientevent>. The AppConnectors 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 is included 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 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 45

46 Handling Events 46 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

47 Chapter 6 Creating and Modifying the Documentum Menu This chapter includes these topics: Introduction, page 47 Building the Documentum menu, page 50 Removing menu items from all applications, page 60 Modifying menu items for all applications, page 60 Adding custom menu items to all applications, page 62 Restricting menu items to specific applications, page 62 Introduction In your application, you create a Documentum menu with menu items that perform functions to access objects in repositories. DAC SDK provides a standard Documentum menu as shown in Figure 9, page 49. You can change the name of the top-level menu item, remove and modify these standard menu items as well as add your own custom menu items. Standard menu items and their functions include: New from Template: Create a new file from a template stored in a repository. Open: Open a file from a repository. Save: Save the updated file to the repository without prompting and keep the file checked out (also known as silent checkin). Save As: Save a file with a different name or to a different location. Checkin: Check the updated file into the repository without keeping the file on the local machine. Search Repositories: Search a repository. Properties: Display the attributes of a file. Locations: Display the locations of a file in a repository. Versions: Display all the versions of a file in a repository. Renditions: Display all the renditions of a file in a repository. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 47

48 Creating and Modifying the Documentum Menu Lifecycle > Promote: Move a file to the next state in a lifecycle. Lifecycle > Demote: Move a file back to the previous state in a lifecycle. Lifecycle > Attach: Add a file to the initial state in a lifecycle. Lifecycle > Suspend: Pause a file in a lifecycle by moving it to a Suspend state. Lifecycle > Detach: Remove a file from a lifecycle. Lifecycle > Resume: Restart 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 a file (unlock). Insert > Web Link: Insert a link to a file in the repository at the current cursor location. Insert > Object: Insert a file from the repository at the current cursor location. Send to > Quick Flow: Send the file to a distribution list. Send > Recipient as Web Link: Send the 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. 48 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

49 Creating and Modifying the Documentum Menu Figure 9. Application Connector standard menu The menu is constructed from a global menu, which is configured from your application 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 the Documentum Application Connectors SDK, for your convenience). At runtime, the appintgmenubar_menugroup.xml file is downloaded to the local machine when your application connector is initialized and is updated on demand; that is, the appintgmenubar_menugroup.xml file is downloaded whenever its content changes. When a user chooses a menu item, a native modal dialog window that hosts a browser control is launched and the corresponding WDK component or action specified in the appintgmenubar_menugroup.xml file is called. The browser control loads an action URL for the selected 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 on the user session and the selected object. This action map enables or disables menu items based on the user 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 Documentum menu, page 50. To remove menu items from the Documentum menu, see Removing menu items from all applications, page 60. To modify menu items on the Documentum menu, see Modifying menu items for all applications, page 60. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 49

50 Creating and Modifying the Documentum Menu To add custom menu items to the Documentum menu, see Adding custom menu items to all applications, page 62 To add or remove menu items to and from specific applications only, and apply menu item modifications to specific applications only, see Restricting menu items to specific applications, page 62. Building the Documentum menu You build the Documentum menu by subclassing the MenuProviderBase class and implementing its abstract methods. To build the Documentum menu: 1. Subclass the MenuProviderBase class. For example: public class MyMenuProvider : MenuProviderBase where MyMenuProvider is the name of your class. You will need to write less code by subclassing the MenuProviderBase class, because the MenuProviderBase 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. In MyMenuProvider, override and implement these abstract methods from the MenuProviderBase class (see the corresponding section for instructions on implementing each method): SetCompanyMenuName and SetCompanyName: Sets the company name for the top-level menu name and the titles of message and dialog boxes. See Calling the SetCompanyMenuName and SetCompanyName methods, page 51. BuildMenu: Builds the custom menu bar. See Implementing the BuildMenu method, page 51. BuildMenuState: Builds the data structure that represents menu item states for a newly opened repository file. See Implementing the BuildMenuState method, page 54. DestroyMenu: Destroys the custom menu bar. 50 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

51 Creating and Modifying the Documentum Menu See Implementing the DestroyMenu method, page 56. DestroyMenuState: Destroys menu item states associated with a file being closed. See Implementing the DestroyMenuState method, page 57. RebuildMenu: Rebuilds the menu from the updated application server side menu definition file. See Implementing the RebuildMenu method, page 58. RebuildMenuState: Rebuilds menu item states associated with a particular file. See Implementing the RebuildMenu method, page 58. RefreshMenu: Refreshes the state of the custom menu items. See Implementing the RefreshMenu method, page 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 60. To add menu items, see Modifying menu items for all applications, page 60. To modify menu items, see Adding custom menu items to all applications, page 62. To restrict menu items to specific applications, see Restricting menu items to specific applications, page 62. Calling the SetCompanyMenuName and SetCompanyName methods To display the company name as the top-level menu name, call the SetCompanyMenuName method. To set the company name in the titles of message and dialog boxes, call the SetCompanyName method. For example, to set the top-level menu item name to "itop : base.setcompanymenuname("&itop"); Note: The & enables the letter that follows it.as the keyboard shortcut. For example, to set the company name in the titles of message and dialog boxes to "itop : base.setcompanyname("itop"); 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, and initialize the data structure that holds menu definition information. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 51

52 Creating and Modifying the Documentum Menu 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 that your application can manage. For example, this code sample converts the menu data structure to a Windows form menu data structure: 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, is created. 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 a MenuInfo object. The first array item is the top-level main menu item (for example, Documentum): menuinfo = (MenuInfo)menuInfoList[0]; 4. Add a top-level menu item (that is, Documentum) if none exists in the menubar object. For example: if (toplevelpopupmenuitem == null) 1 toplevelpopupmenuitem = new MenuItemWithId(menuInfo.menuCaption); toplevelpopupmenuitem.menuid = menuinfo.menuid; mainmenubar.menuitems.add(toplevelpopupmenuitem); 1 The MenuItemWithId class is a private data structure that represents a menu item based on a menu item ID and that includes a caption as a property. 5. 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 child elements in appintgmenubar_menugroup.xml. For example, the menucaption property is mapped to the <actionmenuitem> element s <value> element. 52 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

53 Creating and Modifying the Documentum Menu 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 = new MenuItemWithId(menuInfo.menuCaption); newmenuitemwithid.menuid = menuinfo.menuid; menuitem.menuitems.add(newmenuitemwithid); if (menuinfo.ispopupmenu == false) newmenuitemwithid.click += new EventHandler(MenuItem_Click); EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 53

54 Creating and Modifying the Documentum Menu 1 GetParentIndex method is a private method that returns the index of the parent menu item based on the child menu item. 2 The MenuItemWithId class is a private data structure that represents a menu item based on a menu item 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 the appropriate dialog based on the URL. 6. To specify each menu items initial state (that is, enabled or disabled), call your overridden RefreshMenu 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, make this 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. For example, when a document is opened from a repository, you build and store the menu state for this 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 can have multiple document windows open at the same time), you need to use a menustatehashtable object (a hash table) to keep the association between each open repository document and the corresponding 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 and path or the window handle. Example 6-1. Using the menustatehashtable object For example: 54 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

55 Creating and Modifying the Documentum Menu 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; EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 55

56 Creating and Modifying the Documentum Menu 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 new document is created or an existing document is opend from the local file system, the menu item state is represented by a list stored in menustatehashtable under the ApplicationConstants.DEFAULT_KEY constant 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 menu item 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 you do 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 the ApplicationConstants.VALID constant; if it is, then the menu item is enabled; if not, then the menu item 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 table and 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 to call this method when a document in your application closesif your application can have multiple documents 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 building the new, updated menu bar. 56 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

57 Creating and Modifying the Documentum Menu 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 the Documentum menu. 2 After deleting all the menu items from the Documentum menu, delete the Documentum menu item. 3 Cleans up an internal data structure that contains the menu bar information. This data structure is used when building the menu. Implementing the DestroyMenuState method You implement the DestroyMenuState method to destroy a menu s menu item states by the menustatehashtable key. For example, you would call this method when you close a document window. 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 values simpler by making it lowercase and deleting all the forward and double backward slashes. See the TextEditorApp sample application source code for the exact implementation. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 57

58 Creating and Modifying the Documentum Menu Implementing the RebuildMenu method You implement the RebuildMenu method to rebuild the Documentum menu; for example, you would want to rebuild the Documentum menu when a new appintgmenubar_menugroup.xml file is downloaded 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 from Webtop, call the private method, UpdateMenuDefinitionFile, then send and event notification to other open applications so that they can update their Documentum menu with the updated appintgmenubar_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 a reference to an instance of IAppIntegrationProvider. 5. To rebuild the menu state for all open documents, call GetOpenedDocumentsArguments on integrationprovider, and then BuildMenuState for each open document. 6. To refresh the menu state, call RefreshMenu with the parameter values (assuming that a file has already 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 would want 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 to ApplicationConstants.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 items depending on the context. The parameters passed to the method are the context of the document state and whether the menus in that state are to be enabled or disabled. For example, when a file has been checked out from a repository, you want to enable menu items (for example, check in) that interact with the repository. So, you pass the ApplicationConstants.REPOSITORY_CONTENT value in the context parameter and TRUE in the enabled parameter. In the switch/case logic, you have a case for 58 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

59 Creating and Modifying the Documentum Menu ApplicationConstants.REPOSITORY_CONTENT that enables any menu item that has an enabledcontext 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 else 7 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 current context, that is, ApplicationConstants.REPOSITORY_CONTENT. 4 FindMenuButton is a private method that returns a MenuItemWithId object based on the menu item ID and its parent index. 5 The menu item is disabled. The button object is a.net object that represents a menu item. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 59

60 Creating and Modifying the Documentum Menu 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 menu state hash table. 8 StripSeparatorsAndMakeLowercase is a private method that strips out the forward slashes and back slashes from a path and makes all the characters lowercase. Removing menu items from all applications To 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 using the 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 applications To modify menu items that call application connector components and actions in Webtop, you modify elements and attributes in a <menugroup> element in /webcomponent/config/library/appintgmenubar/appintgmenubar_menugroup.xml. Table 1, page 60 describes the appintgmenubar_menugroup.xml file 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 appintgcontroller component definition that provides a specific success or failure page. If the menu item does not have an entry in the appintgcontroller component definition, the default success and failure pages are used. Table 1. Application Connectors menu configuration elements Element <menugroup> Description Content authoring application menu item group. The id attribute specifies the menu configuration ID. Contains one <contentsourcemenuitem>, one or more <actionmenuitem>, <nlsbundle>, and optional <menu> and <menuseparator/> elements. 60 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

61 Creating and Modifying the Documentum Menu Element <contentsourcemenuitem> <contentsourcemenuitem><value> <menuseparator/> <menu> <actionmenuitem> <nlsid> <aidynamic> Description Not used Not used Displays a separator between menu items Optional. Set of <actionmenuitem> elements that form a submenu for the <menu> item. To remove an entire submenu, remove the <menu> element. Content authoring application menu item that contains <aidynamic>, <name>, <value>, and either <action> or <component> plus optional elements that are described below. To remove an item from the menu, remove the <actionmenuitem> element. Optional key to a localized label Specifies the way in which the state of the authoring application affects the menu item: no_dynamic: item always available aiconnection: item enabled if connected to repository any_content: item enabled if repository or external document is open <name> <value> <action> <component> <arguments><argument> repository_content: item enabled if repository content is open Specifies the menu item name Contains a string value or <nlsid> element that resolves a string label for the menu item Maps a menu item to a WDK action. Either <action> or <component> must be present in the <actionmenuitem> element. Maps a menu item to a WDK component. Either <action> or <component> must be present in the <actionmenuitem> element. The values of the name and value attribute on the <argument> element are passed to the WDK action. The name must be a defined parameter for the action, and the value must be a valid value for that parameter. This parameter can have a hardcoded value (for example, startworkflowdrilldown, or a dynamic value, indicated by the string, contextvalue, which will be substituted at runtime with the valid context value. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 61

62 Creating and Modifying the Documentum Menu Adding custom menu items to all applications To add a custom menu item: 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 using the 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. xml file. See Table 1, page 60 for a description of the child elements that comprise the <actionmenuitem> element. 4. Save the appintgmenubar_menugroup.xml file. 5. Restart the application server and your client application. Restricting menu items to specific applications You can restrict menu items to specific applicationsthat is, remove them from or add them to specific applications. For example, if your users use lifecycles for Word documents, but not for Excel and PowerPoint documents, then you can remove the Lifecycle menu items from Microsoft Excel and PowerPoint, but keep it in Microsoft Word. To restrict a menu item to specific 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 using the 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 of your Webtop installation. If you have not created an application name string for your application, add it using the General procedure for creating and integrating an application connector with your application, page 17 starting with Step To remove a menu item for specific applications only, in the Webtop custom/config/ appintgmenubar_menugroup.xml, enclose the <actionmenuitem> element in a <filter> element that negates (using the not keyword) the desired application name strings, separated by commas. 62 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

63 Creating and Modifying the Documentum Menu 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 Template menu item for the TextEditor and myapp applications: <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 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 add the Create New from Template menu item for the TextEditor and myapp applications: <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. 7. Restart the application server and your client application. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 63

64 Creating and Modifying the Documentum Menu 64 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

65 Chapter 7 Customizing and Creating Application Connector Components and Actions This chapter includes these topics: Overview, page 65 List of Application Connectors components and actions, page 65 appintgcontroller component, page 68 Creating new application connector components and actions, page 66 Overview All Documentum menu selections in the content authoring application are dispatched through the Application Connectors controller component, appintgcontroller. This component launches an action or component via a URL and adds messages and return listeners so that it can return messages, errors or results to the native modal dialog window. If authentication is required, the appintgcontroller component jumps to the appintgcontrollerlogin component. All Application Connectors components and actions are described in EMC Documentum Web Development Kit and Webtop Reference Guide. List of Application Connectors components and actions All Application Connectors component and action names and configuration files are prepended with the text, appintg. Application Connectors components are: appintgcontroller appintgcontrollerlogin appintghelp appintgnewfromtemplate EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 65

66 Customizing and Creating Application Connector Components and Actions appintgopen appintgopenfrom appintgopenfromcabinetslocator appintgopenfromcategorieslocator appintgopenfromlocatorcontainer appintgopenfrommyfileslocator appintgopenfromrecentfileslocator appintgopenfromsubscriptionslocator appintgsaveascabinets appintgsaveascategories appintgsaveascontainer appintgsaveasmyfiles appintgsaveasrecentfiles appintgsaveassubscriptions Application Connectors actions are: appintgnewfromtemplate appintgopenfrom appintgsaveas Creating new application connector components and actions You can create a completely new component or action or extend an existing one. Extending an existing component or action means that the new component or action inherits the existing component or action s configuration file <component> or <action> element s child elements. Note: Hereafter, a <component> or <action> element s child elements will be called a configuration structure. 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 resembles your new component or acion to the webtop\custom\config directory. 2. Rename the configuration file to the name of your new component or action. 66 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

67 Customizing and Creating Application Connector Components and Actions 3. To extend an existing component or action, add the extends attribute to the component or action element and specify the relative path to the component or action that you want to extend. For example, your new component, appintgnewcomponent extends the appintgnewfromtemplate component: <component id="appintgnewcomponent" extends="appintgnewfromtemplate:webcomponent/ config/library/appintgnewfromtemplate/appintgnewfromtemplate_component.xml"> 4. Specify <component> or <action> configuration structures. See the EMC Documentum Web Development Kit and Webtop Reference Guide and EMC Documentum Web Development Kit Development Guide for the specific 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 any unmodified 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 that you want to inherit, you must specify them as well. In this case, the parameter, existingparam, already exists in the parent configuration file, but because you modified contenttype, you must you must also specify 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 application connector, use the <filter> element. See Restricting menu items to specific applications, page To display the new component s own success and failure JSP pages, add the new component s success and failure JSP pages in the appintgcontroller component configuration file. For example, for the appintgnewmenu menu item, the shownewcomponentpage success page is specifiedbut 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 execute and display your component. See Restricting menu items to specific applications, page 62 and Adding custom menu items to all applications, page 62. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 67

68 Customizing and Creating Application Connector Components and Actions appintgcontroller component The appintgcontroller component consists of the AppIntgController servlet and JavaScript. This component 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 values as defined in the appintgcontroller component definition are used. Enables login: Checks for connection requirement and, if required, sets a menu version event and forces login. Provides the loginas action that disconnects from all repositories and allows the 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 the success or failure page after action completion. Adds context arguments to a menu action map that is downloaded to the client. If the menu item does not have a <dispatchitems> entry, the action or component is dispatched and 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 is defined 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 (in apptgcontroller_component.xml) that specifies a success page: <dispatchitems> <item> <name>appintgnewfromtemplate</name> <type>action</type> <successpage>opendocumentevent</successpage> </item> </dispatchitems> Table 2, page 68 describes the configuration elements for dispatching actions or components. Table 2. Appintgcontroller <dispatchitems> elements Element <item>.<name>.<type> Description Contains one of each: <name>, <type>, and either <page> or <successpage> Contains the name of a menu action, if the type is action. Contains the name of an event, if the type is page. Specifies the type of menu item to dispatch: action or page 68 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

69 Customizing and Creating Application Connector Components and Actions Element.<page>.<successpage>.<failurepage> Description Specifies a named child element of <pages>, to launch a page Optional. Specifies a named child element of <pages>, to launch a success page after action completes. If this element is not present, the default success page in <pages><success> is used. Optional. Specifies a named child element of <pages>, to launch a failure page after action fails. If this element is not present, the default success page in <pages><success> is used. When the user selects a menu item, the appintgcontroller builds a URL, and the requested page loads in a modal dialog window that hosts a browser control within your application. If the menu item maps to an action, the WDK action dispatcher performs the action and returns the success or failure JSP page to the modal dialog window. If the menu item maps to a component, the WDK component dispatcher returns 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 component definition. For example, the appintgopendocumentevent item specifies a value of opendocumentevent for the <successpage> element. The element <pages>.<opendocumentevent> defines this page and has a value of /webcomponent/library/appintgcontroller/appintgopendocumentevent.jsp, which specifies the path to the page to be loaded. The following default pages are defined within the <pages> element of the component definition. If an item does not specify a success or failure page, then the default page is used: Table 3. Required pages in appintgcontroller component definition Element <start> <disconnect> <success> <failure> Description Specifies the path to an error handler page that is loaded if the action or component is not dispatched Specifies the path to a page that is used to disconnect existing sessions and return to the controller for new login. This page invalidates the HTTP session. Specifies the path to the default success page that is loaded after the action completes successfully Specifies the path to the default faliure page that is loaded after the action fails to complete EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 69

70 Customizing and Creating Application Connector Components and Actions Client environment qualifier in the WDK application The clientenv qualifier is introduced to enable component configuration based on the client environment. 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 second option). For example: 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 given client session when the server times out. The clientenv qualifier can be used as a filter in component definitions to specify a different set of JSP pages depending on the environment. For example, the changepassword component definition uses the value of appintg and not appintg to present different pages depending on whether the user is in an Application 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 the clientenvpanel control. This control is used to show or hide UI elements based on the runtime clientenv context. The client environment is specified as the value of the environment attribute. For example, the checkin component JSP page has a clientenvpanel control that is rendered only in 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 example above (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> 70 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

71 Customizing and Creating Application Connector Components and Actions JSP fragments can also be defined, so that a component JSP page includes fragments that are dispatched based on the client environment. 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 Delete menu item calls the standard Webtop delete action. Procedure 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 using the 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 the appintgmenubar_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/config directory 6. In the Webtop custom\config\appintgcontroller_component.xml, extend the original file by using the extends attribute on the <component> element: <component id="appintgcontroller" extends="appintgcontroller:/ webtop/config/appintgcontroller_component.xml"> EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 71

72 Customizing and Creating Application Connector Components and Actions 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 this JSP code: <%@ page contenttype="text/html; charset=utf-8" %> <%@ page errorpage="/wdk/errorhandler.jsp" %> <%@ page import="com.documentum.webcomponent.library.appintgcontroller. AppIntgController"%> <%@ taglib uri="/web-inf/tlds/dmform_1_0.tld" prefix="dmf" %> <%@ taglib uri="/web-inf/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, 72 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

73 Customizing and Creating Application Connector Components and Actions MyCompany.AppConnector.TextEditorAppIntg, Version= , 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= , 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 from ActionProviderBase by creating this code in a CustomNotificationHandler.cs file: using System; using log4net; using Documentum.AppConnector.Logging; using Documentum.AppConnector.Application; namespace MyCompany.AppConnector.TextEditorAppIntg public 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); EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 73

74 Customizing and Creating Application Connector Components and Actions break; default: break; 11. Restart the application server and your client application. 74 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

75 Chapter 8 Deploying Your Application Connector This chapter includes these topics: Overview, page 75 Installing with an MSI or InstallShield installer, page 75 Installing with a non-msi or non-installshield installer, page 76 Overview DAC SDK includes a merge module that an MSI or InstallShield installer can use. If you use another installer, manual instructions for the files and services that need to be installed are provided. You need to install these services: EventServer.exe: This service contains the AppConnectorEventServer object that is responsible for registering and unregistering client interest in events and for dispatching events to specific or registered client events sinks. This service is started whenever your client application (to which your application connector is deployed) is instantiated. Documentum.AppConnector.CredentialManager.exe: This service holds user credentials (username, repository information, and so forth) after a user has logged on to the client application connector. This service is started after a user logs on to Windows and remains active until the current Windows session terminates. Documentum.AppConnector.LocaleManager.exe: This service maintains information about the client operating system locale. This service is started after the user logs on to Windows and remains active until the current Windows session terminates. Installing with an MSI or InstallShield installer To deploy your application connector to client machines, your installer must: 1. Add the DAC SDK Common Merge Module. All required DLLs will be installed into C:\Program files\documentum\appconnector. 2. Create theapp_path\documentum folder: where APP_PATH is the path to your application s executable file. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 75

76 Deploying Your Application Connector 3. Install these files: MyCompany.AppConnector.CustomAppIntg.dll into APP_PATH path. CustomApp.exe.config into the APP_PATH path and the APP_PATH\Documentum folder. CustomApp.exe.manifest (if you create one) into the APP_PATH path. Copy all DLLs from C:\Program Files\EMC Documentum Application Connectors SDK <version>\documentum into the APP_PATH\Documentum folder. where: MyCompany is the name of your company. Custom is the name of your application connector. 4. Register the MyCompany.AppConnector.CustomAppIntg.dll and the Documentum.Interop. AdvHosting.dll using the regasm tool: set AssemblyRegistrar=%WINDIR%\Microsoft.NET\Framework\v \regasm.exe "%AssemblyRegistrar%" /verbose %APP_PATH%\Documentum\Documentum.Interop.AdvHosting.dll "%AssemblyRegistrar%" /verbose %APP_PATH%\ MyCompany.AppConnector. CustomAppIntg.dll where: MyCompany is the name of your company. Custom is the name of your application connector. 5. Add this registry entry key for your application connector: HKEY_LOCAL_MACHINE\SOFTWARE\MyCompany\AppConnector\Installed\ MyAppConnector with these values: App.config:REG_SZ: MyAppConnector.exe.config InstallPath:REG_EXPAND_SZ:MyAppConnectorInstallPath where: MyCompany is the name of your company. MyAppConnector is the name of your application connector. MyAppConnectorInstallPath is the path to where your application connector is installed. Use the HKEY_LOCAL_MACHINE predefined key to make your application connector available to all users on the machine or HKEY_CURRENT_USER to make your application connector available to only the user that installs your application connector. Note: See the EMC Documentum Application Connectors SDK.msi wrapper for more information about how to create the folder structure, deploy files, and add registry entries. Installing with a non-msi or non-installshield installer To deploy your application connector to client machines, your installer must: 1. Install these files into the C:\Program Files\Documentum\AppConnector folder: atl90.dll 76 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

77 Deploying Your Application Connector Documentum.AppConnector.Configuration.dll Documentum.AppConnector.CredentialManager.exe Documentum.AppConnector.CredentialManager.exe.config Documentum.AppConnector.CredentialManager.exe.log4net.config Documentum.AppConnector.Credentials.dll Documentum.AppConnector.DataProtection.dll Documentum.AppConnector.DataProtection.Interfaces.dll Documentum.AppConnector.Locale.dll Documentum.AppConnector.LocaleManager.exe Documentum.AppConnector.LocaleManager.exe.log4net.config Documentum.AppConnector.Logging.dll Documentum.AppConnector.Preferences.dll Documentum.AppConnector.Provider.dll Documentum.AppConnector.Provider.Interfaces.dll Documentum.Interop.EventServer.dll EventServer.exe ICSharpCode.SharpZipLib.dll ICSharpCode.SharpZipLib-license.txt log4net.dll log4net-license.txt Microsoft.mshtml.dll msvcp90.dll msvcr90.dll SDK Common Custom Actions.dll sdk common custom actions.installstate Microsoft.VC90.ATL.manifest Microsoft.VC90.CRT.manifest 2. Create the APP_PATH\Documentum folder: where APP_PATH is the path to your application s executable file. 3. Install these files: MyCompany.AppConnector.customAppIntg.dll into APP_PATH path. CustomApp.exe.config into the APP_PATH path and the APP_PATH\Documentum folder. CustomApp.exe.manifest (if you create one) into the APP_PATH path. Copy all DLLs from C:\Program Files\EMC Documentum Application Connectors SDK <version>\documentum into the APP_PATH\Documentum folder. where: MyCompany is the name of your company. Custom is the name of your application connector. 4. Register the MyCompany.AppConnector.CustomAppIntg.dll and the Documentum.Interop. AdvHosting.dll using the regasm tool: set AssemblyRegistrar=%WINDIR%\Microsoft.NET\Framework\v \regasm.exe "%AssemblyRegistrar%" /verbose %APP_PATH%\Documentum\Documentum.Interop.AdvHosting.dll "%AssemblyRegistrar%" /verbose %APP_PATH%\ MyCompany.AppConnector. CustomAppIntg.dll EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 77

78 Deploying Your Application Connector where: MyCompany is the name of your company. Custom is the name of your application connector. 5. Register EventServer.exe: echo Registering the Event Server with COM... %APPCONNECTOR_PATH%\EventServer.exe /RegServer 6. Set the registry values for CredentialManager and LocaleManager, so they start up whenever the user logs into Windows: [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run] Documentum\AppConnector\Documentum.AppConnector.LocaleManager.exe Documentum\AppConnector\Documentum.AppConnector.CredentialManager.exe 7. Add this registry entry key for your application connector: HKEY_LOCAL_MACHINE\SOFTWARE\MyCompany\AppConnector\Installed\ MyAppConnector with these values: App.config:REG_SZ: MyAppConnector.exe.config InstallPath:REG_EXPAND_SZ:MyAppConnectorInstallPath where: MyCompany is the name of your company. MyAppConnector is the name of your application connector. MyAppConnectorInstallPath is the path to where your application connector is installed. Use the HKEY_LOCAL_MACHINE predefined key to make your application connector available to all users on the machine or HKEY_CURRENT_USER to make your application connector available to only the user that installs your application connector. 8. Start CredentialManager.exe and LocaleManager.exe during installation. 78 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

79 Chapter 9 Debugging Application Connector Execution This chapter includes these topics: Setting logging options, page 79 Setting logging options Documentum Application Connectors use the open source logger, log4net, which you can find at Logging is configured in a file specific to your application and to the Application Connectors services and processes. The log files for Documentum Application Connectors services and Microsoft Office Application Connectors are: Application Connectors Credential Manager: Documentum.AppConnector.CredentialManager.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.config Microsoft Outlook: outlook.exe.log4net.config The Documentum Application Connectors default configuration is: <?xml version="1.0" encoding="utf-8"?> <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" /> <staticlogfilename value="true" /> <layout type="log4net.layout.patternlayout,log4net"> <conversionpattern value="%d [%t] %-5p %c [%x] - %m%n" /> </layout> EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 79

80 Debugging Application Connector Execution </appender> <root> <level value="all" /> <appender-ref ref="rollinglogfileappender" /> </root> </log4net> Assembly Requirements Because the sample application, TextEditorApp, depends on other assemblies, you must set the the start application setting in Visual Studio 2008 to the TextEditorApp.exe installed in the drive C:\Program Files\EMC Documentum Application Connectors SDK <version> folder. 80 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

81 Chapter 10 Troubleshooting 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 Manager and Documentum Locale Manager. Verify that a menu configuration file has downloaded to the client, for example, %ProgramFiles%\MyApp\Documentum\Webtop\appintgmenubar_menugroup.xml. If this file is not present, stop and start the Locale Manager Windows process. MyApp is the path that you have chosen for your application. Check the log4net log files for errors. If none are found, declare a more verbose logging level and restart 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 Manager is not running. Check this in the Windows Task Manager and restart the process 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 and components, or custom components that extend them, are not supported with AppConnectors. User credentials are not being saved as expected You may be required to re-enter your login credentials. Check the processes running in Windows Task Manager to see if the Credential Manager process is running. To manually start the process, navigate to C:\Program Files\Documentum\AppConnector and double click Documentum.AppConnector.CredentialManager.exe. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 81

82 Troubleshooting Localized UI not displayed The Documentum Application Connector Locale Manager displays the localized menu. To start this program, double-click it in its default location: C:\Program Files\Documentum\AppConnector\Documentum.AppConnector.LocaleManager.exe. 82 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

83 Chapter 11 Creating Application Connectors That Integrate with C++ or Visual Basic 6 Applications This chapter includes these topics: Introduction, page 83 Overview, page 83 Creating application connectors that integrate with C++ applications, page 84 Introduction Documentum Application Connectors can work with.net, C++, and Visual Basic 6 applications. If your application is written in C++ or Visual Basic 6, you can create a COM component that works as a bridge between your application connector and application. To create an application connector and COM object that work with a C++ application, follow the MDITextEditorSampleApp solution, which consists of a sample C++ application and C# application connector. Overview The MDITextEditorSampleAppConnector solution implements Microsoft ATL Connection Points. For more 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 Connect class in the MDITextEditorSampleApp solution uses the ComSourceInterfacesAttribute class). Figure 10, page 84 shows that events in the Connect class of the MyCompany.AppConnector. MDITextEditorAppIntg sample application connector cause the AppConnectorEventClient class to call into the C++ application CMainFrame class. It also shows that calls from the CMainFrame class go through the _connect interface to the Connect class, which then calls either MDITextEditorAppIntegrationProvider or MenuProvider. In ATL connection points terms, the Connect class is the source that calls the IAppConnectorConnect outgoing interface. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 83

84 Creating Application Connectors That Integrate with C++ or Visual Basic 6 Applications Figure 10. MDITextEditorSampleAppConnector solution architecture When the MDITextEditorApp application starts up, the Documentum menu is added to it in this sequence of execution: 1. The MDITextEditorApp Application class initializes the CMainFrame class, which instantiates the AppConnectorEventClient and Connect classes. The AppConnectorEventClient class implements the IAppConnectorConnect interface. Through the IAppConnectorConnect interface, the Connect class s outgoing events are fired. 2. When the CMainFrame class is initialized, it calls the Connect class s InitAppIntegration method through the _connect interface. 3. The Connect class instantiates the MDITextEditorAppIntegrationProvider and MenuProvider classes. 4. Then, the MenuProvider s menu info is sent via IAppConnectorConnect interface to the CMainFrame class, which builds the Documentum menu. Creating application connectors that integrate with C++ applications This 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 the MDITextEditorSampleAppConnector solution. See the MDITextEditorSampleAppConnector solution for the complete source code. 84 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

85 Creating Application Connectors That Integrate with C++ or Visual Basic 6 Applications Creating your application connector 1. Follow the steps in Creating an application connector, page Immediately before the beginning of your MyAppIntegrationProvider 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, each programming element that should not be visible to COM clients must be explicitly hidden by setting the ComVisible attribute to false. For more information about the ComVisible attributes, see frlrfsystemruntimeinteropservicescomvisibleattributeclasstopic.asp. 3. In your MyAppIntegrationProvider class, add the CLSCompliant attribute immediately before the beginning of the InitializeAppIntegrationand set the attribute to false Because 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 Language Specification must be explicitly identified by setting the CLSCompliant attribute to false. For more information about the CLSCompliant attribute, see 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 your MyAppIntegrationProvider class, add this code: Connect parent; Because your programming model does not have an application object as the methodology used in Creating an application connector, page 19 assumes, your application connector uses 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 InitializeAppIntegration method right before the return(true) line, add this code: Note: In order for VS.NET intellisense to recognize these events, you must first add the appropriate 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 a region similar to this one and generate your own GUID: #region Source interface definition [InterfaceType(ComInterfaceType.InterfaceIsIDispatch)] [Guid("8A8FBEE2-70CA-41b AF6411B61AF3")] public interface IAppConnectorConnect [DispId(1)] void CreateMenuItem(int menuitemid, int parentid, bool ispopup, string caption); EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 85

86 Creating Application Connectors That Integrate with C++ or Visual Basic 6 Applications [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 of this interface are called by Connect class, which is the source. The AppConnectorEventClient class is the listener and is located in your main frame class file. 7. Create a Connect class declaration and corresponding COM interface definition similar to this one and generate your own GUID: [ComSourceInterfaces(typeof(IAppConnectorConnect))] [ClassInterface(ClassInterfaceType.AutoDual)] [Guid("1B7D7AA4-216B-4ad0-B653-C499B7DC497A")] public class Connect 8. In the Connect class, implement these methods corresponding delegates and events that are fired by the IAppConnectorConnect implementation: FireCreateMenuItem FireGetActiveWindowHandle FireSetMenuItemState FireDoOpenDocument FireGetActiveDocumentModifiedSinceLastSave FireSaveDocument FireCloseActiveDocument 9. In the Connect class, implement these methods and corresponding delegates and events that are 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 your MenuProvider class, add the ComVisible attribute and set it to false. 86 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

87 Creating Application Connectors That Integrate with C++ or Visual Basic 6 Applications Because the default setting on the entire assembly level for the ComVisible attribute is true, each programming element that should not be visible to COM clients must be explicitly hidden by setting the ComVisible attribute to false. For more information about the ComVisible attributes, see frlrfsystemruntimeinteropservicescomvisibleattributeclasstopic.asp. 12. In addition to the standard methods (as described in Building the Documentum menu, page 50) to implement in the MenuProvider class, also implement the HandleCustomMenuEvent method. Creating your MyAppConnectorEventClient 1. 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(); EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 87

88 Creating Application Connectors That Integrate with C++ or Visual Basic 6 Applications DispEventUnadvise((IUnknown*)pDotNetObject); 5. Implement these methods, which are basically pass-thru calls to the main frame class methods that actually implement the functionality: OnCreateMenuItem OnGetActiveWindowHandle OnSetMenuItemState OnDoOpenDocument OnGetActiveDocumentModifiedSinceLastSave OnSaveDocument OnCloseActiveDocument Modifying your main frame class 1. 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 AppConnectorEventClient classes: 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(""); 88 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

89 Creating Application Connectors That Integrate with C++ or Visual Basic 6 Applications 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 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 89

90 Creating Application Connectors That Integrate with C++ or Visual Basic 6 Applications 90 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

91 Chapter 12 Executing Documentum Foundation Class Functionality from Your Application Connector This chapter includes these topics: Introduction, page 91 Overview, page 91 Procedure, page 92 Introduction You can execute functionality in the Documentum Foundation Classes (DFC) from your application connector by creating a WDK component that uses DFC functionality to call a repository; then, you can call that component from your application connector. Overview The Application Connector SDK does not install DFC; instead, DFC is installed with Webtop on the 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 Manage Documentum business objects Manage audit trail logging Perform queries and transformations on XML documents EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 91

92 Executing Documentum Foundation Class Functionality from Your Application Connector 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) configuration For a complete description of DFC functionality, see the EMC Documentum Foundation Classes Development Guide. The MyCompany.AppConnector.TextEditorAppIntg sample contains functionality that calls DFC. This sample creates a Run Query menu item on the Documentum menu that calls a WDK component on Webtop, which executes a DQL query against a repository. Procedure 1. Build a menu as you would any other menu. See the MenuProvider.cs file for examples of the values that are specified for the Run Query menu item. Although the sample application connector generates this menu item dynamically, you should follow the best practice of specifying the menu item in the appintgmenubar_menugroup.xml file. In the MenuProvider.cs file, the DQL query is specified as a value of the MenuInfo class s dispatcharguments 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 the value 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 the webcomponent\config\library\appintgxdql\appintgxdql_component.xml configuration file and the 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); 92 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

93 Executing Documentum Foundation Class Functionality from Your Application Connector IDfXmlQuery queryapi = s_clientx.getxmlquery(); queryapi.init(); queryapi.setdql(dqlquery); queryapi.execute(idfquery.df_exec_query, this.getdfsession()); String queryresult = null try 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 the MyCompany.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); EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 93

94 Executing Documentum Foundation Class Functionality from Your Application Connector 94 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

95 Appendix A Sample Applications This appendix includes these topics: Running in debug mode, page 95 Running in debug mode To run the sample applications in debug mode, the sample application projects must run the sample application executables installed by the Documentum Application Connectors SDK installer and the applicaton connector 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 application connector 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 on the 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 is C:\Program Files\EMC Documentum Application Connectors SDK <version>\texteditorapp.exe. 6. Click OK. 7. Compile the application connector project (which is the active project) and copy the assembly and debug symbols file to the same location as the sample application s installed executable. For example, copy the MyCompany.AppConnector.TextEditorAppIntg.DLL and MyCompany.AppConnector.TextEditorAppIntg.pdb files to C:\Program Files\EMC Documentum Application Connectors SDK <version>. EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 95

96 Sample Applications 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" "dac_sdk_install_path" copy /y "$(TargetDir)MyAppIntg.pdb" "dac_sdk_install_path" where: MyAppIntg is the name of your application connector (for example, MyCompany.AppConnector.TextEditorAppIntg) dac_sdk_install_path is the path to your Documentum Application Connectors SDK installation (for example, C:\Program Files\EMC Documentum Application Connectors SDK <version>). 8. Press F5 to run the sample application in debug mode. 96 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide

97 Index A ActiveDocumentArguments property implementing, 28 ActiveDocumentFilePath property implementing, 28 ActiveDocumentModifiedSinceLastSave property implementing, 29 ActiveDocumentObjectId property implementing, 30 ActiveWindowHandle property implementing, 30 AppConnectorEventServer scenarios, 41 appintgcontroller description, 68 application connector events, WDK, 44 application connector components appintgcontroller, 68 creating new, 66 list of, 65 overview, 65 application connectors authentication, 70 architecture Documentum Application Connectors SDK, 11 B BuildMenu method implementing, 51 BuildMenuState method implementing, 54 C C++ applications procedure for integrating Application Connectors with, 84 samples, 83 calling application connectors procedure, 23 cleaning up application connectors, 20 clientenv for application connectors, 70 Close method implementing, 31 CloseActiveDocument method implementing, 31 creating application connectors procedure, coding, 19 procedure, general, 17 D debugging debug mode, 95 logging options, 79 DefaultDocumentFormat property implementing, 32 deploying application connectors, 75 DestroyMenu method implementing, 56 DestroyMenuState method implementing, 57 DoAbout method implementing, 32 Documentum menu adding custom menu items to all applications, 62 building, 50 modifying menu items for all applications, 60 overview, 47 removing menu items from all applications, 60 restricting menu items to specific applications, 62 EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide 97

98 Index samples, 71 DoOpenDocument method implementing, 33 E events AppConnectorEventServer scenarios, 41 overview, 39 F files installed, 15 I InitializeAppIntegration method implementing, 26 initializing application connectors, 20 installation default path for application connector development files, 15 default path for shared files, 15 documentation, 16 installed folders and files, 15 procedure, 15 sample source files, 16 testing, 16 L logging setting options, 79 M MenuBar property implementing, 33 MyAppIntegrationProviderBase class implementing, 26 O OpenedRepositoryDocumentCount property implementing, 34 overview application connector components, 65 Documentum Application Connectors SDK, 11 Documentum menu, 47 events, 39 R RebuildMenu method implementing, 58 RefreshMenu method implementing, 34, 58 S samples adding menu items, 71 C++ applications, 83 debug mode, 95 executing DFC functionality, 91 SaveActiveDocument method implementing, 35 ShowBusyCursor method implementing, 37 ShowDefaultCursor method implementing, 37 T troubleshooting issues, 81 U UpdateActiveDocumentArguments method implementing, EMC Documentum Application Connectors Software Development Kit Version 6.8 Development Guide