h11634|documentum Native Ucf Client Troubleshooting Guide · Documentum Native UCF Client Troubleshooting Guide 5 DFS® UCF Integration Currently, UCF .NET is used with DFS based

White Paper

Abstract

This white paper provides a general overview of EMC Documentum Native UCF client, also known as UCF .NET. It broadly outlines the system requirements for UCF .NET client, the architecture of Documentum Foundation Services (DFS) UCF integration and the logging and configuration options available for UCF .NET integration. It also describes the common problems that customers encounter, and provides suggestions to troubleshoot those problems. October 2013

EMC® DOCUMENTUM® NATIVE UCF® CLIENT TROUBLESHOOTING GUIDE

2 Documentum Native UCF Client Troubleshooting Guide

Copyright © 2013 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. VMware is a registered trademarks or trademarks of VMware, Inc. in the United States and/or other jurisdictions. All other trademarks used herein are the property of their respective owners. Part Number h11634


Table of Contents

Executive summary.................................................................................................. 4

Audience ............................................................................................................................ 4

Introduction to UCF® .NET ....................................................................................... 4

System Requirements .............................................................................................. 4

DFS® UCF Integration .............................................................................................. 5

DFS UCF .NET Integration Architecture ................................................................................. 5

UCF .NET Client Installation................................................................................................. 6

Deploying UCF.NET Test Build to DFS Web Application ........................................................ 6

Removing UCF .NET Client for Debugging Purposes ............................................................. 7

Configuration and Logging ....................................................................................... 8

UCF Server .......................................................................................................................... 8

Logging .......................................................................................................................... 8

Tracing ........................................................................................................................... 8

UCF .NET Installer Logging .................................................................................................. 8

UCF .NET Client ................................................................................................................... 8

UCF .NET Client logging ................................................................................................... 8

Client configuration options ........................................................................................... 9

Common UCF .NET Problems and Resolutions........................................................... 9

UCF Client Configuration Not Populating In ucf.client.config.xml ......................................... 9

Large Content Transfer Failure .......................................................................................... 10

Server Error .................................................................................................................. 11

Client Error ................................................................................................................... 11

Conclusion ............................................................................................................ 12


Executive summary This white paper provides a basic overview of UCF .NET client. It briefly

describes the system requirements for the end user machine. It provides a basic understanding of the Documentum Foundation Services (DFS) and UCF integration and explains its architecture. It also provides details about UCF .NET client installation and describes the steps to deploy UCF .NET test binaries to DFS application.

In addition, it provides the steps to remove UCF .NET client for debugging purposes and explains the configuration and logging options available for UCF .NET installer, UCF .NET client and UCF server.

It also describes common problems that customers encounter while using UCF .NET client for content transfer and also provides suggestions for resolving those issues.

Audience

This white paper is intended for external circulation which will include technical support teams as well as customers. The reader is expected to be familiar with the basic functionalities, installation and configuration of the products discussed here.

Introduction to UCF® .NET UCF .NET is a full duplication of UCF java client functionality which is intended for Windows client machines with .NET framework installed and for customers who do not want to use JVM (Java Virtual Machine) on their client machine. UCF .NET client is implemented in C# and the client engine’s installation and deployment are performed using Microsoft ClickOnce technology.

System Requirements UCF .NET can be installed on a system with .NET framework 3.5 SP1 installed for versions prior to D7 and .NET framework 4.0 for D7.

UCF .NET is supported in the following Windows platforms.

1. Windows XP (32 bit/64 bit)

2. Vista (32 bit/64 bit)

3. Windows 2008 (32 bit/64 bit)

4. Windows 7 (32 bit/64 bit)

For Web based use of UCF .NET, the client system should have IE7 or IE8 (32 bit/ 64 bit) installed. Currently, there are no live products which use UCF .NET for browser based applications.


DFS® UCF Integration Currently, UCF .NET is used with DFS based product deployments. DFS UCF .NET integration requires DFS services (version 6.7 or later) on the server side.

Note: EMC Documentum Foundation Services (DFS) is a set of technologies that enables service-oriented programmatic access to EMC Documentum Content Server platform and related products. DFS is a service layer over a Documentum Foundation Classes (DFC) client which connects to one or more Documentum repositories managed by a Content Server.

DFS UCF .NET Integration Architecture

The figure below illustrates the overview of DFS UCF integration architecture.

Figure 1 DFS UCF integration architecture overview

The components involved in UCF content transfer are UCF client, DFS client, UCF server, DFS server and Content Server®; Optionally ACS®, BOCS® and DMS® take part in content transfer as well.

1. The connection between UCF .net client runtime process (Emc.Documentum.Ucf.Client.Impl.exe) and ACS/BOCS serves for content transfer

2. The connection between UCF Client and UCF Server serves for UCF command flow between UCF Server and UCF Client

3. The connection between DFS Client and UCF Client serves for establishing new UCF Client session


UCF .NET Client Installation

Prior to content transfer, UCF .NET client needs to be installed on the end user client. UCF .NET needs UcfLaunchClickOnce.exe to start the UCF client engine on the client machine. The installation happens when establishing a UCF connection using DFS runtime API and it is automatically performed by DFS runtime and .NET ClickOnce.

Note: ClickOnce is a Microsoft technology that enables the user to deploy, install and run a Windows Application. It is a component of Microsoft .NET Framework

The client engine for UCF Java Client is “javaw.exe” process, and for UCF .NET, it is "Emc.Documentum.Ucf.Client.Impl.exe” process.

Deploying UCF.NET Test Build to DFS Web Application

The figure below illustrates the UCF .NET build directory structure.

Figure 2 UCF.NET Test Build Directory Structure

To deploy UCF .NET test build to DFS web application, follow the steps below in the application server where DFS is deployed:

1. Replace the following

a. AppFiles directory

b. Emc.Documentum.Ucf.Client.Impl.application

c. UcfLauncher.cab (for 32 bit)


d. UcfLauncher64.cab (for 64 bit)

in the ems-dfs\ services\ucf directory with the corresponding files in UCF .NET build

2. Replace the following 3 files

a. External.config

b. UcfInstaller.dll

c. UcfLaunchClickonce.exe

in all the directories under ems-dfs\ services directory other than ems-dfs\ services\ucf folder with the corresponding files in UCF .NET build

3. Restart the application server

Removing UCF .NET Client for Debugging Purposes

To remove UCF .NET Client installation completely in the end user machine, follow the steps below:

1. Kill the UCF .NET client runtime process (Emc.Documentum.Ucf.Client.Impl.exe), if it is running

2. Remove the Documentum directory and UcfInstaller directory. (By default it goes to the %userprofile% but can be configured in ucf.installer.config.xml. For locating this file refer the section on “Client Configuration Options”)

3. Delete the ClickOnce App Cache which is located at :

On Windows Vista, Windows 7 and Windows Server 2008:

C:\Users\<username>\AppData\Local\Apps\2.0\ On Windows XP:

C:\Documents and Settings\ <username>\LocalSettings\Apps\2.0\

4. Remove the entries under registry table “HKEY_CURRENT_USER\Software\Classes\Software\Microsoft\Windows\CurrentVersion\Deployment\SideBySide\2.0\Components”

Note: The paths mentioned above in steps 3 and 4 may vary according to the client machine’s configuration


Configuration and Logging

UCF Server

The platforms supported by DFS Server are supported by UCF Server as well. UCF Server exposes its configuration properties to DFS Server at the ems-dfs\WEB-INF\classes\ ucf.server.config.xml

Logging

For debugging purposes, set the log level to DEBUG in place of INFO and add UCF Server package to log4j.properties which is located at ems-dfs\WEB-INF\classes\ log4j.properties as below.

#-----------------UCF Server Logging (added for collecting ucf server logs) ------------- log4j.logger.com.documentum.ucf=INFO, UCF_LOG log4j.appender.UCF_LOG=org.apache.log4j.RollingFileAppender #-- Below mentioned path should be corrected accordingly for non-windows platforms log4j.appender.UCF_LOG.File=C\:/Documentum/logs/UCF_Server.log log4j.appender.UCF_LOG.MaxFileSize=10MB log4j.appender.UCF_LOG.MaxBackupIndex=10 log4j.appender.UCF_LOG.layout=org.apache.log4j.PatternLayout log4j.appender.UCF_LOG.layout.ConversionPattern=%d{ABSOLUTE} %5p [%t] %c - %m%n

UCF server logs can be collected from the configured location as above in the entry log4j.appender.UCF_LOG.File. Here the logs have been configured to be saved at the following location C:\Documentum\logs\UCF_Server.log.

Tracing To enable UCF Server tracing, set the configuration “tracing.enabled” to true in ucf.server.config.xml as below. <option name="tracing.enabled"> <value>true</value> </option> This is not a recommended setting on production systems.

UCF .NET Installer Logging

UCF .NET Client must be installed prior to content transfer. The UCF .NET Client Engine installation logs can be found at %Temp%\installer.log.

UCF .NET Client

UCF .NET Client logging

UCF .NET Client logs are used for diagnosis of content transfer issues. Client logging is enabled on the end user’s machine. For collecting client logs, edit the ucf.client.logging.xml file, located at: <user-home>\Documentum\ucf-


net\<hostname>\shared\config. For this configuration, set the “rootLoggerLevel” in UCFloggerLevels tab as below.

 <UCFloggerLevels rootLoggerLevel="Warn"> <loggers>  </loggers> </UCFloggerLevels>

The maximum logging level for UCF .NET client is “Trace”, by default it is set to “Warn”.(The logging levels are case sensitive. Kindly use the exact as mentioned above). The client logs can be collected from <user-home>\Documentum\Logs directory.

Client configuration options

UCF .NET Client configuration options like the location of logs, viewed folder, etc., can be viewed and configured from the <user-home>\Documentum\ucf-net\<hostname>\shared\config\ucf.client.config.xml. The options in this file can be configured and additional options can be added by editing the file ucf.installer.config.xml located in all the directories under ems-dfs\ services\ other than the ems-dfs\ services\ucf directory. Adding the client configuration option in the ucf.installer.config.xml will populate the configuration in the client machine.

Common UCF .NET Problems and Resolutions

UCF Client Configuration Not Populating In ucf.client.config.xml

UCF client configuration options are configured in the file ucf.installer.config.xml in the UCF Server i.e., DFS Server. These options will be populated in the UCF Client machine in the following location: <user-home>\Documentum\ucf-net\<hostname>\shared\config\ucf.client.config.xml for UCF .NET Client. Since UCF home is different for UCF java client and .NET client, the configuration options need to be separately added or configured in ucf.installer.config.xml for .NET client in the runtime tab for .net and configVersion should be incremented whenever the configuration options are modified as 1.1, 1.2, and so on as below. This option enables the update of client configuration file instead of updating the entire client installation.


<runtime type=".net" href="Emc.Documentum.Ucf.Client.Impl.application"> <defaults> <ucfHome value="$java{user.home}/Documentum/ucf-net"/> <ucfInstallsHome value="$java{user.home}/Documentum/ucf-net"/> <configuration name="com.documentum.ucf" configVersion="1.0"> <option name="temp.working.dir" persistent="true"> <value>$ucf{user.dir}/Temp</value> </option> <option name="logs.dir" persistent="true"> <value>$ucf{user.dir}/Logs</value> </option> </configuration> </defaults> </runtime>

Simply adding the configuration in the runtime for type=”all” will not populate the ucf.client.config.xml for UCF .NET client.

Large Content Transfer Failure

UCF content transfer operation (specifically, import) might fail for files of large size in the range of GBs depending on the network speed and memory available in the client and DFS/UCF server with the following exceptions on both server and client side.


Server Error

Figure 3 Server Error

Client Error

Figure 4 Client Error


If the content transfer operation fails with the above exceptions in client and server for large file transfer, a configurable option “enable.write.stream.buffering” needs to be added to the ucf.installer.config.xml. This configuration is specific to UCF .NET client because content is transferred through HttpWebRequest where buffering creates performance issues in case of large data transfer. Thus, buffering is disabled for large file transfer by adding this configuration as below.

<runtime type=".net" href="Emc.Documentum.Ucf.Client.Impl.application"> <defaults> <ucfHome value="$java{user.home}/Documentum/ucf-net"/> <ucfInstallsHome value="$java{user.home}/Documentum/ucf-net"/> <configuration name="com.documentum.ucf"> <option name="temp.working.dir" persistent="true"> <value>$ucf{user.dir}/Temp</value> </option> <option name="logs.dir" persistent="true"> <value>$ucf{user.dir}/Logs</value> </option> <option name="enable.write.stream.buffering" persistent="true"> <value>false</value> </option> </configuration> </defaults> </runtime>

It should be set to “false” for large file transfer, by default it is set to true. Setting this option to “false” for all content transfer operation might create performance issues since buffering is disabled.

Conclusion This paper has attempted to provide information about the usage of UCF .NET in content transfer in DFS architecture for Windows machine with .NET framework and no JVM. The information provided in the paper gives a detailed explanation of how to collect logs for analysis and in troubleshooting issues.