# Installation and Upgrade Guide

# Troubleshooting

This section provides reference information for troubleshooting problems you might encounter when you use the Documentum CS. It includes the following topics:

- Reviewing Log Files.
- Modifying Configuration Files.
- Diagnosing Unexpected Results.

## Reviewing Log Files

If you encounter problems with crawl jobs, you can review the job logs provided through the portal’s Automation Service Utility. For details, refer to the portal’s online help or to the Administrator Guide for AquaLogic Interaction.

If you encounter problems with the Documentum CS, you can use ALI Logging Spy to analyze portal communication.

The Documentum CS also logs communication on the Documentum CS host computer. To analyze logs specific to the Documentum CS processes, review the logs in <RemoteServer>/ptdctmcws/5.5/settings/logs.

## Modifying Configuration Files

If you encounter error messages or logs that indicate misconfiguration in the Documentum CS config.xml file, you can modify the config.xml file to correct syntax or mismatched values.

The following table describes the syntax and values for config.xml configuration parameters.

Table 6-1 Configuration Parameters
Configuration (sample value in bold) | Value Description
--- | ---
baseURL | The URL for the Documentum CS application on the Documentum CS host computer. When you configure AquaLogic User Interaction applications, always specify the fully qualified domain name for hosts to avoid host and domain name resolution mismatches.
<clickthroughAuthType>1</clickthroughAuthType> <trustedUserName></trustedUserName> <trustedPassword></trustedPassword> <trustedDomain></trustedDomain> | The clickthroughAuth type parameter determines what type of authentication to use during click-through. The following values are valid: 1 = User Preferences 2 = Basic Authentication 3 = Trusted Authentication 4 = Admin Preferences We recommend you set the accessLevelMapping value to 3 (read) if the clickThroughAuthType is either 4 or 5. See Configuring Security for Document Discovery for details on accessLevelMapping. For Trusted authentication (option #3), credentials must be supplied below. The password must be encrypted. Follow the instructions on http://<RemoteServer>/dctmcws/web/install/index.html to generate an encrypted password.
<accessLevelMapping>2</accessLevelMapping> | The accessLevelMapping maps the Documentum access level setting to the portal’s access privilege setting. Documentum users who have an access level setting that is equal to or higher than the value configured here will receive Read access in the portal. The default setting is 2 which means that Documentum users with Browse access or higher will receive Read access in the portal. Browse users will not, however, be able to click through and read the file contents because the Documentum CS verifies their credentials upon click-through and will not return the document unless they have Read access in Documentum. This is how the portal mimics the Documentum Browse-level security. An important dependency of this functionality is that userCredentialClickThrough must be set to true (see note above regarding setting this parameter to 3 if userCredentialClickThrough is set to false). Valid values for this parameter are: 2 = Browse 3 = Read
<preferredRenditionFormat>default</preferredRenditionFormat> | Set the preferredRenditionFormat to the desired format for the document to be returned during click-through. The portal supports the following formats: default (or blank): The document's native format pdf: Acrobat PDF msw8: Microsoft Word 97/2000 crtext: Text (Windows) The setting is “preferred” because the Documentum CS will return the native format for documents if pdf/msw8/crtext is not available. This option only applies if userCredentialClickThrough is set to true.

## Diagnosing Unexpected Results

The following table summarizes cases in which users encountered unexpected results with the Documentum CS. You can use this table as a reference for particular issues you might encounter or as a guide for troubleshooting any similar problems you might encounter.

Table 6-2 Troubleshooting
Symptom | Solution
--- | ---
HTTP 500 Error on Clickthrough Users have reported that the URL property in a document's Properties page is clickable, but the link returns an error. The URL property is unique as it is clickable in the Document Properties page (accessed by clicking Properties for a document crawled into the portal). This is potentially confusing to users because the value is technical and clicking it results in an HTTP 500 error. | To avoid potential confusion, map the URL property in a content type to an Override Value, such as a space, which will prevent the technical URL from appearing in the Properties page.
Crawl fails with [DM_API_E_NO_SESSION] error: “There are no more available sessions.” | Increase the sessions in server.ini and dmcl.ini. For details, see Advanced Configuration: Tuning Documentum Server..
Port conflict, port in use, BindException | Port numbers for HTTP and HTTPS are configured in <PT_HOME>/ptdctmcws/5.5/settings/config/application.conf. Edit the http and https settings in application.conf to set the value to an available port. The service must be restarted to pick up changes made in the configuration file. Note that changes to a service port number require corresponding changes to any Web service or remote server settings that may reference that port number.
Memory consumption, Out of Memory Errors | The maximum amount of memory, in megabytes, that the service JVM will be allowed to use is controlled by the wrapper.java.maxmemory property, configured in the file <PT_HOME>/ptdctmcws/5.5/settings/config/wrapper.conf. For example, the following line shows a maximum memory setting of 1 GB:
    wrapper.java.maxmemory=1024
The setting corresponds directly to the -Xmx parameter used by the java executable. The default value of this setting in the config file will be adequate for most configurations. For large production configurations, especially those in which the service is installed on a dedicated host machine, this value should be set as high as possible (for example, 1024 or 1536) but should always remain below the amount of physical RAM on the host machine.