Executing Documentum Foundation Class Functionality from

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

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 theEMC Documentum Foundation Classes Development Guide.

The MyCompany.AppConnector.TextEditorAppIntg sample contains functionality that calls DFC. This sample creates aRun Querymenu 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 theRun Querymenu 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";

queryis 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);

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); }

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 selectSet as StartUp Project.

2. Right-click on the application connector project (for example, MyCompany.AppConnector. TextEditorAppIntg) and selectProperties.

The application connector project is the startup project for debug mode. 3. In the dialog box, clickConfiguration Properties>Debugging.

4. Set theDebug Modefield to Program and clickApply.

5. Click in theStart Applicationfield, 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. ClickOK.

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>.

Sample Applications

To automate this step as part of the post-build process:

a. Right-click the sample application connector project, and selectProperties>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:

MyAppIntgis the name of your application connector (for example, MyCompany.AppConnector.TextEditorAppIntg)

dac_sdk_install_pathis the path to your Documentum Application Connectors SDK installation (for example, C:\Program Files\EMC Documentum Application Connectors SDK <version>).

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

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, 37

In document EMC Documentum Application Connectors Software Development Kit (Page 91-98)